145 lines
3.9 KiB
Markdown
145 lines
3.9 KiB
Markdown
---
|
||
name: mcp-builder
|
||
version: 1.1.0
|
||
description: "构建 MCP Server，让 LLM 通过 Tool 与外部服务交互。当需要创建 MCP 工具或封装 API 为 MCP 时使用。推荐 TypeScript + MCP SDK。"
|
||
---
|
||
|
||
# MCP Server 开发指南
|
||
|
||
## 触发条件
|
||
|
||
用户需要构建自定义 MCP Server 以封装 API 或服务为 LLM 可调用的 Tool。
|
||
|
||
## 执行流程
|
||
|
||
### Phase 1：研究与规划
|
||
|
||
#### 1.1 理解目标 API
|
||
|
||
- 梳理目标服务的 API 端点、认证方式、数据模型
|
||
- 使用 WebFetch 或 WebSearch 获取 API 文档
|
||
- 列出需要封装的端点，按优先级排序（最常用操作优先）
|
||
|
||
#### 1.2 学习 MCP 协议
|
||
|
||
**加载 MCP 规范**：
|
||
- 起始页：`https://modelcontextprotocol.io/sitemap.xml`
|
||
- 获取特定页面时添加 `.md` 后缀获取 Markdown 格式
|
||
|
||
**加载 MCP SDK 文档**：
|
||
- WebFetch: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
|
||
- SDK 名称虽含 "typescript"，但完全支持纯 TypeScript 项目
|
||
|
||
#### 1.3 设计 Tool
|
||
|
||
| 设计原则 | 说明 |
|
||
|---|---|
|
||
| 命名清晰 | 使用 `prefix_action_target` 格式，如 `github_create_issue` |
|
||
| 描述精准 | 简洁说明功能 + 参数含义 + 返回值结构 |
|
||
| 错误可操作 | 错误信息应引导 LLM 找到解决方案 |
|
||
| 结果聚焦 | 返回精准、相关的数据，支持分页/过滤 |
|
||
| API 覆盖优先 | 不确定时优先提供全面的 API 覆盖，而非少量高层 Workflow Tool |
|
||
|
||
---
|
||
|
||
### Phase 2：实现
|
||
|
||
**推荐技术栈**：
|
||
- **语言**：TypeScript（MCP SDK 原生支持，无需编译，直接运行）
|
||
- **传输**：远程服务用 Streamable HTTP（无状态 JSON），本地用 stdio
|
||
|
||
#### 2.1 项目结构
|
||
|
||
```
|
||
mcp-server-{{name}}/
|
||
├── src/
|
||
│ ├── index.ts # Server entry + tool registration
|
||
│ ├── client.ts # API client with auth
|
||
│ └── tools/ # One file per tool group
|
||
│ ├── resources.ts
|
||
│ └── actions.ts
|
||
├── package.json
|
||
└── README.md
|
||
```
|
||
|
||
#### 2.2 基础设施
|
||
|
||
实现共享工具：
|
||
- API Client（认证、请求头、Base URL）
|
||
- 错误处理 Helper（统一格式，包含 actionable 信息）
|
||
- 响应格式化（JSON 结构化 + 文本摘要）
|
||
- 分页支持
|
||
|
||
#### 2.3 Tool 实现
|
||
|
||
每个 Tool 需要：
|
||
|
||
**输入 Schema**（Zod）：
|
||
- Zod 在纯 TypeScript 中同样可用，提供运行时参数校验
|
||
- 包含约束和清晰的字段描述
|
||
- 在 description 中添加示例值
|
||
|
||
**输出 Schema**（推荐定义）：
|
||
- 使用 `outputSchema` + `structuredContent` 返回结构化数据
|
||
|
||
**Tool 注解**：
|
||
- `readOnlyHint`: 是否只读
|
||
- `destructiveHint`: 是否有破坏性
|
||
- `idempotentHint`: 是否幂等
|
||
|
||
---
|
||
|
||
### Phase 3：审查与测试
|
||
|
||
#### 3.1 代码质量检查
|
||
- 无重复代码（DRY）
|
||
- 一致的错误处理
|
||
- 关键函数和参数有 JSDoc 注释
|
||
- 清晰的 Tool 描述
|
||
|
||
#### 3.2 测试
|
||
|
||
```bash
|
||
# 直接运行验证语法
|
||
node src/index.ts
|
||
|
||
# 使用 MCP Inspector 交互式测试
|
||
npx @modelcontextprotocol/inspector
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 4：集成到项目
|
||
|
||
将构建好的 MCP Server 注册到 `.cursor/mcp.json`：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"{{name}}": {
|
||
"command": "node",
|
||
"args": ["path/to/mcp-server-{{name}}/src/index.ts"],
|
||
"env": {
|
||
"API_KEY": "{{env_var}}"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 验证
|
||
|
||
1. [ ] `node src/index.ts` 启动无错误
|
||
2. [ ] MCP Inspector 可以列出所有 Tool
|
||
3. [ ] 每个 Tool 的输入 Schema 有 Zod 校验
|
||
4. [ ] 每个 Tool 的 description 清晰、包含参数说明
|
||
5. [ ] 错误信息包含具体的修复建议（actionable）
|
||
6. [ ] 需要分页的 Tool 支持 `cursor`/`limit` 参数
|
||
7. [ ] 环境变量用于凭证/密钥，不硬编码
|
||
8. [ ] `.cursor/mcp.json` 注册正确
|
||
|
||
## Tier 3 参考资料（按需读取）
|
||
|
||
- `references/mcp_best_practices.md` — MCP 最佳实践指南
|
||
- `references/node_mcp_server.md` — TypeScript/Node.js 实现详细指南
|