Mcp Builder

jnMetaCode/superpowers-zh/skills/mcp-builder

by jnMetaCode2daf57c0fb157521de24c62ac9c3254630eefbedMITListed Oct 9, 2026Updated Oct 9, 2026

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

Instructions onlyAI & Agents Software Development

AI-generated overview

A methodology for designing, implementing, testing and deploying production-grade MCP servers and tools.

What it does: Provides a structured methodology for building Model Context Protocol servers, covering protocol primitives (tools, resources, prompts), project layout for TypeScript and Python, tool naming and parameter design, input validation and error handling, resource lifecycle, testing, security and deployment. It includes code examples, a debugging troubleshooting table and a build checklist. The deliverable is guidance and reference patterns rather than generated files.
When to use it: Use when building or extending an MCP server or MCP tool that connects an AI assistant to external capabilities. Also useful when reviewing tool descriptions, error handling, transport choice or testing strategy for an existing MCP server.
Requirements: No scripts or runtime required; the document is instructions only. Its examples reference TypeScript or Python with the MCP SDK, Zod or Pydantic, and optional npm, pip or Docker for distribution.

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

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

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 }) => { /* ... */ });

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);

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

输出

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

4. 输入验证和错误处理

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

typescript

server.tool("get_user", { id: z.string() }, async ({ id }) => {  try {    const user = await db.getUser(id);    if (!user) {      return {        content: [{ type: "text", text: `用户 ${id} 不存在，请检查 ID。` }],        isError: true,      };    }    return { content: [{ type: "text", text: JSON.stringify(user, null, 2) }] };  } catch (err) {    return {      content: [{ type: "text", text: `查询失败：${err.message}` }],      isError: true,    };  }});

server.tool("get_user", { id: z.string() }, async ({ id }) => {  try {    const user = await db.getUser(id);    if (!user) {      return {        content: [{ type: "text", text: `用户 ${id} 不存在，请检查 ID。` }],        isError: true,      };    }    return { content: [{ type: "text", text: JSON.stringify(user, null, 2) }] };  } catch (err) {    return {      content: [{ type: "text", text: `查询失败：${err.message}` }],      isError: true,    };  }});

错误处理四原则：

永远不让服务器崩溃 — try/catch 包裹所有外部调用
返回可操作的错误信息 — 告诉 AI 问题是什么、能做什么
使用 isError: true — 让 AI 知道调用失败
区分错误类型 — 参数错误、权限不足、资源不存在、服务不可用

5. 资源管理和生命周期

typescript

// 资源注册server.resource("user-profile", "users://{userId}/profile", async (uri) => {  const profile = await db.getProfile(extractId(uri));  return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(profile) }] };});
// 生命周期：先初始化 → 再 connect → 监听关闭信号const db = await Database.connect(config.dbUrl);await server.connect(new StdioServerTransport());process.on("SIGINT", async () => { await db.disconnect(); await server.close(); process.exit(0); });

// 资源注册server.resource("user-profile", "users://{userId}/profile", async (uri) => {  const profile = await db.getProfile(extractId(uri));  return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(profile) }] };});
// 生命周期：先初始化 → 再 connect → 监听关闭信号const db = await Database.connect(config.dbUrl);await server.connect(new StdioServerTransport());process.on("SIGINT", async () => { await db.disconnect(); await server.close(); process.exit(0); });

关键点：使用连接池、所有外部调用设超时、优雅关闭清理资源。

6. 测试策略

单元测试 — 业务逻辑与 MCP 注册分离

typescript

// tools/search.ts 导出纯函数export async function searchUsers(query: string, limit: number) { /* ... */ }
// search.test.ts 独立测试test("返回匹配结果", async () => {  const results = await searchUsers("alice", 10);  expect(results[0].name).toContain("Alice");});

// tools/search.ts 导出纯函数export async function searchUsers(query: string, limit: number) { /* ... */ }
// search.test.ts 独立测试test("返回匹配结果", async () => {  const results = await searchUsers("alice", 10);  expect(results[0].name).toContain("Alice");});

集成测试 — 用 SDK Client 做端到端验证

typescript

const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();await server.connect(serverTransport);const client = new Client({ name: "test", version: "1.0.0" });await client.connect(clientTransport);const result = await client.callTool("search_users", { query: "test" });expect(result.isError).toBeFalsy();

const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();await server.connect(serverTransport);const client = new Client({ name: "test", version: "1.0.0" });await client.connect(clientTransport);const result = await client.callTool("search_users", { query: "test" });expect(result.isError).toBeFalsy();

MCP Inspector — 交互式调试

在浏览器中查看所有 tools/resources，手动调用并查看结果。

测试要点：每个 Tool 覆盖正常 + 异常路径、边界值、外部服务失败模拟。

7. 安全考虑

权限控制：

最小权限原则，读写 Tool 分离
危险操作要求确认参数（如 confirm: true）

输入安全：

SQL 注入 → 参数化查询，绝不拼接
路径遍历 → 校验路径，禁止 ../
命令注入 → 用 execFile 而非 exec

敏感数据：

密钥通过环境变量传入，不硬编码
日志不打印完整敏感信息
返回数据做脱敏处理

沙箱：文件操作限制目录、网络请求限制白名单、设置资源配额。

8. 部署和分发

npm 发布

用户配置：

json

{ "mcpServers": { "myservice": { "command": "npx", "args": ["@yourorg/mcp-server-myservice"], "env": { "API_KEY": "xxx" } } } }

{ "mcpServers": { "myservice": { "command": "npx", "args": ["@yourorg/mcp-server-myservice"], "env": { "API_KEY": "xxx" } } } }

pip 发布

Docker — 适用于复杂依赖或隔离场景

dockerfile

FROM node:20-slimWORKDIR /appCOPY package*.json ./ && RUN npm ci --productionCOPY dist ./distENTRYPOINT ["node", "dist/index.js"]

FROM node:20-slimWORKDIR /appCOPY package*.json ./ && RUN npm ci --productionCOPY dist ./distENTRYPOINT ["node", "dist/index.js"]

9. 调试技巧

关键：MCP 用 stdio 通信，不能用 console.log，会破坏协议流。

typescript

// 错误console.log("debug");// 正确console.error("[DEBUG]", info);// 更好server.sendLoggingMessage({ level: "info", data: "处理中" });

// 错误console.log("debug");// 正确console.error("[DEBUG]", info);// 更好server.sendLoggingMessage({ level: "info", data: "处理中" });

常见问题：

症状	原因	解决
启动无响应	transport 未连接	检查 `server.connect()`
Tool 不出现	注册在 connect 之后	先注册再 connect
AI 不调用 Tool	描述不清晰	改善名称和描述
参数总错	Schema 不明确	添加 `.describe()`
调用超时	外部服务慢	加超时和缓存

调试流程： Inspector 验证基本功能 → 手动调用确认输入输出 → 连接真实 AI 客户端观察调用模式 → 根据实际行为调整设计。

10. 构建检查清单

设计

明确 Tools vs Resources vs Prompts 分工
Tool 命名 动词_名词，描述说明用途和返回内容
参数简洁，可选参数有合理默认值

实现

输入用 Zod/Pydantic 校验
外部调用有 try/catch 和超时
错误返回 isError: true 并附可操作信息
不用 console.log（用 stderr 或 SDK 日志）
敏感数据走环境变量

测试

核心逻辑有单元测试
有集成测试验证 MCP 协议交互
用 MCP Inspector 手动验证过
用真实 AI 客户端测试过

部署

README 含安装和配置说明
提供客户端配置 JSON 示例
遵循 semver，无硬编码密钥

Source and attribution

Source:jnMetaCode/superpowers-zhinskills/mcp-builderat commit2daf57c

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Mcp Builder

MCP 服务器构建

1. 协议核心概念

2. 项目结构规范

TypeScript

Python

3. Tool 设计原则

命名

参数

描述

输出

4. 输入验证和错误处理

5. 资源管理和生命周期

6. 测试策略

单元测试 — 业务逻辑与 MCP 注册分离

集成测试 — 用 SDK Client 做端到端验证

MCP Inspector — 交互式调试

7. 安全考虑

8. 部署和分发

npm 发布

pip 发布

Docker — 适用于复杂依赖或隔离场景

9. 调试技巧

10. 构建检查清单

设计

实现

测试

部署

Source and attribution

More from jnMetaCode/superpowers-zh

Using Superpowers

Writing Plans

Verification Before Completion

Using Git Worktrees

Test Driven Development

Requesting Code Review

More in AI & Agents

Ppt Template Creator

Skill Development

Plugin Structure

Command Development

Claude Md Improver

Find Skills