MCP Server Development Guide
本指南面向希望构建高质量 MCP(模型上下文协议)服务器的开发者。其核心理念是:MCP 服务器的质量取决于它能在多大程度上帮助 LLM 完成真实世界任务。整个流程分为四个阶段。
一、深入调研与规划 需理解现代 MCP 设计要点:在 API 覆盖度与专用工作流工具之间取得平衡,不确定时优先保证全面的 API 覆盖;工具命名应清晰、带一致前缀并使用面向动作的表述(如 github_create_issue、github_list_repos);工具描述应简洁,结果应支持过滤与分页,以控制上下文占用;错误信息应给出具体建议和下一步指引。随后研读 MCP 协议文档(从 https://modelcontextprotocol.io/sitemap.xml 入手,用 .md 后缀获取 Markdown 页面,了解规范架构、传输机制如 streamable HTTP 与 stdio、工具/资源/提示定义),并阅读框架文档。推荐技术栈为 TypeScript(SDK 支持好、在 MCPB 等执行环境中兼容性好,且模型擅长生成 TypeScript 代码),远程服务器使用 Streamable HTTP 与无状态 JSON,本地服务器使用 stdio。最后梳理目标服务的 API 文档,确定端点、认证方式与数据模型,并列出要实现的工具。
二、实现 按语言指南搭建项目结构,先实现共享基础设施:带认证的 API 客户端、错误处理辅助、响应格式化(JSON/Markdown)、分页支持。每个工具的输入 schema 使用 Zod(TypeScript)或 Pydantic(Python),包含约束、清晰描述与字段示例;尽可能定义 outputSchema,并在响应中使用 structuredContent 返回结构化数据。工具描述应包含功能摘要、参数说明与返回类型 schema。实现采用异步 I/O、可操作的错误处理与分页支持,并使用 readOnlyHint、destructiveHint、idempotentHint、openWorldHint 注解标注工具行为特性。
三、评审与测试 检查代码是否遵循 DRY、错误处理是否一致、类型覆盖是否完整、工具描述是否清晰。TypeScript 运行 npm run build 验证编译,Python 使用 python -m py_compile your_server.py 检查语法,并用 MCP Inspector(npx @modelcontextprotocol/inspector)测试。
四、创建评估 实现完成后编写 10 道评估题,检验 LLM 能否有效使用该服务器回答真实、复杂的问题。流程为:检查工具、以只读方式探索数据、生成问题、自行验证答案。每道题须独立、只读、复杂(需多次工具调用)、真实、可通过字符串比对验证且答案稳定。输出为 XML 文件,结构示例: <evaluation> <qa_pair> <question>问题文本</question> <answer>答案</answer> </qa_pair> </evaluation>
参考资料包括 MCP 最佳实践(命名规范、响应格式、分页、传输选择、安全与错误处理)、TypeScript SDK(https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md)与 Python SDK(https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md)文档,以及各语言的实现指南与评估指南。