mcp-builder

MCP 服务开发指南

概述

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

---

流程

🚀 高层工作流

创建高质量的 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 学习框架文档

推荐技术栈：

• 语言：TypeScript（SDK 支持质量高，并且与许多执行环境兼容性良好。AI 模型擅长生成 TypeScript 代码；其广泛使用、静态类型和出色的代码检查工具也很有优势）
• 传输：远程服务使用无状态 JSON 的流式 HTTP（相较于有状态会话和流式响应，它更易扩展和维护）；本地服务使用 stdio。
• 身份验证：远程服务使用 OAuth 2.1（MCP 规范的标准方案），或通过 Authorization 标头传递 API 密钥。标准 OAuth 流程请参阅 MCP 规范中的 authorization.md。

加载框架文档：

• 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 模式和示例

1.4 规划实现方案

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

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

---

阶段 2：实现

2.1 设置项目结构

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

• ⚡ TypeScript 指南 - 项目结构、package.json、tsconfig.json
• 🐍 Python 指南 - 模块组织、依赖项

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 服务可能会暴露在互联网上并处理敏感操作。请遵循以下指南：

身份验证与授权

• 远程服务：实现 OAuth 2.1 或 API 密钥身份验证
• 验证所有输入：绝不信任客户端提供的数据；应依据架构进行验证
• 密钥：绝不将 API 密钥硬编码；使用环境变量
• 限制权限范围：只公开客户端所需的工具；遵循最小权限原则

输入验证

// Use Zod with strict schemas
const DeleteUserSchema = z.object({
  userId: z.string().uuid(),  // UUID format enforced
  reason: z.enum(["spam", "policy_violation", "user_request"]),  // Enum limits
});

// Never allow arbitrary code execution
const QuerySchema = z.object({
  table: z.enum(["users", "orders", "products"]),  // No arbitrary tables
  id: z.number().int().positive(),
});

速率限制与滥用防范

// Add rate limiting to destructive operations
const rateLimiter = new Map<string, number[]>();

function checkRateLimit(clientId: string, limit: number, windowMs: number): boolean {
  const now = Date.now();
  const calls = rateLimiter.get(clientId) ?? [];
  const windowCalls = calls.filter(t => now - t < windowMs);
  if (windowCalls.length >= limit) return false;
  rateLimiter.set(clientId, [...windowCalls, now]);
  return true;
}

审计日志

// Log all tool calls for sensitive operations
server.registerTool("delete_record", {
  // ...
  handler: async ({ id }) => {
    console.error(JSON.stringify({  // stderr for logging
      event: "tool_call",
      tool: "delete_record",
      params: { id },
      timestamp: new Date().toISOString(),
    }));
    // ... implementation
  }
});

---

常见陷阱

MCP 服务开发中会遇到一些可预见的失败情况。这些易错点是在实现过程中发现的实际问题。

1. 生成后服务无法启动

症状：

• npm start 失败，退出代码为 1
• 进程启动后立即崩溃
• 提示端口已被占用

根本原因：

• 缺少依赖（SDK 版本不匹配、npm install 未完整执行）
• 与现有进程发生端口冲突
• 环境变量配置错误
• .npmrc 或 tsconfig.json 配置无效

调试命令：

# Verify dependencies are installed
npm list @modelcontextprotocol/sdk

# Check if port is in use
lsof -i :3000  # Replace 3000 with your port
netstat -an | grep LISTEN | grep 3000

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# Run with verbose output to see initialization errors
npm start -- --debug
NODE_DEBUG=* npm start  # Maximum verbosity for Node.js internals

# For TypeScript, verify compilation first
npm run build
npx tsc --noEmit  # Check for type errors without building

# Check for missing env variables
env | grep MCP  # See what MCP-related vars are set

预防措施：

• 生成项目后务必运行 npm install
• 在配置文件中使用明确的端口号
• 在 .env.example 中记录所需的环境变量
• 启动前先测试编译：npm run build

---

2. 工具 Schema 无法通过验证

症状：

• MCP Inspector 显示“Invalid schema”错误
• 客户端因 422 错误拒绝工具
• 工具在一个 SDK 版本中可用，在另一个版本中却不可用

根本原因：

• Zod/Pydantic 定义违反 JSON Schema 规范
• Schema 对象缺少必填字段
• type 注解错误
• Schema 引用形成循环
• 约束无效（正则表达式模式错误，或未指定 number 类型却设置了最小值/最大值）

调试命令：

# Validate schema syntax
npx @modelcontextprotocol/inspector  # GUI debugger, shows schema errors clearly

# Test schema compilation directly (TypeScript)
cat > test-schema.ts << 'EOF'
import { z } from 'zod';
const schema = z.object({
  // your schema here
});
console.log(JSON.stringify(schema.safeParse({}), null, 2));
EOF
npx ts-node test-schema.ts

# For Python, test Pydantic directly
python3 << 'EOF'
from pydantic import BaseModel
class MyTool(BaseModel):
    # your fields here
    pass
print(MyTool.model_json_schema())
EOF

# Print actual schema being sent to client
# In your server code, log before registration:
console.log(JSON.stringify(toolSchema, null, 2));

# Test with invalid inputs to see error messages
# In MCP Inspector, try calling tool with:
# - Missing required fields
# - Wrong types (string instead of number)
# - Values outside constraints

预防措施：

• 使用启用了严格模式的 TypeScript（在 tsconfig.json 中设置 strict: true）
• 每次更改 Schema 后都进行测试：npm run build
• 在开发期间将 Schema JSON 输出到控制台
• 使用 MCP Inspector 的 Schema 验证功能（这是事实标准）
• 尽量保持 Schema 简洁；将复杂工具拆分为多个小工具
• 在字段描述中记录约束（最小值/最大值、正则表达式模式）

---

3. 身份验证流程失败

症状：

• 出现“Unauthorized”或“403 Forbidden”错误
• 请求未携带 API 密钥
• OAuth 令牌已过期或无效
• 凭据在本地可用，但部署后失效

根本原因：

• 部署环境中未设置环境变量
• 凭据已过期或被撤销
• API 身份验证的请求头格式错误（Bearer 与 Basic 混淆）
• OAuth 重定向 URI 与注册信息不匹配
• OAuth 请求中缺少 scope
• 凭据意外硬编码，而不是通过环境变量配置

调试命令：

# Verify environment variables are accessible
node -e "const k = process.env.API_KEY; console.log('Key set:', !!k, '| Length:', k?.length, '| Prefix:', k?.substring(0, 4) + '***')"

# Check if file-based credentials exist
test -f ~/.aws/credentials && echo "AWS creds found" || echo "AWS creds missing"
test -f ~/.config/github-cli/hosts.yml && echo "GitHub token found" || echo "GitHub token missing"

# Validate API key format before use
node -e "const key = process.env.API_KEY; console.log('Key length:', key?.length); console.log('Key prefix:', key?.substring(0, 10));"

# Test API authentication directly
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/v1/test
curl -H "X-API-Key: $API_KEY" https://api.example.com/v1/test  # Alternative header

# Check OAuth token expiration
node -e "const payload = JSON.parse(Buffer.from(process.env.OAUTH_TOKEN.split('.')[1], 'base64url').toString()); console.log('Expires:', new Date(payload.exp * 1000));"

# For deployed servers, check what environment was actually loaded
# Add this to your server initialization:
console.error('Auth check:', {
  hasApiKey: !!process.env.API_KEY,
  keyLength: process.env.API_KEY?.length,
  keyPrefix: process.env.API_KEY?.substring(0, 10) + '***'
});

预防措施：

• 切勿硬编码凭据；始终使用环境变量
• 创建 .env.example，为所有必需凭据填写占位值
• 记录哪些凭据是可选的，哪些是必需的
• 在开发期间使用 dotenv 库加载 .env 文件
• 在启动时记录凭据状态（不要泄露实际值）
• 在服务启动时验证凭据，发现问题时立即失败
• 对于已部署的服务，使用平台原生的机密管理功能（GitHub Secrets、Fly.io Secrets 等）
• 在测试工具前单独测试身份验证：先使用凭据运行 curl

---

4. 客户端连接超时

症状：

• 30 秒后出现“Connection timeout”错误
• 客户端无法找到服务
• Stdio 传输在本地可用，但在 MCP Inspector 中不可用
• Streamable HTTP 服务始终收不到请求

根本原因：

• 客户端连接前服务进程已崩溃
• 客户端配置中的端口或主机名错误
• 防火墙阻止连接
• 服务线程在初始化期间死锁
• Stdio 传输设置错误（stdin/stdout 未正确连接）
• 服务初始化耗时过长（超出默认超时时间）

调试命令：

# For stdio transport, test directly
npx @modelcontextprotocol/inspector stdio node dist/index.js

# For HTTP transport, verify server is listening
lsof -i -n -P | grep LISTEN  # See all listening ports
curl http://localhost:3000/ -v  # Try to reach server directly

# Monitor server startup time
time npm start  # Measure total startup duration

# Check if process is using all CPU (deadlock indicator)
top -n1 | grep node  # See if CPU% is stuck at 100

# For stdio issues, run server directly to see output
node dist/index.js  # If it hangs here, initialization is blocking
# Try interrupt (Ctrl+C) to see if it's truly stuck

# Check for port binding issues
ss -tlnp | grep 3000  # Linux
netstat -tlnp | grep 3000  # Linux alternative
lsof -i TCP:3000  # macOS/BSD

# Test server connectivity with timeout
timeout 5 curl -v http://localhost:3000/ || echo "Connection failed or timeout"

预防措施：

• 添加启动日志：记录服务启动时间以及每个主要初始化步骤完成的时间
• 实现健康检查端点：GET /health 返回 200 OK
• 使用 MCP Inspector 进行测试（它能快速发现连接问题）
• 保持服务初始化过程轻量；将耗时操作推迟到首次请求时执行
• 为外部 API 调用设置明确的超时时间（不要让请求无限期挂起）
• 使用 npx @modelcontextprotocol/inspector stdio <command> 测试 stdio 传输
• 对于 HTTP 传输，开放 /health 并单独测试
• 监控启动期间的内存使用情况（内存泄漏表明存在问题）

---

系统化调试工作流

当你的 MCP 服务无法正常工作时：

1. 先检查日志：大多数故障都会记录在日志中。使用详细输出运行：

   NODE_DEBUG=* npm start 2>&1 | head -50
   

2. 使用 MCP Inspector：独立启动它并选择你的服务：

   npx @modelcontextprotocol/inspector
   

   它会清楚地显示架构错误、连接问题和工具执行失败。

3. 隔离测试：与客户端测试之前，先验证服务能否独立运行：

   npm run build && node dist/index.js
   

4. 检查外部依赖项：验证 API 凭据、网络访问和防火墙：

   curl -v https://api.example.com/  # Does API respond?
   

5. 添加检测代码：遇到困难时，添加日志以了解正在发生的情况：

   server.setRequestHandler(Tool, async (request) => {
     console.error('Tool called:', request.params.name);
     try {
       // implementation
       console.error('Tool succeeded');
     } catch (error) {
       console.error('Tool failed:', error);
       throw error;
     }
   });
   

---

参考文件

📚 文档库

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

MCP 核心文档（首先加载）

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

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 获取

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

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

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

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

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

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

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