MCP 生态与能力扩展

了解 MCP 协议，掌握 WorkBuddy 的能力扩展机制。

学习目标

• 理解 MCP 协议原理
• 掌握服务器配置方法
• 学会自定义开发
• 了解工具集成

核心内容

1. MCP 协议详解

MCP（Model Context Protocol）是一个开放协议，让 AI 模型能够与外部工具和服务进行标准化交互。在 WorkBuddy 中，MCP 扮演着关键角色：

能力	说明
工具调用	调用外部 API 和服务
数据获取	从各种数据源读取数据
能力扩展	无限扩展 AI 能力边界
生态共享	社区贡献的 MCP 服务器

MCP 协议通过标准化的接口定义，使得 AI 能够安全、可靠地访问外部资源，同时保持系统的可扩展性和互操作性。

2. 服务器配置

MCP 服务器配置采用 JSON 格式，支持多环境配置：

配置文件结构：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-weather"],
      "env": {
        "API_KEY": "${WEATHER_API_KEY}"
      }
    },
    "database": {
      "command": "node",
      "args": ["./mcp-servers/database-server.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306"
      }
    }
  }
}

配置位置：

• 全局配置：~/.workbuddy/mcp.json
• 项目配置：.workbuddy/mcp.json
• 用户配置：通过界面配置

配置优先级：用户配置 > 项目配置 > 全局配置

3. 自定义开发

开发自定义 MCP 服务器需要使用官方 SDK，以下是一个完整的开发模板：

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

const server = new Server(
  { name: "my-custom-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 注册工具
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "my_tool",
      description: "My custom tool",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "Input query" }
        },
        required: ["query"]
      }
    }
  ]
}));

// 处理调用
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "my_tool") {
    const result = await processQuery(request.params.arguments.query);
    return { content: [{ type: "text", text: result }] };
  }
});

// 启动服务器
const transport = new StdioServerTransport();
await server.connect(transport);

开发流程：

1. 定义工具接口和输入模式
2. 实现工具调用处理逻辑
3. 注册工具和处理器
4. 启动服务器并测试

4. 工具集成

WorkBuddy 支持多种常用 MCP 服务器，开箱即用：

文件系统服务器：

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

数据库服务器：

{
  "mysql": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-mysql"],
    "env": {
      "MYSQL_HOST": "localhost",
      "MYSQL_PORT": "3306",
      "MYSQL_USER": "root",
      "MYSQL_PASSWORD": "${DB_PASSWORD}",
      "MYSQL_DATABASE": "mydb"
    }
  }
}

Web 搜索服务器：

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
    }
  }
}

集成步骤：

1. 选择合适的 MCP 服务器
2. 配置环境变量和参数
3. 在 WorkBuddy 中启用服务器
4. 测试工具调用功能

实操练习

练习 1：配置 MCP 服务器

目标：配置一个天气查询 MCP 服务器，并测试其功能

步骤：

1. 创建配置文件： 在项目根目录创建 .workbuddy/mcp.json：

   {
     "mcpServers": {
       "weather": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-weather"],
         "env": {
           "API_KEY": "your_weather_api_key"
         }
       }
     }
   }
   

2. 获取 API 密钥：

   • 注册 OpenWeatherMap 或类似天气服务
   • 获取 API 密钥并替换配置中的占位符

3. 测试服务器：

   • 在 WorkBuddy 中询问天气相关问题
   • 观察 MCP 服务器是否被正确调用
   • 验证返回结果的准确性

4. 调试和优化：

   • 检查日志输出，确认服务器启动正常
   • 测试不同地区的天气查询
   • 优化错误处理和响应格式

总结

关键要点...

下一步

• 完成练习
• 查看相关文档
• 尝试实际应用

---