feat(extension): 接入 stdio MCP Bridge 与 Plugin Host #8

2026-09-01T22:10:48+08:00

Kronecker commented

2026-09-01 22:10:48 +08:00

PR Note

变更概述

完成第二阶段阶段 C 的 stdio MCP Bridge 与 Plugin Host，使 Agent Core 可以通过统一的 Tool Registry 调用 MCP Server 提供的工具。

主要内容

新增 stdio MCP Client 与 Plugin Host 生命周期管理。
支持 MCP 初始化、协议版本协商和能力检查。
支持分页执行 tools/list 并注册命名空间 Tool。
支持 tools/call、业务错误转换、超时与取消。
支持 Host 状态查询、停用、重启、异常退出和资源回收。
MCP Host 异常后自动注销相关 Tool，避免继续调用失效进程。
Plugin 禁用、卸载及 FastAPI 退出时关闭子进程。
支持 MCP JSON Schema 联合类型、动态属性和特殊字段名。
保留显式 null，不再把缺失的可选参数自动补成 null。
Tool Registry 增加并发保护和领域错误码透传。
Agent Tool 上下文增加 tool_call_id，用于 MCP 请求关联与取消。
补充前端 Plugin Host 状态类型和服务接口。

新增接口

GET /api/plugins/{plugin_id}/host
POST /api/plugins/{plugin_id}/host/restart

同时将以下可能阻塞的 Plugin 操作移入工作线程：

POST   /api/plugins/{plugin_id}/enable
POST   /api/plugins/{plugin_id}/disable
PUT    /api/plugins/{plugin_id}/permissions
DELETE /api/plugins/{plugin_id}

安全边界

MCP 命令通过参数数组直接启动，不经过 Shell。
Plugin 包内的可执行文件必须保持在包目录内。
子进程仅继承必要系统环境变量，不继承 Provider API Key、数据库路径及 Vault 路径。
限制协议消息、Tool 数量、分页次数和 Tool 返回结果大小。
Python MCP Server 推荐使用固定版本的 uvx --isolated --from。
uvx 仅提供依赖隔离，不视为操作系统安全沙箱。
当前未沙箱化 MCP Host 仅允许在 APP_ENVIRONMENT=development 下运行。
其他环境启用 MCP Plugin 时返回：

403 MCP_TRUST_APPROVAL_REQUIRED

后续面向社区插件前仍需补充 Tauri/Rust 沙箱、完整命令确认、包签名和来源校验。

测试覆盖

新增或完善以下测试：

MCP 初始化与 Tool 发现
Agent 通过 Registry 调用 MCP Tool
分页 Tool 发现
JSON Schema 校验
动态属性及特殊字段名
可选参数与显式 null
MCP 业务错误转换
Tool 超时与取消
超大消息及超大结果拒绝
Host 异常退出与 Tool 注销
Host 重启恢复
环境变量隔离
Plugin 禁用、卸载及状态清理
生产环境安全门禁

验证结果：

Backend:  92 passed
Frontend: 27 passed
TypeScript type-check: passed
Frontend production build: passed
Python compileall: passed
git diff --check: passed

前端构建仍存在已有的大文件分块警告，不影响本次功能正确性。

文档更新

MCP Bridge 与 Plugin Host 开发说明
第二阶段接口契约
后端接口契约
团队技术栈说明
项目及前后端开发说明
测试基线更新为后端 92 项、前端 27 项

合并结论

已基于最新 main 生成合并树并完成复审，无代码冲突及阻断性问题，建议合并。

## PR Note ### 变更概述完成第二阶段阶段 C 的 stdio MCP Bridge 与 Plugin Host，使 Agent Core 可以通过统一的 Tool Registry 调用 MCP Server 提供的工具。 ### 主要内容 - 新增 stdio MCP Client 与 Plugin Host 生命周期管理。 - 支持 MCP 初始化、协议版本协商和能力检查。 - 支持分页执行 `tools/list` 并注册命名空间 Tool。 - 支持 `tools/call`、业务错误转换、超时与取消。 - 支持 Host 状态查询、停用、重启、异常退出和资源回收。 - MCP Host 异常后自动注销相关 Tool，避免继续调用失效进程。 - Plugin 禁用、卸载及 FastAPI 退出时关闭子进程。 - 支持 MCP JSON Schema 联合类型、动态属性和特殊字段名。 - 保留显式 `null`，不再把缺失的可选参数自动补成 `null`。 - Tool Registry 增加并发保护和领域错误码透传。 - Agent Tool 上下文增加 `tool_call_id`，用于 MCP 请求关联与取消。 - 补充前端 Plugin Host 状态类型和服务接口。 ### 新增接口 ```http GET /api/plugins/{plugin_id}/host POST /api/plugins/{plugin_id}/host/restart ``` 同时将以下可能阻塞的 Plugin 操作移入工作线程： ```http POST /api/plugins/{plugin_id}/enable POST /api/plugins/{plugin_id}/disable PUT /api/plugins/{plugin_id}/permissions DELETE /api/plugins/{plugin_id} ``` ### 安全边界 - MCP 命令通过参数数组直接启动，不经过 Shell。 - Plugin 包内的可执行文件必须保持在包目录内。 - 子进程仅继承必要系统环境变量，不继承 Provider API Key、数据库路径及 Vault 路径。 - 限制协议消息、Tool 数量、分页次数和 Tool 返回结果大小。 - Python MCP Server 推荐使用固定版本的 `uvx --isolated --from`。 - `uvx` 仅提供依赖隔离，不视为操作系统安全沙箱。 - 当前未沙箱化 MCP Host 仅允许在 `APP_ENVIRONMENT=development` 下运行。 - 其他环境启用 MCP Plugin 时返回： ```text 403 MCP_TRUST_APPROVAL_REQUIRED ``` 后续面向社区插件前仍需补充 Tauri/Rust 沙箱、完整命令确认、包签名和来源校验。 ### 测试覆盖新增或完善以下测试： - MCP 初始化与 Tool 发现 - Agent 通过 Registry 调用 MCP Tool - 分页 Tool 发现 - JSON Schema 校验 - 动态属性及特殊字段名 - 可选参数与显式 `null` - MCP 业务错误转换 - Tool 超时与取消 - 超大消息及超大结果拒绝 - Host 异常退出与 Tool 注销 - Host 重启恢复 - 环境变量隔离 - Plugin 禁用、卸载及状态清理 - 生产环境安全门禁验证结果： ```text Backend: 92 passed Frontend: 27 passed TypeScript type-check: passed Frontend production build: passed Python compileall: passed git diff --check: passed ``` 前端构建仍存在已有的大文件分块警告，不影响本次功能正确性。 ### 文档更新 - MCP Bridge 与 Plugin Host 开发说明 - 第二阶段接口契约 - 后端接口契约 - 团队技术栈说明 - 项目及前后端开发说明 - 测试基线更新为后端 92 项、前端 27 项 ### 合并结论已基于最新 `main` 生成合并树并完成复审，无代码冲突及阻断性问题，建议合并。

Kronecker added 5 commits 2026-09-01 22:10:49 +08:00

feat(extension): 接入 stdio MCP Plugin Host fc4b7b9495

docs(extension): 补充阶段C MCP开发说明 aedb1c1267

fix(extension): 修复 MCP Host 资源与协议边界 1132a4cece

fix(extension): 完善 MCP 参数与运行安全边界 574b113827

fix(extension): 强化 MCP 参数与生产运行门禁 e37ac7b0a4

Kronecker merged commit eb940e6590 into main

2026-09-01 22:10:57 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Kronecker/NotesAgentic#8