77 lines
4.8 KiB
Markdown
77 lines
4.8 KiB
Markdown
# 独立 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. 启用与运行时规则
|
||
|
||
一次连接按以下顺序执行：
|
||
|
||
1. 用户检查服务端生成的连接摘要并确认当前摘要；
|
||
2. 后端临时连接，完成 initialize 和 `tools/list` 后关闭连接；
|
||
3. 只有当前摘要测试成功，启用操作才会启动长期连接并注册 Tool；
|
||
4. 停用、删除、超时或异常退出会注销 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. 接口
|
||
|
||
```text
|
||
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](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) 与 [Lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)。
|
||
|
||
## 5. 验证
|
||
|
||
```powershell
|
||
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。
|