MCP 构建器 (mcp-builder)

MCP 构建器（mcp-builder）

概述

mcp-builder 是用于创建 MCP（Model Context Protocol）服务器的技能。它的核心是：构建高质量的 MCP 服务器，让 AI 能够通过设计良好的工具与外部服务交互。

作为开发者，你可能遇到过：

• “想创建一个 MCP 服务器但不知道怎么做”
• “想让 AI 能调用外部 API”
• “需要集成第三方服务”

mcp-builder 就是解决这些的。

什么是 MCP

MCP = Model Context Protocol

一种协议，让 AI 模型能够：
- 调用外部工具
- 访问外部资源
- 与外部服务交互

为什么需要 MCP 服务器

1. 扩展 AI 能力

AI 本身能力有限：

- 无法访问文件系统
- 无法调用 API
- 无法执行代码

MCP 服务器让 AI 能够：
- 读写文件
- 调用外部 API
- 执行命令

2. 标准化集成

之前：每个服务都要单独适配

之后：统一协议
- 一次开发
- 多处使用
- 标准化接口

创建流程

第一阶段：深度调研与规划

1.1 理解现代 MCP 设计

API 覆盖 vs 工作流工具：

策略	优点	缺点
API 全面覆盖	灵活，可组合	工具多，选择难
工作流工具	方便，简单	功能受限

建议：不确定时，优先全面 API 覆盖

工具命名：

清晰、一致的命名：
✅ 正确：
github_create_issue
github_list_repos
github_get_pr

❌ 错误：
create_issue
list_repos
get_pull_request

上下文管理：

设计原则：
- 返回专注、相关的数据
- 支持分页
- 支持过滤

错误消息：

好的错误消息：
❌ 错误： "出错了"
✅ 正确： "API 调用失败，可能原因：1. Token 过期，请刷新；2. 权限不足，请检查权限设置"

1.2 研究 MCP 协议文档

关键文档：

- 规范概述和架构
- 传输机制（streamable HTTP, stdio）
- 工具、资源和提示定义

1.3 选择技术栈

推荐：

语言：TypeScript
- SDK 支持好
- AI 模型擅长生成
- 静态类型 + linting

传输：
- 远程服务器：Streamable HTTP
- 本地服务器：stdio

第二阶段：设计与构建

2.1 定义工具

// 工具定义示例
{
  name: 'github_create_issue',
  description: '在 GitHub 仓库创建新 Issue',
  inputSchema: {
    type: 'object',
    properties: {
      owner: { type: 'string', description: '仓库所有者' },
      repo: { type: 'string', description: '仓库名称' },
      title: { type: 'string', description: 'Issue 标题' },
      body: { type: 'string', description: 'Issue 内容' }
    },
    required: ['owner', 'repo', 'title']
  }
}

2.2 实现工具

import { MCPServer } from '@modelcontextprotocol/sdk';

const server = new MCPServer({
  name: 'github-server',
  version: '1.0.0'
});

server.tool('github_create_issue', {
  owner: 'string',
  repo: 'string',
  title: 'string',
  body: 'string?'
}, async ({ owner, repo, title, body }) => {
  const response = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/issues`,
    {
      method: 'POST',
      headers: {
        'Authorization': `token ${process.env.GITHUB_TOKEN}`,
        'Accept': 'application/vnd.github.v3+json'
      },
      body: JSON.stringify({ title, body })
    }
  );

  return { result: await response.json() };
});

第三阶段：测试

3.1 本地测试

# 启动本地 MCP 服务器
npx mcp-server

# 测试工具调用

3.2 集成测试

// 测试工具链
async function test_workflow() {
  // 1. 创建 Issue
  const issue = await callTool('github_create_issue', {...});

  // 2. 添加评论
  const comment = await callTool('github_add_comment', {...});

  // 3. 验证结果
  assert(issue.number === comment.issue_number);
}

第四阶段：优化

4.1 性能优化

优化点：
- 减少不必要的数据传输
- 批量操作支持
- 缓存常用数据

4.2 错误处理

最佳实践：
- 具体的错误消息
- 重试机制
- 超时处理

工具设计模式

1. CRUD 模式

每个资源的标准操作：
- create：创建
- read：读取
- update：更新
- delete：删除
- list：列表

2. 搜索模式

搜索工具：
- 支持关键词
- 支持过滤
- 支持分页

3. 工作流模式

复杂操作封装：
- 创建 → 审批 → 发布
- 提取 → 转换 → 导入

最佳实践

1. 工具命名

原则：
- 使用前缀区分服务
- 动词 + 名词
- 清晰描述功能

示例：
github_create_issue
github_list_repos
slack_send_message
notion_create_page

2. 描述编写

好的描述：
❌ 错误： "创建 Issue"

✅ 正确： "在 GitHub 仓库创建新 Issue。需要的参数：owner（仓库所有者）、repo（仓库名）、title（标题）、body（可选，内容）"

3. 参数设计

设计原则：
- 必填参数明确
- 可选参数有默认值
- 参数有描述
- 类型安全

检查清单

设计阶段

• 明确服务目标
• 规划工具列表
• 设计工具接口
• 确定错误处理策略

开发阶段

• 遵循命名规范
• 编写清晰描述
• 实现错误处理
• 添加日志

测试阶段

• 单元测试
• 集成测试
• 端到端测试
• 性能测试

部署阶段

• 容器化
• 监控
• 文档
• 版本管理

速查卡片

核心概念

• MCP 协议
• 工具定义
• 传输机制

推荐技术栈

• TypeScript
• Streamable HTTP
• MCP SDK

工具命名

prefix_action_target github_create_issue

测试

• 单元测试
• 集成测试
• 端到端测试

---

查看源文件: GitHub原始文件