MCP 集成

AggRoot 支持通过 MCP（Model Context Protocol） 连接外部工具服务器，扩展自身能力。本章介绍 MCP 的概念、配置和使用方法。

什么是 MCP

MCP（Model Context Protocol）是由 Anthropic 提出的开放协议，允许 AI 助手与外部工具服务器进行标准化通信。通过 MCP，AggRoot 可以：

连接任意的 MCP 兼容工具服务器
自动发现服务器提供的工具
在对话中直接调用这些工具

简单来说，MCP 让 AggRoot 的能力可以无限扩展——只要有一个 MCP 服务器，就能获得新的工具。

传输类型

MCP 支持 4 种传输方式：

传输类型	说明	适用场景
`stdio`	标准输入输出	本地命令行工具，最常用
`http`	HTTP 请求	远程 HTTP API 服务
`websocket`	WebSocket 双向通信	需要实时交互的服务
`sse`	Server-Sent Events	服务器推送场景

配置

MCP 服务器配置通过 JSON 文件管理，支持项目级和全局级两层配置。

配置文件位置

层级	路径	作用
项目级	`.aggroot/mcp.json`	仅对当前项目生效
全局级	`~/.aggroot/mcp.json`	对所有项目生效

两个配置文件会自动合并，项目级配置优先。

配置示例

{
  "servers": [
    {
      "name": "powerpoint-server",
      "transport": {
        "type": "stdio",
        "command": "uvx",
        "args": ["pptx-mcp-server"]
      },
      "enabled": true,
      "timeout": 30000
    },
    {
      "name": "word-document-server",
      "transport": {
        "type": "stdio",
        "command": "uvx",
        "args": ["docx-mcp-server"]
      },
      "enabled": true,
      "timeout": 30000
    },
    {
      "name": "remote-api",
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp",
        "headers": {
          "Authorization": "Bearer your-token"
        },
        "timeout": 15000
      },
      "enabled": true
    },
    {
      "name": "websocket-service",
      "transport": {
        "type": "websocket",
        "url": "ws://localhost:9090/mcp"
      },
      "enabled": true
    }
  ],
  "settings": {
    "defaultTimeout": 30000,
    "maxConcurrent": 5,
    "autoReconnect": true,
    "healthCheckIntervalMs": 30000,
    "maxReconnectAttempts": 5
  }
}

环境变量配置

也可以通过环境变量配置 MCP 服务器：

MCP_SERVERS='[{"name":"my-server","transport":{"type":"stdio","command":"node","args":["server.js"]}}]'

工具命名规则

MCP 服务器提供的工具会自动注册到 AggRoot，命名规则为：

mcp_{server-name}_{tool-name}

例如：

powerpoint-server 提供的 create_slide 工具 → mcp_powerpoint-server_create_slide
word-document-server 提供的 read_document 工具 → mcp_word-document-server_read_document

预配置服务器

以下 MCP 服务器可以开箱即用：

服务器	安装命令	提供的工具
pptx-mcp-server	`uvx pptx-mcp-server`	PowerPoint 文件操作
docx-mcp-server	`uvx docx-mcp-server`	Word 文档操作
filesystem-mcp	`uvx filesystem-mcp`	文件系统操作
github-mcp	`uvx github-mcp`	GitHub API 集成
sqlite-mcp	`uvx sqlite-mcp`	SQLite 数据库操作

安装 MCP 服务器

使用 uvx（推荐）

uvx 是安装 MCP 服务器的推荐方式，无需手动克隆仓库：

# 安装 uv（Python 包管理器）
pip install uv

# 使用 uvx 运行 MCP 服务器
uvx pptx-mcp-server

使用 pip

pip install pptx-mcp-server

然后在 mcp.json 中配置：

{
  "name": "powerpoint-server",
  "transport": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "pptx_mcp_server"]
  }
}

自动发现

当 MCP 服务器连接成功后，AggRoot 会自动：

查询服务器提供的所有工具
将工具注册到工具注册表
在对话中自动可用

你无需手动注册工具——连接即用。

自动重连

AggRoot 内置了自动重连机制，当 MCP 服务器断开连接时会自动尝试重连：

重连策略

参数	默认值	说明
`autoReconnect`	`true`	是否自动重连
`maxReconnectAttempts`	`5`	最大重连尝试次数
`backoff`	`exponential`	退避策略：exponential / fixed / linear
`maxDelayMs`	`30000`	最大重连间隔（毫秒）
`jitter`	`false`	是否添加随机抖动

退避策略

exponential（默认） — 间隔时间指数增长：1s → 2s → 4s → 8s → 16s
fixed — 固定间隔：1s → 1s → 1s → 1s → 1s
linear — 线性增长：1s → 2s → 3s → 4s → 5s

重连事件

AggRoot 会在以下事件时触发重连：

server_disconnected — 服务器断开连接
server_health_check_failed — 健康检查连续失败

工具过滤

可以通过配置控制暴露哪些 MCP 工具：

{
  "name": "my-server",
  "transport": { "type": "stdio", "command": "node", "args": ["server.js"] },
  "allowedTools": ["read_file", "search"],     // 只暴露这两个工具
  "excludedTools": ["delete_file"]            // 排除这个工具
}

allowedTools — 白名单，只暴露列出的工具
excludedTools — 黑名单，排除列出的工具

两者可以同时使用，excludedTools 优先级更高。

健康检查

为 MCP 服务器配置定期健康检查：

{
  "name": "my-server",
  "transport": { "type": "http", "url": "http://localhost:8080/mcp" },
  "healthCheck": {
    "intervalMs": 30000,
    "timeoutMs": 5000
  }
}

健康检查通过 ping() 方法实现。连续失败时会触发重连。

常见问题

服务器连接失败

检查 mcp.json 中的 command 和 args 是否正确
确认 MCP 服务器已安装（uvx 或 pip）
检查网络连接（对于 HTTP/WebSocket 传输）

工具未出现

使用 ListSkills 或询问 AggRoot 查看可用工具
确认服务器 enabled 字段为 true
检查 allowedTools / excludedTools 过滤配置

性能问题

减少同时连接的 MCP 服务器数量（maxConcurrent）
增加超时时间（timeout / defaultTimeout）
禁用不常用的服务器（enabled: false）

← 上一篇

最佳实践

技能系统