MCP Server Development Guide
创建高质量的 MCP 服务器,让 LLM 能够与外部服务交互。
概述
MCP (Model Context Protocol) 是一种协议,允许 LLM 通过定义良好的工具与外部服务交互。MCP 服务器的质量取决于它能多好地帮助 LLM 完成实际任务。
技术栈推荐
- 语言: TypeScript(推荐)- SDK 支持好,类型安全
- 传输: Streamable HTTP(远程服务器)/ stdio(本地服务器)
开发流程
阶段 1:研究与规划
- 理解 API:研究目标服务的 API 文档
- 工具选择:优先覆盖常用API 端点
- 命名规范:使用清晰的前缀,如
github_create_issue
阶段 2:实现
项目结构 (TypeScript)
my-mcp-server/
├── src/
│ ├── index.ts # 入口文件
│ ├── tools/ # 工具定义
│ └── utils/ # 工具函数
├── package.json
└── tsconfig.json
工具定义要点
// 使用 Zod 定义输入 Schema
const inputSchema = z.object({
query: z.string().describe("搜索关键词"),
limit: z.number().optional().default(10).describe("返回数量")
});
// 工具注解
{
readOnlyHint: true, // 只读操作
destructiveHint: false, // 非破坏性
idempotentHint: true, // 幂等操作
}
阶段 3:测试
# TypeScript 构建
npm run build
# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector
阶段 4:创建评估
创建 10 个复杂、真实的测试问题验证服务器效果。
工具设计原则
- 清晰命名:
service_action_target格式 - 完整描述:包含参数说明和返回类型
- 错误处理:提供可操作的错误信息
- 分页支持:大数据集支持分页
参考资源
- MCP 协议文档:https://modelcontextprotocol.io
- TypeScript SDK:https://github.com/modelcontextprotocol/typescript-sdk
- Python SDK:https://github.com/modelcontextprotocol/python-sdk