mcp-builder

原文：🇺🇸 英文

已翻译

包含 2 个脚本检查通过 / 未检测到疑似敏感代码

创建高质量MCP（Model Context Protocol，模型上下文协议）服务器的指南，这类服务器可使LLM通过设计精良的工具与外部服务交互。适用于构建MCP服务器以集成外部API或服务的场景，无论使用Python（FastMCP）还是Node/TypeScript（MCP SDK）。

107.9k次下载

来源anthropics/skills

添加于2026-02-04

NPX安装

npx skill4agent add anthropics/skills mcp-builder

SKILL.md 内容（中文）

查看翻译对照 →

MCP服务器开发指南

概述

创建MCP（Model Context Protocol，模型上下文协议）服务器，使LLM（大语言模型）能够通过设计精良的工具与外部服务交互。MCP服务器的质量取决于它能否有效支持LLM完成实际任务。

流程

🚀 高级工作流

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

第一阶段：深度研究与规划

1.1 理解现代MCP设计

API覆盖 vs 工作流工具： 在全面的API端点覆盖与专用工作流工具之间取得平衡。工作流工具针对特定任务更便捷，而全面的API覆盖则为Agent提供组合操作的灵活性。不同客户端的表现有所差异——部分客户端受益于结合基础工具的代码执行，而其他客户端更适配高层级工作流。若不确定优先级，优先选择全面的API覆盖。

工具命名与可发现性： 清晰、描述性的工具名称有助于Agent快速找到合适的工具。使用一致的前缀（例如：

github_create_issue

github_list_repos

）和面向动作的命名方式。

上下文管理： 简洁的工具描述以及结果过滤/分页能力对Agent很有帮助。设计返回聚焦、相关数据的工具。部分客户端支持代码执行，可帮助Agent高效过滤和处理数据。

可操作的错误信息： 错误信息应通过具体建议和下一步操作引导Agent解决问题。

1.2 学习MCP协议文档

浏览MCP规范： 从站点地图开始查找相关页面：

https://modelcontextprotocol.io/sitemap.xml

然后使用

.md

后缀获取特定页面的Markdown格式内容（例如：

https://modelcontextprotocol.io/specification/draft.md

）。

重点查看的页面：

规范概述与架构
传输机制（可流式HTTP、标准输入输出stdio）
工具、资源与提示词定义

1.3 学习框架文档

推荐技术栈：

语言：TypeScript（具备高质量SDK支持，在多种执行环境如MCPB中兼容性良好。此外AI模型擅长生成TypeScript代码，得益于其广泛的使用、静态类型和优秀的代码检查工具）
传输方式：远程服务器使用可流式HTTP，采用无状态JSON（相较于有状态会话和流式响应，更易于扩展和维护）；本地服务器使用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模式与示例

1.4 规划实现方案

理解API： 查看服务的API文档，识别关键端点、认证要求和数据模型。必要时使用网络搜索和WebFetch工具。

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

第二阶段：实现

2.1 搭建项目结构

查看语言特定指南进行项目搭建：

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

2.2 实现核心基础设施

创建共享工具：

带认证的API客户端
错误处理助手
响应格式化（JSON/Markdown）
分页支持

2.3 实现工具

针对每个工具：

输入Schema：

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

输出Schema：

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

工具描述：

功能的简洁摘要
参数描述
返回类型Schema

实现细节：

异步/等待（Async/await）处理I/O操作
带有可操作信息的适当错误处理
支持分页（如适用）
使用现代SDK时同时返回文本内容和结构化数据

注解：

```
readOnlyHint
```
: true/false
```
destructiveHint
```
: true/false
```
idempotentHint
```
: true/false
```
openWorldHint
```
: true/false

第三阶段：评审与测试

3.1 代码质量

评审要点：

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

3.2 构建与测试

TypeScript：

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

Python：

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

查看语言特定指南获取详细的测试方法和质量检查清单。

第四阶段：创建评估用例

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

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

4.1 理解评估目的

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

4.2 创建10个评估问题

按照评估指南中的流程创建有效的评估用例：

工具检查：列出可用工具并理解其功能
内容探索：使用只读操作探索可用数据
问题生成：创建10个复杂、真实的问题
答案验证：自行解决每个问题以验证答案正确性

4.3 评估要求

确保每个问题满足：

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

4.4 输出格式

创建如下结构的XML文件：

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>
<!-- More qa_pairs... -->
</evaluation>

参考文件

📚 文档库

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

核心MCP文档（优先加载）

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

SDK文档（第一/二阶段加载）

Python SDK：从

https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

获取

TypeScript SDK：从

https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

获取

语言特定实现指南（第二阶段加载）

🐍 Python实现指南 - 完整的Python/FastMCP指南，包括：
- 服务器初始化模式
- Pydantic模型示例
- 使用
```
@mcp.tool
```
  注册工具
- 完整的工作示例
- 质量检查清单
⚡ TypeScript实现指南 - 完整的TypeScript指南，包括：
- 项目结构
- Zod Schema模式
- 使用
```
server.registerTool
```
  注册工具
- 完整的工作示例
- 质量检查清单

评估指南（第四阶段加载）

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