ByteBuddy

简体中文

English

简体中文

English

深色模式

MCP 工具 ​

MCP (Model Context Protocol) 是 ByteBuddy 的扩展机制，允许连接外部 MCP 服务器来获取额外的工具、资源和提示功能。

MCP 工作原理 ​

在 ByteBuddy 中，MCP 通过以下方式工作：

  1. 连接外部服务器：通过 stdio、HTTP 或 WebSocket 连接 MCP 服务器
  2. 获取可用功能：自动发现服务器提供的工具、资源和提示
  3. AI 助手调用：在对话中，AI 助手可以调用这些 MCP 功能
  4. 权限控制：每个连接独立配置，确保安全使用

配置文件位置 ​

MCP 服务器配置位于你的 ByteBuddy 配置文件中：

yaml
# config.yaml
name: My ByteBuddy Config
version: 0.0.1
schema: v1

mcpServers:
  # MCP 服务器配置在这里

连接类型 ​

ByteBuddy 支持多种 MCP 服务器连接方式：

1. STDIO 连接（推荐用于本地工具） ​

yaml
mcpServers:
  - name: browser-automation
    command: npx
    args:
      - "@playwright/mcp@latest"
    env:
      NODE_ENV: production

2. HTTP/SSE 连接 ​

yaml
mcpServers:
  - name: remote-api-server
    url: https://api.example.com/mcp
    type: sse
    apiKey: ${API_KEY}
    requestOptions:
      timeout: 30000
      headers:
        User-Agent: ByteBuddy/1.0

3. WebSocket 连接 ​

yaml
mcpServers:
  - name: realtime-service
    url: wss://service.example.com/ws
    type: websocket
    apiKey: ${WEBSOCKET_KEY}

常用 MCP 服务器示例 ​

1. 浏览器自动化工具 ​

yaml
mcpServers:
  - name: browser-search
    command: npx
    args:
      - "@playwright/mcp@latest"

2. 文件系统增强 ​

yaml
mcpServers:
  - name: filesystem-tools
    command: node
    args:
      - "./mcp-servers/filesystem-server.js"
    cwd: ${PROJECT_ROOT}

3. 数据库连接 ​

yaml
mcpServers:
  - name: database-tools
    command: python
    args:
      - "-m"
      - "mcp_database_server"
    env:
      DB_URL: postgresql://user:pass@localhost/mydb

如何在对话中使用 ​

配置完成后，MCP 服务器的功能会自动在对话中可用：

示例对话 1：使用浏览器工具 ​

用户：

帮我打开百度首页，截图保存

AI 助手（自动调用 MCP 工具）：

  1. 启动浏览器并访问百度首页
  2. 截取页面截图
  3. 保存到指定位置

示例对话 2：使用数据库工具 ​

用户：

查询用户表中有多少活跃用户

AI 助手（自动调用 MCP 数据库工具）：

  1. 连接到数据库
  2. 执行查询：SELECT COUNT(*) FROM users WHERE status = 'active'
  3. 返回结果：当前有 523 个活跃用户

安全配置 ​

1. 环境变量管理 ​

yaml
mcpServers:
  - name: secure-api
    url: https://api.example.com/mcp
    type: sse
    apiKey: ${API_SECRET_KEY} # 从环境变量读取
    env:
      DEBUG: false

2. 连接超时配置 ​

yaml
mcpServers:
  - name: timeout-example
    url: https://slow-api.example.com/mcp
    type: sse
    connectionTimeout: 60000 # 60秒连接超时
    requestOptions:
      timeout: 120000 # 120秒请求超时

3. 工作目录限制 ​

yaml
mcpServers:
  - name: local-file-tools
    command: node
    args:
      - "./tools/file-server.js"
    cwd: /safe/workspace # 限制工作目录
    env:
      ALLOWED_PATHS: /safe/workspace

自定义 MCP 服务器 ​

1. 创建 Node.js MCP 服务器 ​

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

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

// 定义工具
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_weather",
      description: "获取指定城市的天气信息",
      inputSchema: {
        type: "object",
        properties: {
          city: { type: "string" },
        },
        required: ["city"],
      },
    },
  ],
}));

// 处理工具调用
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "get_weather") {
    const { city } = request.params.arguments;
    // 调用天气 API
    const weather = await getWeatherData(city);
    return {
      content: [
        {
          type: "text",
          text: `${city}今天天气：${weather.description}，气温 ${weather.temp}°C`,
        },
      ],
    };
  }
});

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

2. 注册自定义服务器 ​

yaml
mcpServers:
  - name: weather-service
    command: node
    args:
      - "./custom-mcp-server.js"
    env:
      WEATHER_API_KEY: ${WEATHER_API_KEY}

配置选项详解 ​

完整配置示例 ​

yaml
mcpServers:
  - name: comprehensive-example
    serverName: "我的自定义服务器"
    faviconUrl: "https://example.com/icon.png"
    command: node
    args:
      - "./server.js"
      - "--production"
    env:
      NODE_ENV: production
      API_KEY: ${API_KEY}
      LOG_LEVEL: info
    cwd: /app
    connectionTimeout: 30000

配置字段说明 ​

  • name: 服务器唯一标识符（必需）
  • serverName: 显示名称（可选）
  • faviconUrl: 服务器图标 URL（可选）
  • command: 启动命令（stdio 连接必需）
  • args: 命令参数（可选）
  • url: 服务 URL（HTTP/WebSocket 连接必需）
  • type: 连接类型（"stdio"、"sse"、"streamable-http"、"websocket"）
  • env: 环境变量（可选）
  • cwd: 工作目录（可选）
  • connectionTimeout: 连接超时时间，毫秒（可选）
  • apiKey: API 密钥（可选）
  • requestOptions: HTTP 请求选项（可选）

故障排除 ​

1. 连接失败 ​

问题：MCP 服务器无法连接

解决方案：

yaml
# 检查命令和参数
mcpServers:
  - name: debug-server
    command: node # 确保命令正确
    args:
      - "./server.js"
      - "--verbose" # 添加调试参数
    env:
      DEBUG: mcp:* # 启用调试日志

2. 权限问题 ​

问题：工具调用被拒绝

解决方案：

  • 检查 MCP 服务器的权限配置
  • 确认 API 密钥有效
  • 验证工作目录访问权限

3. 性能优化 ​

yaml
mcpServers:
  - name: optimized-server
    connectionTimeout: 10000 # 减少超时时间
    requestOptions:
      timeout: 30000
      headers:
        Connection: keep-alive # 保持连接活跃

最佳实践 ​

  1. 选择合适的连接方式：

    • 本地工具使用 stdio 连接
    • 远程服务使用 HTTP/SSE 或 WebSocket
    • 性能敏感的场景优先考虑 stdio

  2. 安全第一：

    • 使用环境变量存储敏感信息
    • 限制 MCP 服务器的工作目录
    • 定期更新 MCP 服务器和依赖

  3. 性能优化：

    • 设置合理的连接超时时间
    • 重用 HTTP 连接（keep-alive）
    • 监控服务器资源使用情况

  4. 调试和监控：

    • 启用详细日志记录
    • 测试每个 MCP 服务器的连通性
    • 监控工具调用频率和响应时间

  5. 版本管理：

    • 为 MCP 服务器指定具体版本
    • 使用锁文件确保依赖一致性
    • 定期更新到稳定版本

可用的 MCP 服务器资源 ​

以下是一些常用的 MCP 服务器：

  1. @playwright/mcp - 浏览器自动化
  2. @modelcontextprotocol/server-filesystem - 文件系统操作
  3. @modelcontextprotocol/server-git - Git 操作
  4. @modelcontextprotocol/server-github - GitHub 集成
  5. @modelcontextprotocol/server-sqlite - SQLite 数据库
  6. @modelcontextprotocol/server-postgres - PostgreSQL 数据库

更多 MCP 服务器可以在 MCP Registry 中找到。

Copyright © 2025 ByteBuddy