名称：构建MCP服务器描述：指导创建高质量的MCP（模型上下文协议）服务器，使LLM能够通过精心设计的工具与外部服务交互。在构建MCP服务器以集成外部API或服务时使用，无论是使用Python（FastMCP）还是Node/TypeScript（MCP SDK）。涵盖工具设计、身份验证、Docker部署和评估创建。不适用于使用现有MCP服务器（直接使用服务器）。

MCP服务器开发指南

概述

创建MCP（模型上下文协议）服务器，使LLM能够通过精心设计的工具与外部服务交互。MCP服务器的质量衡量标准是它使LLM完成现实世界任务的能力。

高级工作流程

创建高质量的MCP服务器涉及四个主要阶段：

阶段1：深度研究与规划

1.1 理解现代MCP设计

API覆盖与工作流工具： 平衡全面的API端点覆盖与专门的工作流工具。不确定时，优先考虑全面的API覆盖。

工具命名与可发现性： 使用一致的前缀（例如github_create_issue、github_list_repos）和面向操作的命名。

上下文管理： 设计返回聚焦、相关数据的工具。支持过滤/分页。

可操作的错误消息： 错误消息应通过具体建议指导代理找到解决方案。

1.2 研究MCP协议文档

从站点地图开始：https://modelcontextprotocol.io/sitemap.xml

获取带有.md后缀的页面（例如https://modelcontextprotocol.io/specification/draft.md）。

关键页面：规范概述、传输机制、工具/资源/提示定义。

1.3 研究框架文档

推荐技术栈：

语言：TypeScript（高质量SDK，良好的AI代码生成）
传输：用于远程服务器的Streamable HTTP，用于本地服务器的stdio

加载框架文档：

MCP最佳实践 - 核心指南
TypeScript指南 - TypeScript模式
Python指南 - Python/FastMCP模式

SDK文档：

TypeScript：https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Python：https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

1.4 规划您的实现

查看服务的API文档。列出要实现的端点，从最常见的操作开始。

阶段2：实现

2.1 设置项目结构

参见语言特定指南：

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

2.2 实现核心基础设施

创建共享实用程序：

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

2.3 实现工具

对于每个工具：

输入模式：

使用Zod（TypeScript）或Pydantic（Python）
包含约束和清晰的描述

输出模式：

尽可能定义outputSchema
在响应中使用structuredContent

工具描述：

简洁的摘要、参数描述、返回类型

注解：

readOnlyHint、destructiveHint、idempotentHint、openWorldHint

阶段3：审查与测试

3.1 代码质量

审查：DRY原则、一致的错误处理、完整的类型覆盖、清晰的描述。

3.2 构建与测试

TypeScript：

npm run build
npx @modelcontextprotocol/inspector

Python：

python -m py_compile your_server.py
# 使用MCP Inspector测试

阶段4：创建评估

创建10个评估问题以测试LLM使用您服务器的有效性。

每个问题的要求：

独立、只读、复杂、现实、可验证、稳定

输出格式：

<evaluation>
  <qa_pair>
    <question>您的问题在这里</question>
    <answer>预期答案</answer>
  </qa_pair>
</evaluation>

参见评估指南获取完整指南。

Docker/容器化

传输安全（allowed_hosts）

FastMCP验证Host头。对于Docker，配置：

from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings

transport_security = TransportSecuritySettings(
    allowed_hosts=[
        "127.0.0.1:*", "localhost:*", "[::1]:*",
        "mcp-server:*",  # Docker容器名称
        "0.0.0.0:*",
    ],
)
mcp = FastMCP("my_server", transport_security=transport_security)

健康检查端点

通过中间件添加/health端点（参见参考资料中的完整示例）。

验证

运行：python3 scripts/verify.py

预期：✓ building-mcp-servers skill ready

如果验证失败

运行诊断：检查references/文件夹是否存在
检查：所有参考文件是否存在
如果仍然失败，请停止并报告

参考资料

MCP最佳实践 - 通用指南
Python指南 - Python/FastMCP模式
TypeScript指南 - TypeScript模式
TaskFlow模式 - 内部服务器模式
评估指南 - 创建评估