⚡

MCP服务器开发技能Skill mcp-builder

这个技能是用于指导开发者创建高质量的MCP（模型上下文协议）服务器，使大语言模型（LLM）能够通过工具与外部服务交互。它涵盖从研究、规划到实现的完整流程，支持Python和Node/TypeScript开发，旨在提升AI代理的工作效率和任务完成能力。关键词包括MCP服务器、LLM工具、API集成、Python FastMCP、Node TypeScript SDK、AI智能体开发。

AI智能体 0 次安装 0 次浏览 更新于 3/14/2026

名称: mcp-builder 描述: 创建高质量MCP（模型上下文协议）服务器的指南，使大语言模型能够通过精心设计的工具与外部服务交互。在构建MCP服务器以集成外部API或服务时使用，无论是Python（FastMCP）还是Node/TypeScript（MCP SDK）。 许可证: 完整条款在LICENSE.txt中

MCP服务器开发指南

概述

要创建高质量MCP（模型上下文协议）服务器，使大语言模型能够有效地与外部服务交互，请使用此技能。一个MCP服务器提供允许大语言模型访问外部服务和API的工具。MCP服务器的质量通过它如何使大语言模型使用提供的工具完成实际任务来衡量。

过程

🚀 高层次工作流程

创建一个高质量的MCP服务器涉及四个主要阶段：

阶段1：深度研究与规划

1.1 理解以代理为中心的设计原则

在开始实现之前，通过回顾这些原则理解如何为AI代理设计工具：

为工作流构建，而不仅仅是API端点：

  • 不要简单包装现有API端点——构建周到、高影响力的工作流工具
  • 整合相关操作（例如，schedule_event 同时检查可用性并创建事件）
  • 专注于能完成完整任务的工具，而不仅仅是单个API调用
  • 考虑代理实际需要完成的工作流

为有限上下文优化：

  • 代理有受限的上下文窗口——让每个令牌都有价值
  • 返回高信号信息，而非详尽的数据转储
  • 提供“简洁”与“详细”的响应格式选项
  • 默认使用人类可读的标识符而非技术代码（名称而非ID）
  • 将代理的上下文预算视为稀缺资源

设计可操作的错误消息：

  • 错误消息应指导代理走向正确的使用模式
  • 建议具体下一步：“尝试使用 filter=‘active_only’ 来减少结果”
  • 让错误具有教育性，而不仅仅是诊断性
  • 通过清晰反馈帮助代理学习正确工具使用

遵循自然的任务细分：

  • 工具名称应反映人类对任务的思考方式
  • 使用一致的前缀分组相关工具以提高可发现性
  • 围绕自然工作流设计工具，而不仅仅是API结构

使用评估驱动的开发：

  • 早期创建现实的评估场景
  • 让代理反馈驱动工具改进
  • 快速原型并根据实际代理性能迭代

1.3 学习MCP协议文档

获取最新的MCP协议文档：

使用WebFetch加载：https://modelcontextprotocol.io/llms-full.txt

这个全面文档包含完整的MCP规范和指南。

1.4 学习框架文档

加载并阅读以下参考文件：

对于Python实现，还加载：

  • Python SDK文档：使用WebFetch加载 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • 🐍 Python实现指南 - Python特定的最佳实践和示例

对于Node/TypeScript实现，还加载：

  • TypeScript SDK文档：使用WebFetch加载 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • ⚡ TypeScript实现指南 - Node/TypeScript特定的最佳实践和示例

1.5 详尽学习API文档

要集成一个服务，阅读所有可用的API文档：

  • 官方API参考文档
  • 认证和授权要求
  • 速率限制和分页模式
  • 错误响应和状态码
  • 可用端点及其参数
  • 数据模型和模式

为收集全面信息，根据需要使用网络搜索和WebFetch工具。

1.6 创建全面的实现计划

基于你的研究，创建一个详细计划，包括：

工具选择：

  • 列出最有价值的要实现的端点/操作
  • 优先考虑能启用最常见和最重要使用场景的工具
  • 考虑哪些工具协同工作以启用复杂工作流

共享实用程序和助手：

  • 识别常见的API请求模式
  • 计划分页助手
  • 设计过滤和格式化实用程序
  • 计划错误处理策略

输入/输出设计：

  • 定义输入验证模型（Python用Pydantic，TypeScript用Zod）
  • 设计一致的响应格式（例如，JSON或Markdown），以及可配置的详细级别（例如，详细或简洁）
  • 为大规模使用计划（数千用户/资源）
  • 实现字符限制和截断策略（例如，25,000令牌）

错误处理策略：

  • 计划优雅的失败模式
  • 设计清晰、可操作、LLM友好、自然语言的错误消息，提示进一步行动
  • 考虑速率限制和超时场景
  • 处理认证和授权错误

阶段2：实现

现在你有了一个全面计划，开始按照语言特定的最佳实践实现。

2.1 设置项目结构

对于Python：

  • 创建一个单独的 .py 文件或如果复杂则组织成模块（参见🐍 Python指南）
  • 使用MCP Python SDK进行工具注册
  • 定义Pydantic模型用于输入验证

对于Node/TypeScript：

  • 创建适当的项目结构（参见⚡ TypeScript指南）
  • 设置 package.json 和 tsconfig.json
  • 使用MCP TypeScript SDK
  • 定义Zod模式用于输入验证

2.2 首先实现核心基础设施

开始实现前，先创建共享实用程序：

  • API请求助手函数
  • 错误处理实用程序
  • 响应格式化函数（JSON和Markdown）
  • 分页助手
  • 认证/令牌管理

2.3 系统性地实现工具

对于计划中的每个工具：

定义输入模式：

  • 使用Pydantic（Python）或Zod（TypeScript）进行验证
  • 包括适当的约束（最小/最大长度、正则表达式模式、最小/最大值、范围）
  • 提供清晰、描述性的字段描述
  • 在字段描述中包括多样化的示例

编写全面的文档字符串/描述：

  • 工具功能的一行摘要
  • 目的和功能的详细解释
  • 显式参数类型与示例
  • 完整的返回类型模式
  • 使用示例（何时使用、何时不使用）
  • 错误处理文档，概述在特定错误下如何继续

实现工具逻辑：

  • 使用共享实用程序避免代码重复
  • 所有I/O遵循异步/等待模式
  • 实现适当的错误处理
  • 支持多种响应格式（JSON和Markdown）
  • 尊重分页参数
  • 检查字符限制并适当截断

添加工具注解：

  • readOnlyHint: true（对于只读操作）
  • destructiveHint: false（对于非破坏性操作）
  • idempotentHint: true（如果重复调用有相同效果）
  • openWorldHint: true（如果与外部系统交互）

2.4 遵循语言特定的最佳实践

此时，加载适当的语言指南：

对于Python：加载🐍 Python实现指南并确保以下：

  • 使用MCP Python SDK进行正确的工具注册
  • 带有 model_config 的Pydantic v2模型
  • 全程类型提示
  • 所有I/O操作的异步/等待
  • 适当的导入组织
  • 模块级常量（CHARACTER_LIMIT, API_BASE_URL）

对于Node/TypeScript：加载⚡ TypeScript实现指南并确保以下：

  • 正确使用 server.registerTool
  • 带有 .strict() 的Zod模式
  • 启用TypeScript严格模式
  • 不使用 any 类型——使用适当类型
  • 显式Promise<T>返回类型
  • 配置构建过程（npm run build）

阶段3：审查与精炼

初步实现后：

3.1 代码质量审查

为确保质量，审查代码的：

  • DRY原则：工具间无重复代码
  • 可组合性：共享逻辑提取到函数中
  • 一致性：相似操作返回相似格式
  • 错误处理：所有外部调用都有错误处理
  • 类型安全：完整类型覆盖（Python类型提示，TypeScript类型）
  • 文档：每个工具都有全面的文档字符串/描述

3.2 测试与构建

重要： MCP服务器是长运行进程，通过stdio/stdin或sse/http等待请求。在主要进程（例如 python server.py 或 node dist/index.js）中直接运行它们会导致你的进程无限期挂起。

安全测试服务器的方法：

  • 使用评估工具（参见阶段4）——推荐方法
  • 在tmux中运行服务器以保持在主要进程外
  • 测试时使用超时：timeout 5s python server.py

对于Python：

  • 验证Python语法：python -m py_compile your_server.py
  • 检查导入是否正确工作，通过审查文件
  • 手动测试：在tmux中运行服务器，然后在主要进程中用评估工具测试
  • 或直接使用评估工具（它管理stdio传输的服务器）

对于Node/TypeScript：

  • 运行 npm run build 并确保完成无错误
  • 验证dist/index.js已创建
  • 手动测试：在tmux中运行服务器，然后在主要进程中用评估工具测试
  • 或直接使用评估工具（它管理stdio传输的服务器）

3.3 使用质量检查清单

为验证实现质量，从语言特定指南加载适当的检查清单：

阶段4：创建评估

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

加载✅ 评估指南获取完整的评估指南。

4.1 理解评估目的

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

4.2 创建10个评估问题

要创建有效的评估，按照评估指南中概述的过程：

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

4.3 评估要求

每个问题必须是：

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

4.4 输出格式

创建具有此结构的XML文件：

<evaluation>
  <qa_pair>
    <question>查找关于动物代号AI模型发布的讨论。一个模型需要一个特定的安全标识，使用格式ASL-X。对于以斑点野生猫命名的模型，确定的数字X是多少？</question>
    <answer>3</answer>
  </qa_pair>
<!-- 更多qa_pair... -->
</evaluation>

参考文件

📚 文档库

在开发过程中根据需要加载这些资源：

核心MCP文档（首先加载）

  • MCP协议：从 https://modelcontextprotocol.io/llms-full.txt 获取——完整的MCP规范
  • 📋 MCP最佳实践 - 通用MCP指南，包括：
    • 服务器和工具命名约定
    • 响应格式指南（JSON vs Markdown）
    • 分页最佳实践
    • 字符限制和截断策略
    • 工具开发指南
    • 安全和错误处理标准

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格式规范
    • 示例问题和答案
    • 使用提供的脚本运行评估