MCP 服务器开发指南

概述

构建 MCP（Model Context Protocol）服务器，使大模型能通过设计良好的 工具（tools） 与外部服务交互。服务器质量取决于：模型能否借助你的工具 稳定完成真实任务。

流程

高层工作流

高质量 MCP 服务器大致分四阶段：

阶段一：深入调研与规划

1.1 理解当代 MCP 设计

API 覆盖面 vs. 工作流型工具：
在「尽可能覆盖 API」与「为特定任务封装高层工具」之间取舍。工作流工具对固定场景更省事，广覆盖则让智能体自由组合调用。不同客户端表现不同——有的适合配合代码执行拼基础工具，有的更适合高层工作流。不确定时，优先广覆盖 API。

工具命名与可发现性：
名称要清晰、可检索；建议统一前缀（如 github_create_issue、github_list_repos），动词开头、表意明确。

上下文管理：
工具描述宜简洁；结果宜可分页、可筛选。部分客户端支持代码执行，便于智能体在本地过滤数据。

可行动的错误信息：
错误应指出 下一步 与 如何修正，而不是只抛栈。

1.2 阅读 MCP 协议文档

从站点地图入手：https://modelcontextprotocol.io/sitemap.xml
具体页面可加 .md 后缀取 Markdown（如 https://modelcontextprotocol.io/specification/draft.md）。

重点包括：规范总览与架构、传输方式（streamable HTTP、stdio）、工具 / 资源 / 提示词定义等。

1.3 阅读框架文档

推荐栈：

语言：TypeScript（SDK 成熟、运行环境兼容性好，且模型写 TS 质量通常较高）
传输：远程服务用 Streamable HTTP（无状态 JSON，易扩展维护）；本地服务可用 stdio。

文档加载：

MCP 最佳实践：本技能包内 ./reference/mcp_best_practices.md
TypeScript：可拉取 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md，并参阅 ./reference/node_mcp_server.md
Python：可拉取 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md，并参阅 ./reference/python_mcp_server.md

1.4 规划实现

理解 API： 阅读服务 API 文档，弄清端点、鉴权、数据模型；可用联网搜索与按需抓取页面。

工具选择： 仍以广覆盖为主；列出待实现端点，从最高频操作开始。

阶段二：实现

2.1 项目结构

见语言指南：./reference/node_mcp_server.md、./reference/python_mcp_server.md（目录、package.json/pyproject 等）。

2.2 核心基础设施

共用能力建议包括：带鉴权的 API 客户端、错误处理辅助、响应格式化（JSON/Markdown）、分页支持等。

2.3 实现工具

对每个工具：

输入 Schema： TypeScript 用 Zod，Python 用 Pydantic；约束写清楚，字段描述里可给示例。

输出 Schema： 尽量定义 outputSchema；TypeScript SDK 可在响应里用 structuredContent，便于客户端解析。

工具描述： 功能摘要、参数说明、返回结构。

实现要点： I/O 用 async；错误信息可行动；需要时分页；现代 SDK 下可同时返回文本与结构化内容。

注解（Annotations）： readOnlyHint、destructiveHint、idempotentHint、openWorldHint 等按语义设置。

阶段三：评审与测试

3.1 代码质量

避免重复（DRY）、错误处理一致、类型覆盖完整、工具描述清晰。

3.2 构建与测试

TypeScript： npm run build；用 MCP Inspector：npx @modelcontextprotocol/inspector
Python： python -m py_compile ...；同样可用 MCP Inspector

细节与检查清单见各语言指南。

阶段四：编写评测（Evaluations）

实现完成后，应用评测检验 真实复杂问题下模型能否用好你的服务器。

完整说明见 ./reference/evaluation.md。

4.1 评测目的

验证：在给定 MCP 下，模型能否完成 贴近真实、需要多步调用 的任务。

4.2 编写 10 道评测题

按评测指南流程：

工具巡检：列出工具并理解能力
内容探索：用只读操作探索数据
出题：编写 10 道复杂、贴近真实的题目
自解验证：自行解答以确认标答

4.3 题目要求

每道题应：相互独立、只读/非破坏、足够复杂（多工具、深探索）、贴近真实用例、答案唯一可字符串比对验证、答案稳定（不随时间漂移）。

4.4 输出格式

使用如下 XML 结构（示例）：

<evaluation>
  <qa_pair>
    <question>……</question>
    <answer>……</answer>
  </qa_pair>
</evaluation>

参考文件

文档库（按需加载）

MCP 核心（优先）

协议：从 https://modelcontextprotocol.io/sitemap.xml 导航，页面用 .md 后缀
./reference/mcp_best_practices.md：命名、响应格式、分页、传输选择、安全与错误等通用规范

SDK（阶段一/二）

Python / TypeScript SDK README（见上文 raw 地址）

语言实现指南（阶段二）

./reference/python_mcp_server.md：FastMCP、Pydantic、@mcp.tool 等
./reference/node_mcp_server.md：Zod、server.registerTool 等

评测（阶段四）

./reference/evaluation.md：出题、验证、XML 格式、脚本运行方式等

MCP 服务器构建

安装方式

CLI 安装（推荐）

手动下载安装

触发指令

使用指南