MCP Builder Skill 详解

创建高质量的 MCP 服务器

基本信息

属性	值
名称	mcp-builder
类别	开发工具
输出格式	TypeScript / Python 项目
许可证	Apache 2.0

name: mcp-builder
description: Guide for creating high-quality MCP (Model Context Protocol)
servers that enable LLMs to interact with external services through
well-designed tools. Use when building MCP servers to integrate external
APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

---

1. 核心概念

1.1 什么是 MCP

通俗比喻：MCP（Model Context Protocol）就像是 LLM 的"USB 接口"——它让 AI 可以通过标准化的方式与外部服务（API、数据库、文件系统等）交互。

1.2 质量衡量标准

MCP 服务器的质量由其帮助 LLM 完成实际任务的效果来衡量

---

2. 四阶段开发流程

graph LR
    A[阶段1: 深度研究] --> B[阶段2: 实现]
    B --> C[阶段3: 审查测试]
    C --> D[阶段4: 创建评估]

---

3. 阶段1：深度研究和规划

3.1 理解现代 MCP 设计

**API 覆盖 vs 工作流工具**：
- 综合 API 端点覆盖给 Agent 组合操作的灵活性
- 专门的工作流工具对特定任务更方便
- 不确定时，优先考虑综合 API 覆盖

**工具命名和可发现性**：
- 清晰、描述性的工具名帮助 Agent 快速找到正确工具
- 使用一致的前缀（如 github_create_issue, github_list_repos）
- 面向动作的命名

**上下文管理**：
- Agent 受益于简洁的工具描述
- 设计返回聚焦、相关数据的工具
- 支持过滤/分页结果

**可操作的错误消息**：
- 错误消息应引导 Agent 找到解决方案
- 提供具体建议和下一步操作

3.2 学习 MCP 规范

**导航 MCP 规范**：
1. 从站点地图开始：https://modelcontextprotocol.io/sitemap.xml
2. 获取特定页面，添加 .md 后缀获取 Markdown 格式

**关键页面**：
- 规范概述和架构
- 传输机制（streamable HTTP, stdio）
- 工具、资源和提示定义

3.3 学习框架文档

**推荐技术栈**：
- 语言：TypeScript（高质量 SDK 支持）
- 传输：远程服务器用 Streamable HTTP，本地服务器用 stdio

**SDK 文档**：
- TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
- Python SDK：https://github.com/modelcontextprotocol/python-sdk

3.4 规划实现

**理解 API**：
- 审查服务的 API 文档
- 识别关键端点、认证要求和数据模型

**工具选择**：
- 优先考虑综合 API 覆盖
- 列出要实现的端点，从最常用的操作开始

---

4. 阶段2：实现

4.1 项目结构设置

参考语言特定指南：

• TypeScript：项目结构、package.json、tsconfig.json
• Python：模块组织、依赖项

4.2 实现核心基础设施

创建共享工具：
- 带认证的 API 客户端
- 错误处理辅助函数
- 响应格式化（JSON/Markdown）
- 分页支持

4.3 实现工具

**对于每个工具**：

1. **输入 Schema**
   - 使用 Zod (TypeScript) 或 Pydantic (Python)
   - 包含约束和清晰描述
   - 在字段描述中添加示例

2. **输出 Schema**
   - 尽可能定义 outputSchema
   - 使用 structuredContent 返回结构化数据

3. **工具描述**
   - 功能的简洁摘要
   - 参数描述
   - 返回类型 schema

4. **实现**
   - 异步/await 处理 I/O 操作
   - 带可操作消息的错误处理
   - 适当时支持分页
   - 返回文本内容和结构化数据

5. **注解**
   - readOnlyHint: true/false
   - destructiveHint: true/false
   - idempotentHint: true/false
   - openWorldHint: true/false

4.4 TypeScript 示例

import { z } from 'zod';

// 输入 Schema
const CreateIssueInput = z.object({
  repo: z.string().describe("仓库名称，格式：owner/repo"),
  title: z.string().describe("Issue 标题"),
  body: z.string().optional().describe("Issue 正文内容"),
  labels: z.array(z.string()).optional().describe("标签列表")
});

// 工具注册
server.registerTool({
  name: "github_create_issue",
  description: "在 GitHub 仓库中创建新的 Issue",
  inputSchema: CreateIssueInput,
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false
  },
  async execute(input) {
    // 实现逻辑
    const issue = await githubClient.createIssue(input);
    return {
      content: [{ type: "text", text: `Created issue #${issue.number}` }],
      structuredContent: issue
    };
  }
});

4.5 Python 示例

from pydantic import BaseModel, Field
from mcp import tool

class CreateIssueInput(BaseModel):
    repo: str = Field(description="仓库名称，格式：owner/repo")
    title: str = Field(description="Issue 标题")
    body: str | None = Field(default=None, description="Issue 正文内容")
    labels: list[str] | None = Field(default=None, description="标签列表")

@mcp.tool
async def github_create_issue(input: CreateIssueInput) -> dict:
    """在 GitHub 仓库中创建新的 Issue"""
    issue = await github_client.create_issue(
        repo=input.repo,
        title=input.title,
        body=input.body,
        labels=input.labels
    )
    return {"issue_number": issue.number, "url": issue.html_url}

---

5. 阶段3：审查和测试

5.1 代码质量检查

审查要点：
- 无重复代码（DRY 原则）
- 一致的错误处理
- 完整的类型覆盖
- 清晰的工具描述

5.2 构建和测试

**TypeScript**：
- 运行 npm run build 验证编译
- 使用 MCP Inspector 测试：npx @modelcontextprotocol/inspector

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

---

6. 阶段4：创建评估

6.1 评估目的

使用评估测试 LLM 是否能有效使用你的 MCP 服务器
回答现实的、复杂的问题

6.2 创建 10 个评估问题

1. **工具检查**：列出可用工具，理解其能力
2. **内容探索**：使用只读操作探索可用数据
3. **问题生成**：创建 10 个复杂、现实的问题
4. **答案验证**：自己解答每个问题以验证答案

6.3 评估要求

确保每个问题：
- **独立**：不依赖其他问题
- **只读**：只需要非破坏性操作
- **复杂**：需要多次工具调用和深度探索
- **现实**：基于人类真正关心的用例
- **可验证**：单一、清晰的答案，可通过字符串比较验证
- **稳定**：答案不会随时间变化

6.4 输出格式

<evaluation>
  <qa_pair>
    <question>在关于 AI 模型发布的讨论中，有一个以斑点野猫命名的模型需要特定的安全等级...该模型需要什么 ASL-X 等级？</question>
    <answer>3</answer>
  </qa_pair>
  <!-- 更多 qa_pairs... -->
</evaluation>

---

7. 参考资源

7.1 核心 MCP 文档

- **MCP 协议**：从 sitemap 开始
- **MCP 最佳实践**：reference/mcp_best_practices.md

7.2 SDK 文档

- **Python SDK**：https://github.com/modelcontextprotocol/python-sdk
- **TypeScript SDK**：https://github.com/modelcontextprotocol/typescript-sdk

7.3 语言特定指南

- **Python 指南**：reference/python_mcp_server.md
- **TypeScript 指南**：reference/node_mcp_server.md

7.4 评估指南

- **评估指南**：reference/evaluation.md

---

8. 使用示例

8.1 触发方式

"帮我创建一个 MCP 服务器来集成 Slack API"
"build an MCP server for GitHub integration"
"create a Python MCP server for database access"

---

9. 本节小结

要点	说明
四阶段流程	研究 → 实现 → 测试 → 评估
推荐技术栈	TypeScript + Streamable HTTP
工具设计	清晰命名、结构化输入输出、可操作错误
测试验证	MCP Inspector + 10 个评估问题
质量标准	帮助 LLM 完成实际任务的效果

---

返回：Skills 目录