mcp-builder

Overview

mcp-builder 是什么

mcp-builder 是一项面向开发的 skill，适合正在构建 MCP（Model Context Protocol）服务器的团队使用。它旨在帮助开发者创建结构清晰、能让模型调用外部服务的服务器，并提供关于架构、命名、传输方式、实现模式和评估方法的实用指导。

mcp-builder 本身并不是一个可直接运行的服务器，而更像是一份以参考资料为核心的构建指南。在这项 skill 中，核心内容是 SKILL.md，并辅以 reference/ 目录下的文档和 scripts/ 目录中的辅助脚本。

谁适合使用 mcp-builder

这项 skill 特别适合以下人群：

• 正在为 API、SaaS 平台、内部系统或业务流程创建新的 mcp-server 的开发者
• 需要在 Python FastMCP 和 Node/TypeScript MCP SDK 方案之间做选型的团队
• 希望为 Claude 或其他兼容 Anthropic 工作流优化 mcp-tools 命名、schema 设计和响应模式的构建者
• 想用可重复的方法、通过贴近真实场景的工具型问题来评估服务器质量的工程师

这项 skill 解决哪些问题

mcp-builder 聚焦于那些最影响 MCP 服务器实际可用性的开发环节：

• 在广覆盖的 API 能力与更高层级的工作流工具之间做取舍
• 为服务器和工具命名，让 agent 更容易发现和调用
• 设计既适合结构化处理、又便于阅读的输出结果
• 选择合适的传输方式，包括 stdio 或 streamable HTTP
• 使用受支持的 MCP SDK 模式，在 Python 或 Node/TypeScript 中实现服务器
• 测试 agent 是否真的能借助所提供的工具完成复杂任务

仓库中包含什么内容

已发布仓库体现的是一种以文档为先、辅以实现参考和评估辅助工具的结构：

• SKILL.md：MCP 服务器开发主流程说明
• reference/mcp_best_practices.md：命名、分页、响应格式和传输方式指导
• reference/python_mcp_server.md：Python FastMCP 实现模式
• reference/node_mcp_server.md：Node/TypeScript MCP SDK 实现模式
• reference/evaluation.md：评估设计规则
• scripts/evaluation.py 和 scripts/connections.py：用于对 MCP 服务器运行评估 harness
• scripts/example_evaluation.xml 和 scripts/requirements.txt：评估相关的支持文件

mcp-builder 的亮点是什么

mcp-builder 的价值在于，它对服务器质量的判断不只是“把 endpoint 暴露出来”这么简单。源文档明确把成功标准放在：LLM 是否能借助这个 MCP 服务器，较好地完成真实任务。这让它在你关注实际 agent 表现、而不仅仅是技术实现完整度时，尤其有参考价值。

什么情况下适合用 mcp-builder

如果你正处于以下场景，mcp-builder 会很合适：

• 从零规划一个新的 MCP 集成
• 重构已有服务器，解决工具命名不清或 schema 设计薄弱的问题
• 比较 Python 和 TypeScript 两种实现路线
• 在发布 MCP 服务器前建立内部质量检查清单
• 设计评估题，验证服务器是否支持真实工作流

什么情况下 mcp-builder 可能不是最佳选择

如果你需要的是以下内容，这项 skill 的帮助可能有限：

• 针对某个特定服务、无需二次开发即可直接使用的 MCP 服务器包
• 通用的非 MCP API 教程
• 托管式产品或基于 GUI 的配置体验

更准确地说，它是一份面向构建者的指南和评估辅助工具，而不是一个已经做好的终端用户集成方案。

How to Use

安装 mcp-builder

从 anthropics/skills 仓库添加这个 skill：

npx skills add https://github.com/anthropics/skills --skill mcp-builder

安装完成后，打开本地 skill 文件，按下面的顺序阅读，能最快进入状态。

先从主流程开始

先阅读 SKILL.md。这是这项 skill 的主指南，会介绍如何开发高质量 MCP 服务器的整体流程。

从仓库内容来看，这一流程首先强调调研与规划，包括一些当前常见的 MCP 设计取舍，例如：

• 在全面覆盖 endpoint 与提供更专门的工作流工具之间取得平衡
• 使用清晰、描述性强的工具命名
• 通过简洁说明、过滤和分页支持来控制上下文规模

写代码前先看最佳实践参考

接着阅读 reference/mcp_best_practices.md。这是最快了解 mcp-builder 所采用规范和约定的文件。

其中重点涵盖：

• Python 和 Node/TypeScript 的服务器命名约定
• 采用带服务前缀的 snake_case 工具命名方式
• JSON 和 Markdown 的响应格式建议
• 分页字段约定，例如 limit、has_more、next_offset 和 total_count
• 传输方式建议，包括用于远程场景的 streamable HTTP，以及用于本地集成的 stdio

如果你想在动手实现前先确定 MCP 服务器整体应该长什么样，这份参考文档尤其值得先看。

选择你的实现路径

使用 FastMCP 的 Python 路线

如果你使用 Python 开发，请阅读 reference/python_mcp_server.md。

从仓库内容可以看出，这份指南包括：

• 如何使用 MCP Python SDK 中的 FastMCP
• 基于装饰器的工具注册方式 @mcp.tool
• 基于 Pydantic 的输入校验模式
• 使用 {service}_mcp 约定的服务器命名方式

对于希望使用更高层框架、并采用直接明了的工具注册模式的 Python 团队来说，mcp-builder 很适合参考。

使用 MCP SDK 的 Node/TypeScript 路线

如果你使用 Node 或 TypeScript 开发，请阅读 reference/node_mcp_server.md。

从仓库内容可以看出，这份指南包括：

• 如何使用 @modelcontextprotocol/sdk 中的 McpServer
• registerTool 的用法
• 基于 Zod 的输入校验
• StreamableHTTPServerTransport 和 StdioServerTransport
• 使用 structuredContent 的结构化输出模式

如果你的团队已经在交付 TypeScript 服务，或者希望借助 Zod 获得更顺手的 schema 体验，这条路线会比较契合。

用评估指南验证真实可用性

mcp-builder 最有价值的部分之一，就是它对评估的重视。当你的服务器已经具备基本可测试能力时，就可以阅读 reference/evaluation.md。

根据仓库中的说明，评估建议是设计 10 个人类可读的问题，这些问题应当满足：

• 只读
• 彼此独立
• 不会造成破坏性影响
• 能用单一且可验证的值回答
• 复杂度足以需要多次工具调用

这也让它非常适合作为 skill-testing 的辅助场景。它能帮助你验证 LLM 是否真的能有效使用你的服务器，而不只是确认工具 handler 能正常运行。

查看辅助脚本

scripts/ 目录提供了与评估相关的辅助支持。

根据仓库内容：

• scripts/connections.py 包含 MCP 服务器的轻量级连接处理逻辑，支持多种连接类型，包括 stdio、与 SSE 相关的客户端代码，以及 streamable HTTP 客户端代码
• scripts/evaluation.py 是一个 MCP 服务器评估 harness，可通过 Anthropic API 调用 Claude 来运行测试问题
• scripts/example_evaluation.xml 提供了问题与答案配对的 XML 结构示例
• scripts/requirements.txt 列出了评估工具所需的 Python 依赖

如果你的目标是在实际工作流中用 Claude 对 MCP 服务器进行基准评估，这几份文件值得重点查看。

推荐采用流程

在新项目中使用 mcp-builder，一个比较实用的方式是：

1. 安装这个 skill。
2. 阅读 SKILL.md，了解整体流程。
3. 查看 reference/mcp_best_practices.md，先确定命名、传输方式和响应格式。
4. 根据技术栈选择 reference/python_mcp_server.md 或 reference/node_mcp_server.md。
5. 构建第一组工具，确保命名清晰、schema 明确。
6. 结合 reference/evaluation.md 设计贴近真实场景的评估问题。
7. 如果你想使用自动化评估 harness，再深入查看 scripts/evaluation.py 及相关文件。

安装决策参考

当你的团队需要的是方法论和统一规范，而不只是几段代码示例时，mcp-builder 会特别值得推荐。尤其适合你仍在思考下面这些问题的时候：

• 我们应该暴露原始 API 操作、工作流工具，还是两者都提供？
• 工具应该怎样命名，Claude 才更容易自然地发现并调用？
• 本地部署和远程部署分别该选哪种传输方式？
• 我们该如何证明这个服务器在真实 agent 任务中表现良好？

如果这些正是你当前的主要卡点，那么这项 skill 很值得安装。

FAQ

mcp-builder 是可以直接运行的 MCP 服务器吗？

不是。根据仓库结构和文档说明，mcp-builder 是一项以指导为主、用于构建 MCP 服务器的 skill。它包含参考资料和评估辅助工具，但并不是某个特定服务的现成可用服务器。

如何安装 mcp-builder？

使用：

npx skills add https://github.com/anthropics/skills --skill mcp-builder

然后在本地阅读 SKILL.md 和 reference/ 目录下的文档。

mcp-builder 支持 Python 和 Node 吗？

支持。仓库中分别提供了两套参考文档：

• reference/python_mcp_server.md
• reference/node_mcp_server.md

其中 Python 指南采用 FastMCP 模式，Node/TypeScript 指南则使用 MCP TypeScript SDK。

mcp-builder 能帮助做 MCP 服务器测试吗？

可以。这正是它最实用的优势之一。reference/evaluation.md 说明了如何设计贴近真实场景的评估问题，而 scripts/evaluation.py 则提供了一个通过 Anthropic API 调用 Claude 的评估 harness。

mcp-builder 提供了哪些传输方式建议？

最佳实践文档建议：远程和多客户端场景优先使用 streamable HTTP，本地集成和命令行场景使用 stdio。文档还提到，在最佳实践中更推荐 streamable HTTP，而不是 SSE。

mcp-builder 推荐哪些命名规范？

仓库中的建议包括：

• Python 服务器名称使用 {service}_mcp
• Node/TypeScript 服务器名称使用 {service}-mcp-server
• 工具名称使用带服务前缀的 snake_case，例如 github_create_issue

当存在多个 MCP 工具可用时，这些约定有助于提升可发现性。

mcp-builder 适合生产团队使用吗？

适合，尤其适合希望把 MCP 开发流程做得更规范的团队。它对生产环境规划很有帮助，因为覆盖了实现模式、传输方式选择、命名一致性和评估标准。不过，你仍然需要自己构建并维护真正的服务器实现。

什么情况下可以跳过 mcp-builder？

如果你已经有成熟的 MCP 服务器架构，只需要一个非常具体的代码示例，或者你根本不是在构建 MCP 工具，那么可以跳过它。mcp-builder 的最大价值，体现在新建或持续改进 MCP 服务器时的设计、实现和评估阶段。