🏗️ avm-mcp服务器

MCP服务器，用于从二头肌公共注册表中发现和探索Azure验证模块（AVM）。

🎯 概述

此MCP服务器使AI代理和工具能够通过模型上下文协议（MCP）搜索、发现和检索有关Azure验证模块（AVM）的详细信息。它直接连接到Microsoft容器注册表（MCR）和GitHub，以提供最新的模块信息、版本、参数和使用示例。

❓ 为什么选择AVM MCP服务器？

Azure验证模块（AVM）是一组标准化、经过验证且记录良好的基础设施即代码（IaC）模块的集合，用于使用二头肌部署Azure资源。然而，发现正确的模块并理解其参数可能具有挑战性：

探索挑战：有数百个AVM模块可供选择，为您的用例找到合适的模块需要搜索文档
参数复杂性：每个模块都有许多具有特定要求和默认值的参数
版本管理：跟踪整个注册表中的模块版本和更新
文档访问：模块文档分散在GitHub存储库中

此MCP服务器通过以下方式解决了这些挑战：

在所有AVM模块中提供快速、智能的搜索
直接从注册表检索模块版本
提取详细的参数信息和使用示例
使AI代理能够帮助您找到并使用正确的模块

与微软二头肌MCP服务器的比较

微软提供官方二头肌MCP服务器其中包括a ListAvmMetadata 工具。那么，为什么要创建单独的AVM MCP服务器呢？

主要区别

功能	微软二头肌MCP服务器	AVM MCP服务器（本项目）
主要焦点	二头肌语言工具和Azure资源模式	AVM模块发现和文档
AVM模块搜索	列出所有模块（无筛选）	使用多种查询格式的智能搜索
模块详细信息	基本元数据（名称、描述、版本）	深度文档提取（参数、资源类型、示例）
安装	需要。NET运行时和二头肌CLI	轻量级Python，依赖性最小
响应格式	换行分隔文本摘要	具有丰富元数据的结构化JSON
文档访问	仅限外部链接	从模块READM中提取并格式化的标记

为什么存在此服务器

虽然官方的二头肌MCP服务器非常适合 创作二头肌模板 以及访问Azure资源类型模式，它为以下对象提供了有限的功能 发现和理解AVM模块:

无搜索功能：The ListAvmMetadata 该工具返回所有模块而不进行过滤，这使得在有数百个可用模块的情况下很难找到相关模块。此服务器提供智能搜索，可处理“密钥库”、“密钥库“和”密钥库“等变体。

有限文件：官方工具仅提供基本元数据（名称、描述、版本、文档URI）。此服务器提取实际文档内容，包括：

- 完整的参数参考，包括类型和描述 - 模块部署的资源类型 - 具有大型参数集的实际使用示例

不同的用例:

- 在以下情况下使用二头肌MCP服务器：编写二头肌代码，检查Azure资源架构，遵循二头肌最佳实践 - 在以下情况下使用AVM MCP服务器：发现要使用哪个AVM模块，了解模块参数，探索模块功能

补充工具：这些服务器可以一起工作！使用二头肌MCP服务器进行模板创作，使用此服务器进行模块发现和文档编制。

何时使用每个

如果需要，请选择Microsoft二头肌MCP服务器：

二头肌创作最佳实践
Azure资源类型架构和API版本
全面的二头肌生态系统工具

如果需要，请选择AVM MCP服务器：

查找特定Azure服务的AVM模块
在使用模块参数之前，请先了解它们
提取使用示例和文档
在AVM目录中快速筛选搜索

将这两个服务器一起使用，获得完整的二头肌+AVM开发体验！

🛠️ 特性

搜索AVM模块：支持多种查询格式的智能搜索（例如，“密钥库”、“密钥库“、”密钥库“）
列出模块版本：检索任何AVM模块的所有可用版本
模块详细信息：从模块文档中提取资源类型、参数和使用示例
快速过滤：优化搜索，可快速缩小数千个存储库的结果范围
直接注册表访问：连接到Microsoft容器注册表以获取实时模块信息

📋 先决条件

Python 3.11或更高版本
UV包管理器
互联网连接（访问Microsoft容器注册表和GitHub）
Node.js和npm（用于MCP检查器工具，可选）

1.Python

官方下载页面：\

Python 3.11.14的直接下载：\

Python 3.11.14发布页面

下载适用于您的操作系统（Windows、macOS、Linux）的安装程序，并按照安装说明进行操作。

______________________________________________________________________

2.UV（Python包管理器）

官方文件和来源：\

\ UV文档

安装（Windows）：

  irm https://astral.sh/uv/install.ps1 | iex

或者，使用pip（如果你已经安装了Python和pip）：

  pip install uv

安装（macOS/Linux）：

  curl -LsSf https://astral.sh/uv/install.sh | sh

更多信息：\

紫外线安装指南

3.克劳德桌面（可选）

官方下载页面：\

下载适用于您的操作系统（Windows、macOS）的安装程序，并按照安装说明进行操作。

🚀 安装

克隆存储库：

   git clone https://github.com/stefanstranger/avm-mcp-server.git
   cd avm-mcp-server

创建虚拟环境：

   uv venv .venv --python 3.13

激活虚拟环境：

- Windows PowerShell：

     .\.venv\Scripts\Activate.ps1

- macOS/Linux：

     source .venv/bin/activate

安装依赖项：

   uv pip install fastmcp requests

⚙️ 配置

🔧 Claude桌面设置

选项1：在GitHub存储库中使用uvx（推荐）

使用以下命令将AVM MCP服务器添加到本地环境中。这假设uvx在你的$PATH中；如果没有，那么您需要提供uvx的完整路径。

将以下内容添加到您的 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "avm-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/stefanstranger/avm-mcp-server",
        "avm-mcp-server"
      ]
    }
  }
}

或mcp.json用于可视化代码mcp配置。

{
 "servers": {
  "avm-mcp-server-github": {
   "type": "stdio",
   "command": "uvx",
   "args": [
    "--from",
    "git+https://github.com/stefanstranger/avm-mcp-server@v0.1.5",
    "avm-mcp-server"
   ]
  }
 },
 "inputs": []
}

这种方法：

✅ 无需本地安装
✅ 始终使用主分支的最新版本
✅ 无需管理虚拟环境
✅ 在具有相同配置的不同机器上工作

要使用特定的版本/标签，请修改GitHub URL：

"git+https://github.com/stefanstranger/avm-mcp-server@v0.1.5"

选项2：使用本地安装

如果您更喜欢从本地克隆运行：

{
  "mcpServers": {
    "avm-mcp-server": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "requests",
        "mcp",
        "run",
        "C:\\Github\\avm-mcp-server\\server.py"
      ]
    }
  }
}

备注：调整最后一条路径 args 元素以匹配您的安装位置。

🏃 运行服务器

使用uvx（无需安装）

直接从GitHub运行：

uvx --from git+https://github.com/stefanstranger/avm-mcp-server avm-mcp-server

或者使用特定版本：

uvx --from git+https://github.com/stefanstranger/avm-mcp-server@v0.1.5 avm-mcp-server

使用本地安装

如果克隆了存储库：

uv run .\server.py

乘坐不同的交通工具

服务器现在支持不同用例的多种传输方法：

1.STDIO传输（默认）

标准输入/输出-适用于Claude Desktop和MCP Inspector：

python server.py --transport stdio

这是默认模式，在未指定传输时使用。

2.HTTP传输

流式HTTP传输-非常适合web应用程序和REST API集成：

python server.py --transport http --host 0.0.0.0 --port 8080

测试服务器是否正在运行：

# Simple tools listing endpoint (GET request)
curl http://localhost:8080/tools

# MCP protocol endpoint (requires POST with JSON-RPC format)
curl -X POST http://localhost:8080/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

备注：MCP终点(/mcp/)需要一个尾随斜线，并期望POST请求具有JSON-RPC格式的数据。

3.苏格兰和南方能源公司运输

服务器发送事件传输-非常适合实时流媒体应用程序：

python server.py --transport sse --host 0.0.0.0 --port 8080

附加选项

--debug：启用调试日志记录
--host：要绑定的主机地址（默认值：HTTP/SSE为0.0.0.0）
--port：要使用的端口（默认值：HTTP/SSE为8080）

调试模式示例：

python server.py --transport http --port 8081 --debug

通过环境变量进行配置

您还可以使用 .env 文件：

MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_DEBUG=false
LOG_LEVEL=INFO

使用Docker运行

对于容器化部署，请使用附带的Dockerfile：

# Build the image
docker build -t avm-mcp-server .

# Run the container
docker run -p 8080:8080 avm-mcp-server

默认情况下，容器在端口8080上以HTTP传输模式运行。要使用其他端口，请执行以下操作：

docker run -p 9000:8080 avm-mcp-server

要使用SSE传输运行，请执行以下操作：

docker run -p 8080:8080 avm-mcp-server python server.py --transport sse --port 8080

Linux/macOS的快速设置

对于Linux或macOS上的本地开发，请使用安装脚本快速创建虚拟环境并安装依赖项：

chmod +x setup.sh
./setup.sh

此脚本：

检查Python 3安装
创建虚拟环境(.venv)
安装来自的所有依赖项 requirements.txt
验证导入是否正常工作

备注：对于Windows用户或使用UV的用户，请遵循标准安装相反，步骤。

检查MCP服务器

这 MCP检查员是测试和调试MCP服务器的有用工具。

STDIO传输（默认）

使用GitHub上的uvx：

npx @modelcontextprotocol/inspector uvx --from git+https://github.com/stefanstranger/avm-mcp-server avm-mcp-server

使用本地安装：

npx @modelcontextprotocol/inspector uv run --with mcp[cli] mcp run c://github//avm-mcp-server//server.py

HTTP传输

首先，以HTTP模式启动服务器：

python server.py --transport http --port 8080

然后打开MCP Inspector web UI并连接到HTTP端点：

npx @modelcontextprotocol/inspector

在检查器UI中，输入 http://localhost:8080/mcp/ 作为服务器URL，并选择“Streamable HTTP”作为传输类型。

或者，使用curl验证服务器是否正在运行：

# Check the tools endpoint
curl http://localhost:8080/tools

# Or test the MCP endpoint directly
curl -X POST http://localhost:8080/mcp/ `
  -H "Content-Type: application/json" `
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

苏格兰和南方能源公司运输

首先，以SSE模式启动服务器：

python server.py --transport sse --port 8080

然后打开MCP检查器web UI：

npx @modelcontextprotocol/inspector

在检查器UI中，输入 http://localhost:8080/sse 作为服务器URL，并选择“SSE”作为传输类型。

使用mcptools

mcptools 提供了一种检查MCP服务器的替代方法：

# STDIO transport
mcptools web cmd /c "uvx.exe --from git+https://github.com/stefanstranger/avm-mcp-server avm-mcp-server"

# List tools
mcptools tools cmd /c "uvx.exe --from git+https://github.com/stefanstranger/avm-mcp-server avm-mcp-server"

# Call a specific tool
mcptools call list_avm_modules --modulename "storage" cmd /c "uvx.exe --from git+https://github.com/stefanstranger/avm-mcp-server avm-mcp-server"

📖 可用工具

1. `list_avm_modules`

从二头肌公共注册表中搜索并列出Azure验证模块。

参数：

modulename （可选）：要筛选的模块名称。支持多种格式：

- 精确匹配： "storage-account" - 连字符： "key-vault" - 空间分隔： "key vault" （匹配“密钥保管库”、“密钥保管”、“钥匙”或“保管库”） - 契约： "keyvault"

退货： 包含模块信息的JSON数组，包括：

模块名称（注册表路径）
可用版本
描述
文档链接

示例用法：

"List all AVM modules for storage accounts"
"Find Azure Verified Modules for key vault"
"Show me AVM modules related to networking"

示例响应：

[
  {
    "name": "bicep/avm/res/storage/storage-account",
    "versions": ["0.9.1", "0.9.0", "0.8.3"],
    "description": "Azure Verified Module",
    "documentation": "https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/storage/storage-account"
  }
]

2. `scrape_avm_module_details`

从AVM模块的README文档中获取详细信息。

参数：

url （必填）：AVM模块存储库的GitHub URL

- 例子： https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/storage/storage-account

退货： 格式化标记包含：

资源类型：模块部署的Azure资源
参数：完整的参数参考，包括类型、默认值和描述
使用示例：显示实际使用情况的大型参数集示例

示例用法：

"Get the details for the storage account AVM module"
"Show me the parameters for the key vault module"
"What resources does the virtual network module deploy?"

示例响应：

## Resource Types

| Resource Type | API Version |
| :-- | :-- |
| `Microsoft.Storage/storageAccounts` | [2022-09-01] |
| `Microsoft.Storage/storageAccounts/blobServices` | [2022-09-01] |

## Parameters

**Required parameters**

| Parameter | Type | Description |
| :-- | :-- | :-- |
| [`name`](#parameter-name) | string | Name of the Storage Account. |

**Optional parameters**

| Parameter | Type | Description |
| :-- | :-- | :-- |
| [`location`](#parameter-location) | string | Location for all resources. |
...

📖 可用提示

1. `find_avm_module_prompt`

查找Azure验证模块（AVM）的提示。

参数：

search_term （可选）：用于查找AVM模块的搜索词。

示例用法：

"Find AVM modules for 'storage account'"

2. `get_avm_module_details_prompt`

获取特定AVM详细信息的提示。

参数：

module_name （必填）：AVM模块的名称。

示例用法：

"Get details for the 'storage-account' AVM module"

3. `suggest_avm_for_service_prompt`

为特定Azure服务建议AVM的提示。

参数：

azure_service （必需）：用于查找AVM的Azure服务。

示例用法：

"Suggest an AVM for 'Azure Key Vault'"

💡 使用示例

搜索模块

"Find all AVM modules for storage"
"List Azure Verified Modules for Key Vault"
"Show me networking modules"

获取模块版本

"What versions are available for the storage account module?"
"List all versions of the AVM key vault module"

探索模块详细信息

"Show me the parameters for bicep/avm/res/storage/storage-account"
"What resources does the virtual network module deploy?"
"Get usage examples for the key vault module"

组合工作流

"Find the storage account AVM module and show me its parameters"
"I need to deploy a key vault - find the module and explain its parameters"
"Search for virtual network modules and show me usage examples"

🔍 运作原理

模块发现

查询Microsoft容器注册表的目录端点(mcr.microsoft.com/v2/_catalog)
筛选以开头的存储库 bicep/avm/
应用智能搜索匹配：

- 规范搜索词（小写、连字符、紧凑） - 匹配多单词查询中的任何标记 - 返回所有匹配的模块

版本检索

对于每个匹配的模块，查询注册表的标签端点
检索所有可用的语义版本
返回包含模块元数据的版本信息

文档提取

将GitHub树URL转换为原始内容URL
从二头肌注册表模块存储库获取README.md内容
使用正则表达式模式提取相关部分：

- 资源类型表 - 参数文档 - 具有大型参数集的使用示例

🐛 故障排除

常见问题

“无法获取模块”错误

- 检查互联网连接 - 验证访问权限 mcr.microsoft.com - 检查防火墙/代理限制

“无法获取README.md”错误

- 验证GitHub URL格式是否正确 - 确保存储库中存在模块文档 - 检查互联网连接 raw.githubusercontent.com

未找到用于搜索查询的模块

- 尝试不同的搜索词（例如，“存储”而不是“存储帐户”） - 使用部分名称（例如，“key”查找“密钥库”） - 首先列出所有没有过滤器的模块

服务器无法在Claude Desktop中启动

- 验证是否安装了Python 3.11+ - 检查UV是否正确安装 - 确保路径 claude_desktop_config.json 是正确的 - 查看Claude Desktop日志以了解详细的错误消息

🧪 测试

该项目包括一个全面的测试套件，以确保代码质量并在发布前发现问题。

运行测试

# Install dev dependencies
uv sync --dev

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

测试检查什么

测试套件(tests/test_distribution.py)验证：

测试	目的
`test_required_files_in_wheel`	确保 `server.py` 和 `config.py` 包含在车轮中
`test_required_dependencies`	验证是否列出了所有运行时依赖项
`test_entry_point_configured`	确认已定义CLI入口点
`test_modules_import`	从丢失的文件/依赖关系中捕获导入错误

这些测试专门针对导致运行时失败的问题（缺少模块、缺少依赖项）。

持续集成

测试在以下情况下自动运行：

每一次推动 main 和 feature/** 分支
每次pull请求 main
发布到PyPI之前（如果测试失败，则阻止发布）

CI工作流针对Python 3.10、3.11、3.12和3.13进行测试，以确保兼容性。

出版与发行

此服务器发布到PyPI和MCP注册表，便于安装和发现。

从PyPI安装

建议使用此服务器的方式是通过 uvx 来自PyPI：

# Run directly without installation
uvx avm-mcp-server

# Or install globally
uv tool install avm-mcp-server

MCP注册表

此服务器已在中注册 MCP注册表，使其可被MCP客户端和AI助手发现。

注册表项: io.github.stefanstranger/avm-mcp-server

面向开发人员：发布更新

该项目使用自动化的GitHub Actions工作流来发布新版本。当要素分支合并到时，会自动触发发布 main 带有版本凸起。

更新版本号 （在功能分支中）：

- pyproject.toml -软件包版本 - server.py -FastMCP实例版本

创建PR并合并:

   # On your feature branch
   git add pyproject.toml server.py
   git commit -m "Bump version to X.Y.Z"
   git push
   # Create PR and merge to main

自动化工作流程 （合并到main时触发）：

- 检测中的版本更改 pyproject.toml - 在Python 3.10-3.13中运行所有测试 - 创建git标签 vX.Y.Z 自动地 - 构建并发布到PyPI - 更新 server.json 使用新版本 - 通过GitHub OIDC与MCP注册表进行身份验证 - 发布到MCP注册表 - 创建带有发布说明的GitHub版本

备注：工作流仅在以下情况下触发 pyproject.toml 更改后，版本还没有标签。这可以防止重复发布。

手工出版（首次）

对于PyPI的初始版本，请手动发布：

# Build the package
uv build

# Publish to PyPI (will prompt for token)
uv publish

需求:

PyPI帐户和API令牌
README包括MCP验证行： ``

备注：无法重新上传PyPI版本。对于新版本，请务必提高版本号。

📚 参考文献

📄 许可证

MIT许可证

🤝 贡献

欢迎投稿！请随时提交拉取请求。

⚖️ 免责声明

此工具与Microsoft或Azure验证模块团队没有正式关联或认可。它提供对来自Microsoft容器注册表和GitHub的公开模块信息的只读访问。

Avm MCP Server

快速接入

详细介绍

🏗️ avm-mcp服务器

🎯 概述

❓ 为什么选择AVM MCP服务器？

与微软二头肌MCP服务器的比较

主要区别

为什么存在此服务器

何时使用每个

🛠️ 特性

📋 先决条件

1.Python

2.UV（Python包管理器）

3.克劳德桌面（可选）

🚀 安装

⚙️ 配置

🔧 Claude桌面设置

选项1：在GitHub存储库中使用uvx（推荐）

选项2：使用本地安装

🏃 运行服务器

使用uvx（无需安装）

使用本地安装

乘坐不同的交通工具

1.STDIO传输（默认）

2.HTTP传输

3.苏格兰和南方能源公司运输

附加选项

通过环境变量进行配置

使用Docker运行

Linux/macOS的快速设置

检查MCP服务器

STDIO传输（默认）

HTTP传输

苏格兰和南方能源公司运输

使用mcptools

📖 可用工具

1. list_avm_modules

2. scrape_avm_module_details

📖 可用提示

1. find_avm_module_prompt

2. get_avm_module_details_prompt

3. suggest_avm_for_service_prompt

💡 使用示例

搜索模块

获取模块版本

探索模块详细信息

组合工作流

🔍 运作原理

模块发现

版本检索

文档提取

🐛 故障排除

常见问题

🧪 测试

运行测试

测试检查什么

持续集成

出版与发行

从PyPI安装

MCP注册表

面向开发人员：发布更新

手工出版（首次）

📚 参考文献

📄 许可证

🤝 贡献

⚖️ 免责声明

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `list_avm_modules`

2. `scrape_avm_module_details`

1. `find_avm_module_prompt`

2. `get_avm_module_details_prompt`

3. `suggest_avm_for_service_prompt`