SuperAPI AI 工具集

mcp-builder

编程与开发

查看项目

更新于 10-19 16:18

技能介绍

用途

mcp-builder 是一份面向 MCP(Model Context Protocol)服务器开发的实践指南,用于指导开发者构建能够让大语言模型通过设计良好的工具与外部服务交互的服务器。指南强调,MCP 服务器的质量应以“能否帮助 LLM 完成真实世界任务”来衡量。

主要流程与能力

指南给出四阶段工作流。

阶段一:深入调研与规划

  • 理解现代 MCP 设计:在“全面覆盖 API 端点”与“专用工作流工具”之间权衡;不确定时优先保证 API 覆盖面。
  • 工具命名与可发现性:使用清晰、描述性的名称与一致前缀(如 github_create_issue、github_list_repos),采用面向动作的命名。
  • 上下文管理:工具描述简洁,支持结果过滤与分页,返回聚焦且相关的数据。
  • 错误信息可操作:错误应给出具体建议与下一步。
  • 研究 MCP 协议文档:从 sitemap 入手,再以 .md 后缀获取具体页面,重点阅读规范概览与架构、传输机制(streamable HTTP、stdio)、工具、资源与提示定义。
  • 研究框架文档:推荐 TypeScript(SDK 支持好、兼容 MCPB 等执行环境、模型擅长生成);远程服务器用 Streamable HTTP 加无状态 JSON,本地服务器用 stdio。
  • 规划实现:查阅目标服务的 API 文档,确定关键端点、认证要求与数据模型,列出待实现端点并从最常见操作开始。

阶段二:实现

  • 搭建项目结构(参考 TypeScript 或 Python 指南)。
  • 实现共享基础设施:带认证的 API 客户端、错误处理辅助、响应格式化(JSON/Markdown)、分页支持。
  • 实现工具:用 Zod(TypeScript)或 Pydantic(Python)定义输入模式并附约束、描述与示例;尽可能定义 outputSchema,并在响应中使用 structuredContent 输出结构化数据;工具描述包含功能摘要、参数说明与返回类型模式;实现时使用异步 I/O、可操作的错误处理、分页,并在现代 SDK 下同时返回文本内容与结构化数据;添加 readOnlyHint、destructiveHint、idempotentHint、openWorldHint 注解。

阶段三:审查与测试

  • 代码质量:避免重复代码、统一错误处理、完整类型覆盖、清晰的工具描述。
  • 构建与测试:TypeScript 运行 npm run build 验证编译;Python 用 python -m py_compile 验证语法;两者均可用 MCP Inspector(npx @modelcontextprotocol/inspector)测试。

阶段四:创建评测

  • 目的:检验 LLM 能否有效使用该 MCP 服务器回答真实、复杂的问题。
  • 流程:检查工具、以只读操作探索数据、生成 10 个复杂真实问题、自行求解验证答案。
  • 每道题需满足:独立、只读、复杂(需多次工具调用与深入探索)、真实、可验证(可字符串比较的单一明确答案)、稳定(答案不随时间变化)。
  • 输出为 XML 格式,包含 evaluation 与多个 qa_pair(question、answer)。

参考资源

指南列出开发中按需加载的资料:MCP 协议 sitemap、MCP 最佳实践(命名约定、响应格式、分页、传输选择、安全与错误处理)、Python SDK 与 TypeScript SDK 的 README、Python 与 TypeScript 实现指南,以及评测指南。

适用场景

适合需要为 LLM 构建或完善 MCP 服务器、把外部服务封装为可调用工具的开发者,尤其是希望遵循统一设计规范、覆盖测试与评测流程的团队。

限制

该资料为开发指南,未提供具体托管、收费或性能数据;具体实现细节需依赖文中引用的协议与 SDK 文档。