独立 MCP Server 配置中心开发说明

更新日期：2026-09-03。本文记录第二阶段 C.1 的完整实现；独立 MCP Server Registry 与 Plugin 自带 MCP Host 是两个并列入口。

1. 已实现范围

独立 Server 的创建、读取、版本化编辑、删除和 Tool 摘要查询；
stdio、Streamable HTTP 和旧版 HTTP+SSE 三种 Transport；
stdio 可执行文件、参数、普通/加密环境变量，以及 HTTP URL、普通/加密 Header；
配置摘要确认、连接测试、启停、异常状态与最近一次测试结果；
MCP initialize、tools/list、tools/call、取消与动态 Tool 注册，名称为 mcp.{server_id}.{tool}；
Streamable HTTP Session、协议版本 Header、JSON/SSE POST 响应、可选 GET 事件流和 Last-Event-ID 重连；
旧 HTTP+SSE 的 endpoint 事件与消息 POST，并强制消息地址和配置地址同源；
前端表单/JSON 双模式、三种模板、高风险变更确认及请求期 Secret 输入。

Streamable HTTP 按 MCP 当前规范实现；SSE 仅用于兼容旧 Server，不应作为新部署首选。

2. 配置、版本与 Secret

普通配置原子写入 APP_DATA_DIR/mcp/servers.json。更新请求必须携带读取到的 version；版本过期返回 409 MCP_SERVER_VERSION_CONFLICT，避免多个页面互相覆盖。改变 Transport、命令、URL、Header、环境变量或权限后，旧授权和测试结果立即失效。

Secret 使用带类型和键名哈希的 mcp.* 内部 ID 写入 Fernet 凭据存储。API 只返回环境变量或 Header 是否配置，绝不返回明文。删除 Server 或移除 Secret 键会同步清理密文。前端密码框提交后立即清空，不写入 JSON 编辑器、localStorage、普通配置或日志。

3. 启用与运行时规则

一次连接按以下顺序执行：

用户检查服务端生成的连接摘要并确认当前摘要；
后端临时连接，完成 initialize 和 tools/list 后关闭连接；
只有当前摘要测试成功，启用操作才会启动长期连接并注册 Tool；
停用、删除、超时或异常退出会注销 Tool 并关闭连接。

HTTP Header 中 Host、Content-Type、MCP-Session-Id 等协议保留项不可由配置覆盖。URL 不允许内嵌凭据或 Fragment。旧 SSE 返回的 POST endpoint 必须与初始 URL 同源，防止认证 Header 被转发到其他站点。

stdio 命令不经过 Shell，管道、重定向和命令拼接不会被解释。Windows 使用新进程组并通过 taskkill /T 回收子树；POSIX 使用独立 session/process group 并向进程组发信号。Python 阶段仍无法提供文件、网络、系统调用或操作系统版本差异下的绝对隔离保证。

uvx 模板使用 --isolated、明确的 --from 和固定包版本。它只能隔离依赖，不能替代安全沙箱。非开发环境仍拒绝启动 stdio Server，并返回 403 MCP_SANDBOX_REQUIRED；远程 HTTP Transport 不创建本机子进程，但仍要求摘要确认和成功测试。第三阶段前的 C.5 将冻结 Tauri/Rust 沙箱设计。

4. 接口

GET    /api/mcp/servers
POST   /api/mcp/servers
GET    /api/mcp/servers/{server_id}
PUT    /api/mcp/servers/{server_id}
DELETE /api/mcp/servers/{server_id}
GET    /api/mcp/servers/{server_id}/tools
POST   /api/mcp/servers/{server_id}/trust
POST   /api/mcp/servers/{server_id}/test
POST   /api/mcp/servers/{server_id}/enable
POST   /api/mcp/servers/{server_id}/disable
PUT    /api/mcp/servers/{server_id}/secrets/{key}?kind=environment|header
DELETE /api/mcp/servers/{server_id}/secrets/{key}?kind=environment|header

完整字段、状态和错误码见《第二阶段接口契约-开发版》。协议实现参考 MCP 官方的 Transports 与 Lifecycle。

5. 验证

cd backend
uv run pytest -q tests/test_mcp_registry.py tests/test_extension_core.py

cd ../frontend
npm run type-check
npm test
npm run build

后端测试使用无需网络或密钥的 stdio Fixture，以及 httpx.MockTransport 驱动的确定性 HTTP/SSE Server Fixture。覆盖摘要授权、Secret 不回显、版本冲突、生产门禁、重启恢复、Streamable HTTP Session/Header/工具调用及旧 SSE 同源校验。前端覆盖模板切换、JSON 校验、Secret 请求期输入、测试失败和删除确认。

6. 后续边界

增加真实第三方 Server 的兼容矩阵；确定性 Fixture 只能证明宿主协议行为，不能代表所有实现兼容；
C.5 在第二阶段开发与测试完成后、第三阶段桌面端实现前冻结沙箱 Contract；
第三阶段将 stdio 进程创建和 Secret 托管迁移至 Tauri/Rust Host 与 Stronghold/系统 Keychain。

4.8 KiB Raw Blame History Unescape Escape