AgentHarness 课程

MCP 集成与扩展

6.3K字·16分钟·
MCP协议、工具集成、能力扩展

引言

MCP（Model Context Protocol，模型上下文协议）是连接 AI 模型与外部工具/服务的标准协议。通过 MCP，CodeBuddy 可以访问数据库、调用 API、操作云服务等，极大地扩展了智能体的能力边界。

如果说 CodeBuddy 的内置工具是"手"，那么 MCP 就是给它装上了"万能接口"——让它能够连接任何外部系统。

一、MCP 协议解释

1.1 什么是 MCP

MCP 是由 Anthropic 提出的开放协议，定义了 AI 模型与外部工具/服务之间的通信标准。它类似于 USB 协议之于电脑——一个统一的接口标准，让不同的设备（工具）可以即插即用。

1.2 为什么需要 MCP

没有 MCP 的问题：

  • 每个 AI 工具都需要自己实现外部集成
  • 工具之间不兼容，重复开发
  • 缺乏统一的安全和权限标准

MCP 解决的问题：

  • 统一的工具接入标准
  • 即插即用的工具生态
  • 标准化的安全和权限控制

1.3 MCP 架构

CodeBuddy (MCP Client)
      ↓
MCP 协议层
      ↓
┌─────────────────────────────────────┐
│  MCP Server A    MCP Server B    ... │
│  (数据库)        (API 服务)          │
└─────────────────────────────────────┘

二、MCP vs Skills vs Rules 对比

2.1 三方对比表

特性MCPSkillsRules
主要用途连接外部工具/服务封装多步骤工作流定义行为规范
通信方式标准协议（stdio/SSE）内部配置文本文件
能力范围无限扩展（任何服务）有限（预定义动作）有限（行为约束）
配置复杂度中等（需要 Server）低（YAML 配置）最低（Markdown）
运行环境独立进程内嵌执行上下文注入
典型场景数据库查询、API 调用代码审查、部署流程编码规范、命名约定

2.2 协同工作示例

# MCP 提供能力：连接数据库
# Skills 定义流程：查询 -> 分析 -> 报告
# Rules 约束行为：查询必须有 LIMIT，禁止 DELETE

# 最终效果：
# CodeBuddy 使用 MCP 连接数据库，
# 按照 Skills 定义的流程执行，
# 遵循 Rules 的约束条件

三、内置 MCP 工具列表

3.1 文件系统 MCP

{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
}

提供的工具：

  • read_file - 读取文件
  • write_file - 写入文件
  • list_directory - 列出目录
  • search_files - 搜索文件
  • move_file - 移动/重命名文件

3.2 Git MCP

{
  "name": "git",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "/path/to/repo"]
}

提供的工具：

  • git_status - 查看状态
  • git_diff - 查看差异
  • git_commit - 提交更改
  • git_log - 查看历史

3.3 数据库 MCP

{
  "name": "postgres",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
}

提供的工具：

  • query - 执行 SQL 查询
  • list_tables - 列出表
  • describe_table - 查看表结构

四、配置自定义 MCP

4.1 MCP 配置方式

官方推荐方式：通过 IDE 设置页配置

  1. 在侧栏对话面板右上方，点击 CodeBuddy Settings 按钮
  2. 切换到 MCP 标签页
  3. 支持两种配置方式：
    • 一键安装：在 MCP Market 中选择 MCP Server 一键安装
    • 自定义配置：点击 Add MCP 按钮，添加 JSON 配置

MCP Market 一键安装：

  • 在 MCP Market 中提供大量 MCP Server
  • 选择后一键安装，安装成功显示绿色状态
  • 安装失败显示红色状态

自定义配置 JSON 格式：

配置文件位置（备选）：

  • 也可以直接编辑 文件
  • 但推荐使用 IDE 设置页配置，更直观
// .codebuddy/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"]
    },
    "custom-api": {
      "command": "node",
      "args": ["./mcp-servers/api-server.js"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_BASE": "https://api.example.com"
      }
    }
  }
}

4.2 自定义 MCP Server 开发

// mcp-servers/api-server.js
const { Server } = require('@modelcontextprotocol/sdk/server');

const server = new Server({
  name: 'custom-api',
  version: '1.0.0',
});

// 注册工具
server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: 'fetch_data',
      description: '从 API 获取数据',
      inputSchema: {
        type: 'object',
        properties: {
          endpoint: { type: 'string', description: 'API 端点' },
          method: { type: 'string', enum: ['GET', 'POST'] },
          body: { type: 'object', description: '请求体' }
        },
        required: ['endpoint']
      }
    }
  ]
}));

// 处理工具调用
server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === 'fetch_data') {
    const response = await fetch(`${process.env.API_BASE}${args.endpoint}`, {
      method: args.method || 'GET',
      headers: { 'Authorization': `Bearer ${process.env.API_KEY}` },
      body: args.body ? JSON.stringify(args.body) : undefined
    });
    const data = await response.json();
    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
  }
});

server.start();

五、数据库查询实战

场景：使用 MCP 查询 PostgreSQL 数据库

# 配置好 PostgreSQL MCP 后，直接对话：

用户：查询最近 7 天注册的用户数量

CodeBuddy：（通过 MCP 调用 query 工具）
SELECT DATE(created_at) as date, COUNT(*) as count
FROM users
WHERE created_at >= NOW() - INTERVAL '7 days'
GROUP BY DATE(created_at)
ORDER BY date;

# 执行结果：
# | date       | count |
# |------------|-------|
# | 2024-01-15 | 42    |
# | 2024-01-16 | 38    |
# | 2024-01-17 | 55    |

# 更复杂的查询：

用户：找出购买金额 Top 10 的用户及其订单详情

CodeBuddy：
SELECT u.username, u.email, 
       SUM(o.amount) as total_spent,
       COUNT(o.id) as order_count
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.status = 'completed'
GROUP BY u.id
ORDER BY total_spent DESC
LIMIT 10;

六、安全注意事项

6.1 权限控制

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://readonly_user:pass@localhost/db"
      },
      "permissions": {
        "query": { "allowed": true },
        "execute": { "allowed": false },
        "list_tables": { "allowed": true }
      }
    }
  }
}

6.2 安全最佳实践

  1. 最小权限原则：只给 MCP Server 必要的权限
  2. 使用只读账户：数据库连接使用只读用户
  3. 环境变量存储密钥：不要在配置文件中硬编码密钥
  4. 网络隔离：MCP Server 只能访问必要的网络资源
  5. 日志审计：记录所有 MCP 工具调用日志

6.3 常见安全风险

风险说明防护措施
SQL 注入通过查询参数注入恶意 SQL使用参数化查询
权限提升MCP Server 获取过高权限最小权限原则
数据泄露敏感数据被暴露数据脱敏、访问控制
服务滥用MCP Server 被恶意调用速率限制、认证

七、常见陷阱与最佳实践

常见错误

  1. MCP Server 未启动：配置了 MCP 但 Server 未运行
  2. 连接超时：MCP Server 响应过慢
  3. 权限不足：MCP Server 没有足够的权限执行操作
  4. 版本不兼容：MCP SDK 版本与 Server 不匹配

最佳实践

  1. 健康检查：启动时检查 MCP Server 是否可用
  2. 超时设置：为 MCP 调用设置合理的超时时间
  3. 错误处理：MCP 调用失败时有降级方案
  4. 版本锁定：锁定 MCP SDK 和 Server 的版本
  5. 文档完善：为自定义 MCP Server 编写详细文档

总结

MCP 集成与扩展让 CodeBuddy 的能力无限延伸：

  1. 统一协议：标准化的工具接入方式
  2. 丰富生态：文件系统、数据库、API 等内置 MCP
  3. 自定义扩展：可以开发任意功能的 MCP Server
  4. 安全可控：权限控制、环境变量、日志审计
  5. 协同工作：与 Skills、Rules 配合形成完整解决方案

下一章我们将探索检查点与版本管理，了解如何安全地进行 AI 辅助开发。