# MCP Builder

在构建 MCP 服务器或 MCP 工具时使用, , 系统化的生产级 MCP 构建方法论，覆盖工具设计、错误处理、传输层选择与测试，让 AI 助手连接外部能力

- Repository: https://github.com/jnMetaCode/superpowers-zh (8437 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add jnMetaCode/superpowers-zh --skill mcp-builder -g -a claude-code -y`
Codex: `npx skills add jnMetaCode/superpowers-zh --skill mcp-builder -g -a codex -y`
Cursor: `npx skills add jnMetaCode/superpowers-zh --skill mcp-builder -g -a cursor -y`
Gemini CLI: `npx skills add jnMetaCode/superpowers-zh --skill mcp-builder -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add jnMetaCode/superpowers-zh`

## Description

在构建 MCP 服务器或 MCP 工具时使用, , 系统化的生产级 MCP 构建方法论，覆盖工具设计、错误处理、传输层选择与测试，让 AI 助手连接外部能力

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# MCP 服务器构建

系统化设计、实现、测试和部署 Model Context Protocol 服务器的方法论。

## 1. 协议核心概念

MCP 定义三种原语：

- **Tools（工具）**：AI 助手主动调用的函数，有副作用。如搜索、创建、删除操作。
- **Resources（资源）**：AI 助手只读访问的数据源，用 URI 标识。如 `users://{id}/profile`。
- **Prompts（提示词模板）**：预定义交互模板，引导用户触发工作流。

**选择原则：** 执行操作 → Tool | 读取数据 → Resource | 引导交互 → Prompt

## 2. 项目结构规范

### TypeScript
```
my-mcp-server/
├── src/
│   ├── index.ts          # 入口，注册 tools/resources
│   ├── tools/             # 按功能拆分
│   ├── resources/
│   └── lib/               # 客户端封装、校验逻辑
├── tests/
├── package.json
└── tsconfig.json
```

关键依赖：`@modelcontextprotocol/sdk` + `zod`

### Python
```
my-mcp-server/
├── src/my_mcp_server/
│   ├── server.py
│   ├── tools/
│   └── lib/
├── tests/
└── pyproject.toml
```

关键依赖：`mcp` + `pydantic`

## 3. Tool 设计原则

### 命名
- `snake_case` 格式，动词开头：`search_users`、`create_issue`、`delete_file`
- 名称自解释，AI 助手靠名称选工具，模糊命名导致误调用

### 参数
- 每个参数有类型约束和 `.describe()` 描述
- 可选参数给默认值，减少 AI 决策负担
- 用枚举代替布尔开关

```typescript
server.tool("search_issues", {
  query: z.string().describe("搜索关键词"),
  status: z.enum(["open", "closed", "all"]).default("open").describe("状态筛选"),
  limit: z.number().min(1).max(100).default(20).describe("返回上限"),
}, async ({ query, status, limit }) => { /* ... */ });
```

### 描述
说明**用途 + 返回内容 + 限制**，这是 AI 选择工具的关键依据：

```typescript
server.tool("search_users",
  "根据姓名或邮箱搜索用户。返回 ID、姓名、邮箱列表。模糊匹配，最多 50 条。",
  schema, handler);
```

### 输出
- 结构化数据 → JSON，人类可读内容 → Markdown
- 始终用 `content: [{ type: "text", text: "..." }]` 格式返回

## 4. 输入验证和错误处理

用 Zod/Pydantic 做 Schema 级校验，业务级校验放 handler 开头：

The rest: https://github.com/jnMetaCode/superpowers-zh/blob/HEAD/skills/mcp-builder/SKILL.md