docs(extension): 补充阶段C MCP开发说明
This commit is contained in:
@@ -0,0 +1,262 @@
|
||||
# MCP Bridge 与 Plugin Host 开发说明
|
||||
|
||||
> 更新日期：2026-09-01。本文记录第二阶段阶段 C 已实现的本地 stdio MCP Bridge、隔离 Plugin Host、Tool Contract 转换和离线测试方式。Plugin Command 与 Settings 属于阶段 D，不在本文实现范围内。
|
||||
|
||||
## 1. 目标与实现状态
|
||||
|
||||
阶段 C 的目标是让外部 MCP Server 进入既有 Plugin、Tool、Permission、Agent 和 Trace 链路，同时避免 Agent Runtime、前端或 Benchmark 直接依赖 MCP 原始消息。
|
||||
|
||||
当前链路：
|
||||
|
||||
```text
|
||||
Plugin Manifest
|
||||
→ Plugin Runtime
|
||||
→ 独立 stdio MCP Server 进程
|
||||
→ initialize / capability negotiation
|
||||
→ tools/list 分页发现与校验
|
||||
→ NotesAgent ToolDefinition
|
||||
→ Tool Registry / Permission Manager
|
||||
→ Agent Runtime / Agent Trace
|
||||
```
|
||||
|
||||
已经实现：
|
||||
|
||||
- 本地 stdio 子进程启动、关闭和异常退出检测；
|
||||
- UTF-8、换行分隔的 JSON-RPC 2.0 消息；
|
||||
- initialize、协议版本与 tools capability 协商；
|
||||
- `notifications/initialized`；
|
||||
- 分页 `tools/list`；
|
||||
- `tools/call`、业务错误与 JSON-RPC 错误转换；
|
||||
- 超时和 `notifications/cancelled`；
|
||||
- Tool 命名空间、JSON Schema、权限和 Manifest 集合校验；
|
||||
- Host 状态查询、重启和异常后的 Tool 自动注销；
|
||||
- stderr 隔离、环境变量裁剪、消息及结果大小限制；
|
||||
- 无网络、无密钥的确定性 MCP Fixture。
|
||||
|
||||
实现依据为 MCP 官方 [Lifecycle 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)、[Transports 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) 和 [Tools 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)。
|
||||
|
||||
## 2. 代码位置
|
||||
|
||||
```text
|
||||
backend/app/extensions/mcp.py
|
||||
stdio 进程、JSON-RPC、MCP 生命周期、发现、调用和 Host 状态
|
||||
|
||||
backend/app/extensions/runtime.py
|
||||
Plugin Manifest、权限、MCP Tool 批量注册/回滚和生命周期集成
|
||||
|
||||
backend/app/agent/tools.py
|
||||
内部 Tool 参数校验、结构化执行错误和线程安全 Registry
|
||||
|
||||
backend/extensions/fixtures/mcp-echo/
|
||||
确定性 stdio MCP Server 与 Plugin Manifest
|
||||
```
|
||||
|
||||
## 3. Plugin Manifest
|
||||
|
||||
MCP Plugin 的后端配置示例：
|
||||
|
||||
```yaml
|
||||
id: example-mcp
|
||||
name: Example MCP
|
||||
version: 1.0.0
|
||||
permissions:
|
||||
- notes.read
|
||||
contributes:
|
||||
tools:
|
||||
- example-mcp.search
|
||||
backend:
|
||||
type: mcp
|
||||
transport: stdio
|
||||
command: python
|
||||
args: [server.py]
|
||||
startup_timeout_seconds: 5
|
||||
tool_timeout_seconds: 30
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- 阶段 C 只接受 `type: mcp` 与 `transport: stdio`；
|
||||
- 命令和参数通过数组直接传给 `subprocess.Popen`，不经过 Shell；
|
||||
- PATH 中的 executable 使用名称，例如 `python`、`node`；
|
||||
- manifest 中带目录的 executable 必须解析到 Plugin 包内部；
|
||||
- `contributes.tools` 使用 `<plugin_id>.<remote_name>`；
|
||||
- 安装阶段只读 Manifest，不启动第三方进程；
|
||||
- 完成用户授权后，`enable` 才启动 Host。
|
||||
|
||||
## 4. 生命周期
|
||||
|
||||
### 4.1 启动
|
||||
|
||||
启用 MCP Plugin 时依次执行：
|
||||
|
||||
1. 检查 Plugin 声明权限是否全部获得授权；
|
||||
2. 检查 Manifest 声明的 Tool ID 是否与现有 Registry 冲突；
|
||||
3. 启动独立 stdio Server；
|
||||
4. 发送 `initialize`；
|
||||
5. 校验协商版本和 `tools` capability；
|
||||
6. 发送 `notifications/initialized`；
|
||||
7. 分页读取 `tools/list`；
|
||||
8. 校验全部 Tool；
|
||||
9. 确认发现集合与 Manifest 完全一致；
|
||||
10. 将完整集合注册到 Tool Registry；
|
||||
11. Plugin 和 Host 进入 `ready`。
|
||||
|
||||
任何步骤失败都会注销本轮已注册 Tool、关闭子进程并把 Plugin 标记为 `error`，不会留下半启用状态。
|
||||
|
||||
### 4.2 停止与异常退出
|
||||
|
||||
停用、卸载或应用关闭时，先注销 Tool，再关闭 stdin，等待 Server 正常退出。超时后依次 terminate 和 kill。
|
||||
|
||||
Server 异常退出、stdout 出现非 JSON-RPC 内容或发送超大协议消息时：
|
||||
|
||||
- 未完成请求返回 `PLUGIN_HOST_UNAVAILABLE`；
|
||||
- Host 进入 `unhealthy`；
|
||||
- Plugin 进入 `error`；
|
||||
- 对应 Tool 从 Registry 中立即注销；
|
||||
- 用户可以调用 Host Restart 接口重新协商和发现。
|
||||
|
||||
Server 发送 `notifications/tools/list_changed` 时不会直接信任新集合。当前实现先把 Host 标记为不健康并注销旧 Tool，要求通过 Restart 重新执行完整发现与校验。
|
||||
|
||||
## 5. Tool Contract 转换
|
||||
|
||||
MCP Tool：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "search",
|
||||
"description": "Search notes",
|
||||
"inputSchema": { "type": "object", "properties": {} },
|
||||
"_meta": { "notesagent/permission": "notes.read" }
|
||||
}
|
||||
```
|
||||
|
||||
进入系统后转换为：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "example-mcp.search",
|
||||
"description": "Search notes",
|
||||
"parameters": { "type": "object", "properties": {} },
|
||||
"permission": "notes.read",
|
||||
"source": "plugin"
|
||||
}
|
||||
```
|
||||
|
||||
转换规则：
|
||||
|
||||
- 远端名称必须能转换为合法且稳定的项目 Tool ID；
|
||||
- `inputSchema` 必须是有效的 object JSON Schema；
|
||||
- `_meta.notesagent/permission` 必须属于项目已知权限；
|
||||
- Tool 权限必须同时出现在 Plugin Manifest 中；
|
||||
- Agent 仍通过 Tool Registry 执行参数校验、Permission、超时和 Trace；
|
||||
- MCP `structuredContent` 存在时映射为内部 output；否则保留为受控 `content` 数组；
|
||||
- MCP `isError: true` 映射为 `MCP_TOOL_CALL_FAILED`；
|
||||
- 结果超过 256 KiB 映射为 `MCP_TOOL_RESULT_TOO_LARGE`。
|
||||
|
||||
## 6. 隔离与安全边界
|
||||
|
||||
当前隔离是“独立进程 + 协议边界”，不是完整的操作系统沙箱。
|
||||
|
||||
已经执行的保护：
|
||||
|
||||
- 第三方模块不 import 到 AI Core；
|
||||
- 子进程 `cwd` 固定为 Plugin 包目录；
|
||||
- 不使用 Shell 拼接命令；
|
||||
- 不把 Provider API Key、`APP_DB_PATH`、Vault 路径和其他宿主环境变量传入子进程；
|
||||
- stderr 与 JSON-RPC stdout 分离，stderr 不进入 API 和 Agent Trace；
|
||||
- stdout 只能发送合法 MCP JSON-RPC；
|
||||
- 单条协议消息上限 2 MiB；
|
||||
- 单次 Tool Result 上限 256 KiB；
|
||||
- MCP Tool 不绕过 Permission Manager 和 Agent Tool Timeout。
|
||||
|
||||
当前尚未提供容器、受限系统账户、seccomp、Windows AppContainer 或 macOS Sandbox，因此 Plugin 进程仍具有当前操作系统用户授予的一般文件访问能力。正式社区插件分发前必须继续增加包签名、来源验证和平台级沙箱；不得把当前进程隔离描述为完全安全执行任意不可信代码。
|
||||
|
||||
## 7. Host API
|
||||
|
||||
```http
|
||||
GET /api/plugins/{plugin_id}/host
|
||||
POST /api/plugins/{plugin_id}/host/restart
|
||||
```
|
||||
|
||||
状态响应包含：
|
||||
|
||||
```text
|
||||
plugin_id
|
||||
backend_type / transport
|
||||
status
|
||||
tools_count
|
||||
started_at / last_seen_at
|
||||
protocol_version
|
||||
server_name / server_version
|
||||
error
|
||||
```
|
||||
|
||||
状态值：
|
||||
|
||||
```text
|
||||
stopped
|
||||
starting
|
||||
ready
|
||||
unhealthy
|
||||
error
|
||||
```
|
||||
|
||||
Restart 返回 `202 OperationResponse`。接口返回前已完成本地 Host 重启和 Tool 重新发现；`message` 中给出最终 Host 状态。
|
||||
|
||||
## 8. 离线 Fixture
|
||||
|
||||
Fixture 位于：
|
||||
|
||||
```text
|
||||
backend/extensions/fixtures/mcp-echo
|
||||
```
|
||||
|
||||
它提供：
|
||||
|
||||
- `mcp-fixture.echo`：返回 structuredContent；
|
||||
- `mcp-fixture.fail`：返回 `isError: true`；
|
||||
- `mcp-fixture.sleep`：验证超时和取消；
|
||||
- `mcp-fixture.large`：验证结果大小上限；
|
||||
- `mcp-fixture.environment`：验证宿主 Secret/路径没有进入子进程；
|
||||
- `mcp-fixture.exit`：验证异常退出、Tool 注销和 Restart。
|
||||
|
||||
Fixture 的 `tools/list` 使用两页响应，用于覆盖分页发现。测试还会启动缺少 tools capability 和返回无效 Schema 的变体。
|
||||
|
||||
## 9. 验证
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
uv run python -m compileall -q app
|
||||
uv run pytest
|
||||
|
||||
cd ../frontend
|
||||
pnpm test
|
||||
pnpm type-check
|
||||
pnpm build
|
||||
```
|
||||
|
||||
阶段 C 新增测试覆盖：
|
||||
|
||||
- initialize、版本和 capability negotiation；
|
||||
- 分页 `tools/list` 与命名空间映射；
|
||||
- Permission、JSON Schema 与 Contribution 集合；
|
||||
- Tool 成功、业务错误、结果过大和超时；
|
||||
- Agent Runtime 调用 MCP Tool 并写入正式 Trace；
|
||||
- Secret/Vault 环境隔离；
|
||||
- Server 异常退出、Tool 注销和 Host Restart；
|
||||
- 缺少 capability 与无效 MCP Schema；
|
||||
- OpenAPI 发布 Host 状态和重启路径。
|
||||
|
||||
## 10. 当前边界与后续阶段
|
||||
|
||||
阶段 C 不包含：
|
||||
|
||||
- Streamable HTTP MCP transport；
|
||||
- Resources、Prompts、Sampling、Elicitation 和 MCP Tasks；
|
||||
- Plugin Command 与 Settings Contribution；
|
||||
- Secret Reference 注入；
|
||||
- Plugin Registry 持久化、签名与社区来源校验；
|
||||
- 操作系统级沙箱；
|
||||
- Tool 列表热更新的无中断替换。
|
||||
|
||||
阶段 D 将在当前 Plugin Runtime 上继续增加 Command、Settings、Secret Contract 和命名空间 Storage，不修改 Agent 使用内部 Tool Contract 的原则。
|
||||
Reference in New Issue
Block a user