mcp-builder-ms

MCP 服务开发指南

适用场景

在构建 MCP 服务以集成外部 API 或服务时，请使用此技能，无论是使用 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。

概述

创建 MCP（Model Context Protocol）服务，让大模型能够通过设计良好的工具与外部服务交互。MCP 服务的质量取决于它能否帮助大模型完成实际任务。

---

下方以表情符号命名的实现／评估指南未包含在此目录中。请查阅官方 SDK 文档，不要声称读过这些指南或脚本。端点／服务数量仅为示例，需进行最新核实。stdio 是一种传输方式：使用该方式的服务仍可发出网络请求。工具注解只是提示，并非授权控制措施。请在服务代码中执行租户／身份检查，遵循最小权限原则，限制输入／输出，设置超时，并对错误信息进行脱敏；远程服务需要使用协议支持的身份验证和请求来源保护措施。stdio 模式下，绝不要将协议消息记录到 stdout。

Microsoft MCP 生态系统

Microsoft 为 Azure 和 Foundry 服务提供了广泛的 MCP 基础设施。了解这一生态系统有助于你决定是构建自定义服务，还是使用现有服务。

服务类型

类型	传输方式	使用场景	示例
本地	stdio	桌面应用、单用户、本地开发	通过 NPM/Docker 使用 Azure MCP 服务
远程	Streamable HTTP	云服务、多租户、Agent Service	https://mcp.ai.azure.com（Foundry）

Microsoft MCP 服务

构建自定义服务之前，请先检查 Microsoft 是否已提供现成服务：

服务	类型	描述
Azure MCP	本地	48+ 种 Azure 服务（Storage、KeyVault、Cosmos、SQL 等）
Foundry MCP	远程	https://mcp.ai.azure.com - 模型、部署、评估、Agent
Fabric MCP	本地	Microsoft Fabric API、OneLake、项目定义
Playwright MCP	本地	浏览器自动化与测试
GitHub MCP	远程	https://api.githubcopilot.com/mcp

完整生态系统： 请参阅 🔷 Microsoft MCP Patterns，了解完整的服务目录和模式。

何时使用 Microsoft 服务，何时构建自定义服务

场景	建议
集成 Azure 服务	使用 Azure MCP Server（涵盖 48 种服务）
AI Foundry Agent／评估	使用 Foundry MCP 远程服务
自定义内部 API	构建 自定义服务（本指南）
集成第三方 SaaS	构建 自定义服务（本指南）
扩展 Azure MCP	遵循 Microsoft MCP Patterns

---

流程

🚀 高层工作流

创建高质量 MCP 服务包含四个主要阶段：

阶段 1：深入研究与规划

1.1 理解现代 MCP 设计

API 覆盖范围与工作流工具： 在全面覆盖 API 端点与专用工作流工具之间取得平衡。对于特定任务，工作流工具可能更方便；全面覆盖则能让 Agent 灵活组合操作。不同客户端的表现各异：有些客户端受益于能够组合基础工具的代码执行功能，而另一些客户端使用更高层级的工作流效果更好。如果无法确定，请优先考虑全面覆盖 API。

工具命名与可发现性： 清晰、描述性强的工具名称有助于 Agent 快速找到合适的工具。使用一致的前缀（例如 github_create_issue、github_list_repos）和以操作为导向的命名方式。

上下文管理： 简洁的工具描述以及筛选／分页结果的能力对 Agent 很有帮助。设计能够返回精简相关数据的工具。有些客户端支持代码执行，可帮助 Agent 高效地筛选和处理数据。

可操作的错误消息： 错误消息应通过具体建议和后续步骤，引导 Agent 找到解决方案。

1.2 学习 MCP 协议文档

浏览 MCP 规范：

先查看站点地图，找到相关页面：https://modelcontextprotocol.io/sitemap.xml

然后获取特定页面，在 URL 后添加 .md 后缀以获取 Markdown 格式（例如：https://modelcontextprotocol.io/specification/draft.md）。

需要查看的关键页面：

• 规范概述和架构
• 传输机制（可流式传输的 HTTP、stdio）
• 工具、资源和提示词定义

1.3 学习框架文档

语言选择：

语言	最适用场景	SDK
TypeScript（推荐）	通用 MCP 服务，兼容性广	@modelcontextprotocol/sdk
Python	数据/ML 工作流、FastAPI 集成	mcp（FastMCP）
C#/.NET	Azure/Microsoft 生态、企业场景	Microsoft.Mcp.Core

传输方式选择：

传输方式	使用场景	特性
可流式传输的 HTTP	远程服务、多租户、Agent Service	无状态、可扩展，需要身份验证
stdio	本地服务、桌面应用	简单的本地进程传输；服务可访问网络

加载框架文档：

• MCP 最佳实践：📋 查看最佳实践 - 核心指南

对于 TypeScript（推荐）：

• TypeScript SDK：使用 WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ TypeScript 指南 - TypeScript 模式和示例

对于 Python：

• Python SDK：使用 WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• 🐍 Python 指南 - Python 模式和示例

对于 C#/.NET（Microsoft 生态）：

• 🔷 Microsoft MCP 模式 - C# 模式、Azure MCP 架构、命令层次结构

1.4 规划实现方案

了解 API： 查看服务的 API 文档，确定关键端点、身份验证要求和数据模型。根据需要使用网络搜索和 WebFetch。

工具选择： 优先实现全面的 API 覆盖。列出要实现的端点，从最常见的操作开始。

---

阶段 2：实现

2.1 设置项目结构

有关项目设置，请参阅特定语言的指南：

• ⚡ TypeScript 指南 - 项目结构、package.json、tsconfig.json
• 🐍 Python 指南 - 模块组织、依赖项
• 🔷 Microsoft MCP 模式 - C# 项目结构、命令层次结构

2.2 实现核心基础设施

创建共享实用工具：

• 带身份验证的 API 客户端
• 错误处理辅助工具
• 响应格式化（JSON/Markdown）
• 分页支持

2.3 实现工具

对于每个工具：

输入架构：

• 使用 Zod（TypeScript）或 Pydantic（Python）
• 添加约束和清晰的描述
• 在字段描述中添加示例

输出架构：

• 尽可能定义 outputSchema 以支持结构化数据
• 在工具响应中使用 structuredContent（TypeScript SDK 功能）
• 帮助客户端理解和处理工具输出

工具描述：

• 简洁的功能摘要
• 参数描述
• 返回类型架构

实现：

• 对 I/O 操作使用 Async/await
• 使用可操作的消息妥善处理错误
• 适用时支持分页
• 使用现代 SDK 时，同时返回文本内容和结构化数据

注解：

• readOnlyHint：true/false
• destructiveHint：true/false
• idempotentHint：true/false
• openWorldHint：true/false

---

阶段 3：审查和测试

3.1 代码质量

检查以下方面：

• 不存在重复代码（DRY 原则）
• 错误处理一致
• 类型覆盖完整
• 工具描述清晰

3.2 构建和测试

TypeScript：

• 运行 npm run build，验证编译是否通过
• 使用 MCP Inspector 测试：npx @modelcontextprotocol/inspector

Python：

• 验证语法：python -m py_compile your_server.py
• 使用 MCP Inspector 测试

有关详细的测试方法和质量检查清单，请参阅特定语言的指南。

---

第 4 阶段：创建评估

实现 MCP 服务后，请创建全面的评估，以测试其有效性。

加载 ✅ 评估指南，查看完整的评估准则。

4.1 了解评估目的

使用评估来测试大模型能否有效地使用 MCP 服务回答真实且复杂的问题。

4.2 创建 10 个评估问题

要创建有效的评估，请遵循评估指南中列出的流程：

1. 工具检查：列出可用工具并了解其功能
2. 内容探索：使用只读操作探索可用数据
3. 问题生成：创建 10 个复杂且真实的问题
4. 答案验证：亲自解答每个问题以验证答案

4.3 评估要求

确保每个问题都符合以下要求：

• 独立：不依赖其他问题
• 只读：只需要非破坏性操作
• 复杂：需要多次调用工具并进行深入探索
• 真实：基于人们会关心的真实用例
• 可验证：答案唯一且明确，可通过字符串比较进行验证
• 稳定：答案不会随时间变化

4.4 输出格式

创建一个 XML 文件，结构如下：

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>

</evaluation>

---

参考文件

📚 文档库

在开发过程中，按需加载以下资源：

MCP 核心文档（首先加载）

• MCP 协议：从 https://modelcontextprotocol.io/sitemap.xml 中的站点地图开始，然后使用 .md 后缀获取具体页面
• 📋 MCP 最佳实践 - 通用 MCP 指南，包括：
  • 服务和工具命名约定
  • 响应格式指南（JSON 与 Markdown）
  • 分页最佳实践
  • 传输方式选择（可流式传输的 HTTP 与 stdio）
  • 安全和错误处理标准

Microsoft MCP 文档（适用于 Azure/Foundry）

• 🔷 Microsoft MCP 模式 - Microsoft 专属模式，包括：
  • Azure MCP 服务架构（48+ 个 Azure 服务）
  • C#/.NET 命令实现模式
  • 使用 Foundry Agent Service 的远程 MCP
  • 身份验证（Entra ID、OBO 流程、托管标识）
  • 使用 Bicep 模板的测试基础设施

SDK 文档（在第 1/2 阶段加载）

• Python SDK：从 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md 获取
• TypeScript SDK：从 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 获取
• Microsoft MCP SDK：C#/.NET 内容请参阅 Microsoft MCP 模式

特定语言的实现指南（在第 2 阶段加载）

• 🐍 Python 实现指南 - 完整的 Python/FastMCP 指南，包括：

  • 服务初始化模式
  • Pydantic 模型示例
  • 使用 @mcp.tool 注册工具
  • 完整的可运行示例
  • 质量检查清单

• ⚡ TypeScript 实现指南 - 完整的 TypeScript 指南，包括：

  • 项目结构
  • Zod 模式
  • 使用 server.registerTool 注册工具
  • 完整的可运行示例
  • 质量检查清单

• 🔷 Microsoft MCP 模式 - 完整的 C#/.NET 指南，包括：

  • 命令层次结构（BaseCommand → GlobalCommand → SubscriptionCommand）
  • 命名约定（{Resource}{Operation}Command）
  • 使用 .AsRequired() / .AsOptional() 处理选项
  • Azure Functions 远程 MCP 部署
  • 使用 Bicep 的实时测试模式

评估指南（在第 4 阶段加载）

• ✅ 评估指南 - 完整的评估创建指南，包含：
  • 问题创建指南
  • 答案验证策略
  • XML 格式规范
  • 示例问题和答案
  • 使用提供的脚本运行评估

局限性

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境的验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。