MCP 集成

Cell 内的 MCP（Model Context Protocol）Server 注册与连接管理，以及三层浏览器/桌面自动化。

MCP 概念

MCP 是 wesgine 扩展 Cell 能力的核心机制。每个 Cell 可以注册多个 MCP Server，其暴露的工具自动出现在 Cell 的 ToolRegistry 中，模型可直接调用。

Cell A 的 MCP 工具对 Cell B 的 Agent 物理不可见（AX-1 隔离）。

MCP API

Server 管理

方法	路径	说明
`GET`	`/mcp`	MCP Server 列表
`POST`	`/mcp`	注册/更新 MCP Server
`DELETE`	`/mcp/{name}`	删除 MCP Server

连接控制

方法	路径	说明
`POST`	`/mcp/{name}/probe`	探测连通性
`POST`	`/mcp/{name}/connect`	建立连接
`POST`	`/mcp/{name}/disconnect`	断开连接

工具调用

方法	路径	说明
`POST`	`/mcp/{name}/call`	调用工具
`GET`	`/mcp/events`	SSE 事件流

SDK 调用

// 注册
err := cell.MCPs().Upsert(ctx, mcp.ServerConfig{
    Name:      "legal-mcp",
    Transport: "stdio",
    Command:   []string{"/opt/mcp/legal/bin/server"},
})

// 列出
servers, err := cell.MCPs().List(ctx)

// 探测
result, err := cell.MCPs().Probe(ctx, "legal-mcp")

// 连接
err := cell.MCPs().Connect(ctx, "legal-mcp")

// 断开
err := cell.MCPs().Disconnect(ctx, "legal-mcp")

// 调用
result, err := cell.MCPs().Call(ctx, "legal-mcp", mcp.CallRequest{
    Tool:   "search_cases",
    Params: map[string]any{"query": "合同纠纷"},
})

MCP 工具集成

MCP Server 注册后，其暴露的工具自动出现在 Cell ToolRegistry：

Cell ToolRegistry
├── 引擎内置工具 (read, write, exec, grep, ...)
├── SDK 注册工具 (cell.Tools().Register)
├── MCP 代理工具 (cell.MCPs().Upsert)  ← MCP 工具在这里
├── Adapter 派生工具 (kb/email/cron/...)
└── Per-run 临时工具 (RunParams.Tools)

模型看到的是统一的工具列表，无需感知工具来自 MCP 还是内置。

配额（INV-QUOTA-05）

MaxMCPServers 遵循外设配额统一规则：

规则	说明
唯一增长点	MCP Upsert 是唯一能让集合变大的地方
整体替换幂等	`UpdateSpec` 的 MCPs 替换对 cap 幂等
覆盖已有名字 delta=0	upsert 是编辑手势
注意无运行时存储	MCPs 的集合就是 CellSpec，运行期越界持久化后下次重启才拒绝

三层浏览器/桌面自动化

wesgine 提供三层自动化 adapter，按使用场景选择：

HeadlessBrowser（服务端匿名抓取）

spec := wesgine.CellSpec{
    HeadlessBrowser: &wesgine.HeadlessBrowserConfig{
        // 使用 chromedp
    },
}

特性	说明
运行时位置	服务端
技术	chromedp
用途	匿名网页抓取
用户登录态	❌ 无
CellSpec 字段	`.HeadlessBrowser`（非 nil 即启用）

API：

方法	路径	说明
`GET`	`/headless-browser/state`	状态查询

Playwright（用户浏览器自动化）

spec := wesgine.CellSpec{
    Playwright: &wesgine.PlaywrightConfig{
        // mode: user + extension
    },
}

特性	说明
运行时位置	服务端 subprocess + 用户浏览器
技术	Playwright MCP
用途	用户浏览器自动化（登录态可用）
CellSpec 字段	`.Playwright`

API：

方法	路径	说明
`GET`	`/playwright/status`	连接状态
`PUT`	`/playwright/token`	更新扩展 auto-connect token

Desktop（桌面自动化 Device Agent）

spec := wesgine.CellSpec{
    Desktop: &wesgine.DesktopConfig{
        Command:   "/opt/device-agent/bin/agent",
        Transport: "stdio",
    },
}

特性	说明
运行时位置	客户端 binary（AX-5）
技术	MCP over stdio
用途	OS 级桌面自动化（截屏/剪贴板/应用控制）
CellSpec 字段	`.Desktop`

API：

方法	路径	说明
`GET`	`/desktop/status`	Agent 连接状态

选择指南

新能力 X →
├── 服务端匿名爬取？        → CellSpec.HeadlessBrowser
├── 用户浏览器（登录态）？   → CellSpec.Playwright
├── 桌面/剪贴板/截屏？      → CellSpec.Desktop + 客户端二进制
├── 其他客户端硬件？        → AX-5：消费应用自建 Device Agent + cell.MCPs()
└── 新外设协议？            → adapter/ + Cell 声明式装配

MCP Server 配置示例

stdio 方式

cell.MCPs().Upsert(ctx, mcp.ServerConfig{
    Name:      "legal-research",
    Transport: "stdio",
    Command:   []string{"/opt/mcp/legal/bin/server"},
    Env:       map[string]string{"DB_HOST": "localhost"},
})

SSE 方式

cell.MCPs().Upsert(ctx, mcp.ServerConfig{
    Name:      "crm-integration",
    Transport: "sse",
    URL:       "http://crm-mcp.internal:8080/sse",
})

最佳实践

使用 probe 验证连通性：注册后调用 /mcp/{name}/probe
MCP Server 独立部署：作为独立进程或容器运行
按场景选择自动化层：匿名抓取用 Headless，登录态用 Playwright，桌面用 Desktop
注意配额：MCP Server 无运行时存储，越界写入下次重启才暴露