MCP Builder

来源: modelcontextprotocol/specification + Anthropic 官方文档 + 社区最佳实践

发布时间: 2026-08

理念: "把你的系统能力，变成 AI 能安全调用的标准接口。"

🔌 MCP Builder — MCP Server / Tool 构建指南

把现有 API、数据库、文档系统或内部服务封装成 Model Context Protocol (MCP) 标准接口，让 AI 客户端以统一方式发现、调用和组合你的能力。

为什么需要 MCP

一句话：MCP 是 AI 时代的「USB-C」，让你的系统能力即插即用。

核心技术栈

Model Context Protocol  # 协议规范
JSON-RPC 2.0            # 通信格式
stdio / SSE / HTTP      # 传输层
Tools                   # AI 可调用的函数
Resources               # AI 可读取的上下文/文档
Prompts                 # 可复用的提示词模板
Sampling                # Server 请求 LLM 补全的能力

协议三要素

项目结构模板

my-mcp-server/
├── src/
│   ├── index.ts              # Server 入口
│   ├── tools/                # Tool 定义与实现
│   │   ├── users.ts
│   │   └── orders.ts
│   ├── resources/            # Resource 定义
│   │   └── api-docs.ts
│   ├── prompts/              # Prompt 模板
│   │   └── code-review.ts
│   └── utils/
│       └── errors.ts
├── package.json
├── tsconfig.json
└── claude_config.json        # Claude Code 本地配置（可选）

开发到接入全链路

Step 1：选择传输协议

新手建议：先用 stdio，5 分钟跑通第一个 Tool。

Step 2：定义你的第一个 Tool

以把内部用户查询 API 封装为 MCP Tool 为例：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "user-service-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 1. 声明 Tool 列表
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "query_user",
        description: "根据用户 ID 或手机号查询用户信息",
        inputSchema: {
          type: "object",
          properties: {
            userId: { type: "string", description: "用户唯一 ID" },
            phone: { type: "string", description: "用户手机号" }
          },
          anyOf: [{ required: ["userId"] }, { required: ["phone"] }]
        }
      }
    ]
  };
});

// 2. 实现 Tool 调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "query_user") {
    const { userId, phone } = request.params.arguments || {};
    const user = await fetchUserFromBackend({ userId, phone });
    return {
      content: [{ type: "text", text: JSON.stringify(user, null, 2) }]
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

// 3. 启动 stdio 传输
const transport = new StdioServerTransport();
await server.connect(transport);

Step 3：在 Claude Code 中接入

// ~/.claude/settings.json 或项目级 .claude/settings.json
{
  "mcpServers": {
    "user-service": {
      "command": "node",
      "args": ["D:/work/my-mcp-server/dist/index.js"]
    }
  }
}

接入后，Claude Code 会自动：

1. 读取 ListTools 发现能力
2. 在需要时调用对应 Tool
3. 把 Tool 结果作为上下文继续推理

Step 4：安全加固

黄金规则：

• 默认只读，写操作显式授权
• 每个 Tool 的 description 必须清晰说明副作用
• 不在 Tool 结果中返回内部系统路径或密钥

使用示例

示例 1：把 OpenSpec 后端接口封装为 MCP Tools

// 假设已有 OpenSpec 规范 /openapi.yaml
// 自动生成 MCP Tool 定义

import yaml from "js-yaml";
import fs from "fs";

const spec = yaml.load(fs.readFileSync("./openapi.yaml", "utf8"));

const tools = Object.entries(spec.paths).flatMap(([path, methods]) =>
  Object.entries(methods).map(([method, op]) => ({
    name: `${method}_${path.replace(/\//g, "_")}`,
    description: op.summary,
    inputSchema: op.requestBody?.content?.["application/json"]?.schema || { type: "object" }
  }))
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));

最佳组合：

• openspec-sdd 设计并输出 OpenSpec
• mcp-builder 把 OpenSpec 自动转换为 MCP Tools
• api-doc-generator 生成配套 API 文档

示例 2：把 Lark OpenAPI 封装为 MCP Resources

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: "lark://docs/meeting-notes",
        name: "会议纪要汇总",
        mimeType: "application/json",
        description: "从飞书文档拉取最近会议纪要"
      }
    ]
  };
});

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  if (request.params.uri === "lark://docs/meeting-notes") {
    const notes = await fetchLarkDocs();
    return { contents: [{ uri: request.params.uri, mimeType: "application/json", text: JSON.stringify(notes) }] };
  }
});

最佳组合：

• lark-doc / lark-wiki 读取飞书内容
• mcp-builder 把 Lark 能力暴露为 MCP Resource
• memory-hub 把读取到的内容沉淀为项目记忆

示例 3：Prompt 模板 —— 代码审查

server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: [
      {
        name: "pr_code_review",
        description: "根据 PR diff 生成结构化代码审查意见",
        arguments: [
          { name: "diff", description: "PR diff 文本", required: true }
        ]
      }
    ]
  };
});

server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  if (request.params.name === "pr_code_review") {
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `请对以下 PR diff 进行代码审查，关注：安全性、性能、可维护性、边界处理。\n\n${request.params.arguments.diff}`
          }
        }
      ]
    };
  }
});

调试技巧

# 1. 直接运行 Server 看输出
node dist/index.js

# 2. 用官方 inspector 可视化调试
npx @anthropic-ai/mcp-inspector node dist/index.js

# 3. 在 Claude Code 中查看已加载 Tools
# 输入："你有哪些工具可用？"

# 4. 手动触发一个 Tool 调用
# 输入："调用 query_user，userId 为 123"

快速入口

"封装个 MCP"          → 从 0 创建一个 stdio MCP Server
"把 API 转成 MCP"     → OpenSpec / Java API → MCP Tools
"MCP 安全怎么做"      → 权限边界 + 只读默认 + 写确认
"接入 Claude Code"    → settings.json 配置 + 自动发现 Tool
"Lark 接口 MCP 化"    → Lark OpenAPI → MCP Resources

与其他 Skill 的关系

最佳实践链：

openspec-sdd（设计接口契约）
  → api-doc-generator（生成文档）
  → mcp-builder（封装为 MCP Server）
  → security-audit（审计 Tool 权限）
  → memory-hub（沉淀上下文）

"MCP 不是又一个集成框架，而是让 AI 真正理解你系统能力的通用语言。"