---
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 实现详细指南