MCP 服务器开发指南

概述

MCP (Model Context Protocol) 服务器使 LLM 能通过精心设计的工具与外部服务交互。服务器质量取决于它能多好地帮助 LLM 完成真实世界的任务。

开发流程

阶段 1：调研与规划

1.1 理解现代 MCP 设计

API 覆盖 vs 工作流工具: 平衡全面的 API 端点覆盖与专业化工作流工具。不确定时优先选择全面覆盖。

工具命名与可发现性: 清晰、描述性的名称帮助 Agent 快速找到正确工具。使用一致前缀和动作导向命名：

github_create_issue
github_list_repos
slack_send_message

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

可操作的错误信息: 错误信息应引导 Agent 找到解决方案，提供具体建议和下一步操作。

1.2 学习 MCP 协议

关键概念：

传输机制: Streamable HTTP（远程）、stdio（本地）
工具定义: 输入 Schema、输出 Schema、描述
资源与提示: 静态数据暴露和提示模板

MCP 规范文档: https://modelcontextprotocol.io/sitemap.xml

1.3 选择技术栈

推荐: TypeScript（SDK 支持好、类型安全、AI 生成代码质量高）

语言	框架	适用场景
TypeScript	MCP SDK	远程服务器、复杂集成
Python	FastMCP	快速原型、数据处理

1.4 规划实现

审查目标服务 API 文档
识别关键端点、认证要求、数据模型
列出要实现的工具，从最常用操作开始

阶段 2：实现

2.1 项目结构

TypeScript:

my-mcp-server/
├── src/
│   ├── index.ts          # 入口点
│   ├── tools/            # 工具实现
│   │   ├── create.ts
│   │   ├── read.ts
│   │   └── update.ts
│   ├── client.ts         # API 客户端
│   └── utils.ts          # 工具函数
├── package.json
├── tsconfig.json
└── README.md

Python:

my-mcp-server/
├── server.py             # 入口点
├── tools/                # 工具实现
├── client.py             # API 客户端
├── utils.py              # 工具函数
├── pyproject.toml
└── README.md

2.2 核心基础设施

创建共享工具：

API 客户端（含认证）
错误处理辅助函数
响应格式化（JSON/Markdown）
分页支持

2.3 实现工具

每个工具需要：

输入 Schema:

// TypeScript - 使用 Zod
const schema = z.object({
  query: z.string().describe("搜索查询"),
  limit: z.number().optional().default(10).describe("返回结果数量"),
});

# Python - 使用 Pydantic
class SearchInput(BaseModel):
    query: str = Field(description="搜索查询")
    limit: int = Field(default=10, description="返回结果数量")

工具描述:

简洁的功能摘要
参数描述
返回类型说明

实现要点:

Async/await 处理 I/O
正确的错误处理和可操作错误信息
支持分页
返回文本内容和结构化数据

注解:

annotations: {
  readOnlyHint: true,      // 只读操作
  destructiveHint: false,   // 非破坏性
  idempotentHint: true,     // 幂等
  openWorldHint: false,     // 封闭世界
}

阶段 3：审查与测试

3.1 代码质量

无重复代码（DRY 原则）
一致的错误处理
完整的类型覆盖
清晰的工具描述

3.2 构建与测试