azure-machine-learning-mcp

# Azure Machine Learning MCP Server 一个全面的模型上下文协议（Model Context Protocol，MCP）服务器，通过 Azure SDK for Go 提供对 Azure Machine Learning 服务的访问。该服务器使您能够通过标准化的 MCP 工具管理 Azure ML 工作区、计算资源、配额等。 ## 🚀 快速开始 **想立即在 VS Code 中使用这个吗？** 请查看我们的 [VS Code 设置指南](VSCODE_SETUP.md)，获取逐步说明，几分钟内即可开始使用！ ## 特性 该 MCP 服务器提供以下 Azure ML 管理功能： ### 工作区管理 - **list_workspaces_by_subscription**: 列出订阅中的所有 Azure ML 工作区 - **get_workspace**: 获取特定工作区的详细信息 - **create_workspace**: 创建一个新的 Azure ML 工作区 ### 计算资源管理 - **list_compute**: 列出工作区中的所有计算资源 - **get_compute**: 获取特定计算资源的详细信息 - **start_compute**: 启动计算资源 - **stop_compute**: 停止计算资源 ### 资源监控 - **list_quotas**: 列出特定 Azure 区域的资源配额 - **list_usage**: 列出特定 Azure 区域的当前资源使用情况 - **list_vm_sizes**: 列出可用于计算的虚拟机大小 ### 网络与安全 - **list_private_endpoints**: 列出工作区的私有端点连接 - **list_workspace_connections**: 列出工作区连接 - **list_workspace_features**: 列出工作区的可用功能 ## 先决条件 1. **Azure 订阅**: 您需要一个有效的 Azure 订阅 2. **Azure 身份验证**: 服务器在您首次使用时会自动提示进行身份验证。您可以使用以下任一方法： - **交互式浏览器登录**: 服务器将打开您的浏览器进行身份验证（默认） - **设备代码流**: 在无头环境中自动使用 - **Azure CLI**: 如果您已经使用 `az login` 登录 - **服务主体**: 设置环境变量 `AZURE_CLIENT_ID`、`AZURE_CLIENT_SECRET`、`AZURE_TENANT_ID` - **托管身份**: 在 Azure 资源上运行时 3. **Go 1.18+**: 构建和运行服务器所需 ## 安装 ### VS Code 设置（推荐） 为了在 Visual Studio Code 中获得最简单的设置体验，请遵循我们的专用 [VS Code 设置指南](VSCODE_SETUP.md)。该指南涵盖： - 基于 Docker 的设置，使用预构建的镜像 - 从源代码进行本地二进制设置 - 身份验证配置 - 常见问题的故障排除 - 使用 GitHub Copilot 的示例 ### 手动安装 如果您更喜欢手动设置或与其他 MCP 客户端一起使用： 1. 克隆此存储库： ```bash git clone <repository-url> cd aml-cmp ``` 2. 安装依赖： ```bash go mod tidy ``` 3. 构建服务器： ```bash go build ./cmd/mcp-server ``` ## 使用示例 ### 1. 列出工作区 ``` 使用 list_workspaces_by_subscription 工具： - subscription_id: "your-azure-subscription-id" ``` ### 2. 创建工作区 ``` 使用 create_workspace 工具： - subscription_id: "your-azure-subscription-id" - resource_group_name: "my-resource-group" - workspace_name: "my-ml-workspace" - location: "eastus" - description: "My ML workspace for experiments" - friendly_name: "ML Workspace" ``` ### 3. 管理计算资源 ``` # 列出计算资源 使用 list_compute 和工作区详细信息 # 启动计算实例 使用 start_compute： - subscription_id, resource_group_name, workspace_name, compute_name # 停止计算实例 使用 stop_compute： - subscription_id, resource_group_name, workspace_name, compute_name ``` ### 4. 监控资源 ``` # 检查配额 使用 list_quotas： - subscription_id: "your-subscription-id" - location: "eastus" # 检查当前使用情况 使用 list_usage，使用相同的参数 ``` ### 5. 列出可用的 VM 大小 ``` 使用 list_vm_sizes： - subscription_id: "your-subscription-id" - location: "eastus" ``` ## 工具参考 ### 工作区工具 #### `list_workspaces_by_subscription` 列出订阅中的所有 Azure ML 工作区。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID **返回：** 包含名称、位置和资源组的工作区列表。 #### `get_workspace` 获取特定工作区的详细信息。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 **返回：** 包含属性、URL 和配置的详细工作区信息。 #### `create_workspace` 创建一个新的 Azure ML 工作区。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 - `location`（必需）：Azure 区域（例如："eastus"、"westus2"） - `description`（可选）：工作区描述 - `friendly_name`（可选）：友好的显示名称 **返回：** 包含工作区 ID 的工作区创建确认。 ### 计算工具 #### `list_compute` 列出工作区中的所有计算资源。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 **返回：** 包含类型、状态和位置的计算资源列表。 #### `get_compute` 获取特定计算资源的详细信息。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 - `compute_name`（必需）：计算资源名称 **返回：** 包含状态、创建时间和配置的详细计算信息。 #### `start_compute` / `stop_compute` 启动或停止计算资源。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 - `compute_name`（必需）：计算资源名称 **返回：** 操作完成的确认。 ### 监控工具 #### `list_quotas` 列出特定区域的资源配额。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `location`（必需）：Azure 区域 **返回：** 包含限制、单位和资源类型的配额列表。 #### `list_usage` 列出特定区域的当前资源使用情况。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `location`（必需）：Azure 区域 **返回：** 当前使用情况，包括限制和可用容量。 #### `list_vm_sizes` 列出可用于计算的虚拟机大小。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `location`（必需）：Azure 区域 **返回：** 包含 vCPU 和内存规格的可用 VM 大小。 ### 网络与安全工具 #### `list_private_endpoints` 列出工作区的私有端点连接。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 **返回：** 包含状态和配置的私有端点连接。 #### `list_workspace_connections` 列出工作区连接（数据存储、链接服务）。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 **返回：** 包含类型和身份验证方法的工作区连接。 #### `list_workspace_features` 列出工作区的可用功能。 **参数：** - `subscription_id`（必需）：Azure 订阅 ID - `resource_group_name`（必需）：资源组名称 - `workspace_name`（必需）：工作区名称 **返回：** 可用的工作区功能和能力。 ## 错误处理 服务器为常见场景提供详细的错误消息： - **身份验证错误**: Azure 凭据或权限问题 - **资源未找到**: 当指定的资源不存在时 - **权限错误**: 当经过身份验证的用户缺少所需权限时 - **API 错误**: Azure API 特定错误，附带详细消息 ## 开发 ### 项目结构 ``` . ├── cmd/mcp-server/ # 主应用程序入口点 │ └── main.go ├── internal/ # 内部包（不可外部导入） │ ├── azure/ # Azure 客户端管理 │ │ ├── clients.go # Azure 服务客户端 │ │ └── tests/ # Azure 客户端功能的测试 │ │ └── clients_test.go │ ├── helpers/ # 工具函数 │ │ ├── azure.go # Azure 特定的工具函数 │ │ └── tests/ # 工具函数的测试 │ │ └── azure_test.go │ ├── server/ # MCP 服务器实现 │ │ ├── server.go # 服务器设置和配置 │ │ └── tests/ # 服务器测试 │ │ └── server_test.go │ └── tools/ # MCP 工具实现 │ ├── workspace.go # 工作区管理工具 │ ├── compute.go # 计算资源工具 │ ├── monitoring.go # 监控工具（配额、使用情况、VM 大小） │ ├── network.go # 网络和安全工具 │ └── tests/ # 工具实现的测试 │ ├── workspace_test.go │ ├── compute_test.go │ ├── monitoring_test.go │ └── network_test.go ├── .github/workflows/ # GitHub Actions CI/CD ├── Makefile # 构建和开发命令 ├── go.mod # Go 模块定义 ├── go.sum # Go 模块校验和 └── README.md # 本文件 ``` ### 构建 ```bash # 构建服务器 make build # 或手动构建 go build ./cmd/mcp-server ``` ### 测试 ```bash # 运行所有测试 make test # 运行详细输出的测试 make test-verbose # 运行带覆盖率的测试 make test-coverage # 运行特定的测试套件 make test-helpers # 测试工具函数 make test-azure # 测试 Azure 客户端创建 make test-tools # 测试 MCP 工具实现 make test-server # 测试服务器设置 ``` ### 开发命令 ```bash # 安装依赖 make deps # 格式化代码 make format # 运行 linter make lint # 运行所有检查（格式化、lint、测试） make check # 清理构建产物 make clean # 为多个平台构建 make build-all # 本地运行服务器 make run ``` ### 本地运行 ```bash # 使用 make make run # 或直接运行 go run ./cmd/mcp-server ``` ### 添加新工具 要添加新的 Azure ML 功能： 1. 使用 `mcp.NewTool()` 创建新的工具定义 2. 实现处理函数，调用 Azure SDK 3. 使用 `s.AddTool()` 将工具添加到服务器 4. 更新本 README 文档 ## 贡献 1. Fork 该存储库 2. 创建一个功能分支 3. 进行更改 4. 如果适用，添加测试 5. 更新文档 6. 提交拉取请求 ## 许可证 本项目根据 MIT 许可证进行许可。有关详细信息，请参见 LICENSE 文件。 ## 支持 如有问题和疑问： - 查看 Azure ML 文档: https://docs.microsoft.com/azure/machine-learning/ - 查看 Azure SDK for Go 文档: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go - 在此存储库中打开问题 ## Azure ML SDK 覆盖范围 该 MCP 服务器覆盖以下 Azure ML SDK 客户端： - ✅ WorkspacesClient - ✅ ComputeClient - ✅ QuotasClient - ✅ UsagesClient - ✅ VirtualMachineSizesClient - ✅ PrivateEndpointConnectionsClient - ✅ WorkspaceConnectionsClient - ✅ WorkspaceFeaturesClient - ⏳ WorkspaceSKUsClient（计划中） - ⏳ PrivateLinkResourcesClient（计划中） - ⏳ OperationsClient（计划中） 未来版本将扩展覆盖范围，以包括更多 Azure ML 服务和功能。