feat(mcp): complete remote transports and configuration workflow
This commit is contained in:
@@ -1,47 +1,76 @@
|
||||
# 独立 MCP Server 配置中心开发说明
|
||||
|
||||
> 更新日期：2026-09-03。本文记录第二阶段 C.1 的 P0 实现；它与 Plugin 自带的 MCP Host 是两个并列入口。
|
||||
> 更新日期：2026-09-03。本文记录第二阶段 C.1 的完整实现；独立 MCP Server Registry 与 Plugin 自带 MCP Host 是两个并列入口。
|
||||
|
||||
## 1. 已实现范围
|
||||
|
||||
- 独立 Server 的创建、读取、编辑和删除；
|
||||
- stdio 命令、参数、普通环境变量、加密环境变量及超时配置；
|
||||
- 命令摘要确认、测试连接、启用、停用和异常状态展示；
|
||||
- MCP initialize、`tools/list` 与动态 Tool 注册，工具命名为 `mcp.{server_id}.{tool}`；
|
||||
- 启用状态持久化与开发服务重启恢复；
|
||||
- 前端独立“MCP”导航与配置弹窗，提供 stdio/uvx 模板；
|
||||
- Streamable HTTP 与旧 SSE 仅作为后续选项展示为禁用，不属于本次完成范围。
|
||||
- 独立 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 输入。
|
||||
|
||||
## 2. 数据与 Secret
|
||||
Streamable HTTP 按 MCP 当前规范实现；SSE 仅用于兼容旧 Server，不应作为新部署首选。
|
||||
|
||||
普通配置原子写入 `APP_DATA_DIR/mcp/servers.json`。Secret 使用 `mcp.{server_id}.{key_hash}` 作为内部引用写入现有 Fernet 凭据存储；API 和前端只看到 `configured: true/false`。删除 Server 或移除 Secret 键时同步清理密文。
|
||||
## 2. 配置、版本与 Secret
|
||||
|
||||
前端 Secret 输入使用密码框，提交后立即清空，不写入 localStorage、普通配置 JSON 或日志。`mcp.*` 同 `plugin.*` 一样属于保留凭据命名空间，Provider 配置与通用凭据 API 无权读取。
|
||||
普通配置原子写入 `APP_DATA_DIR/mcp/servers.json`。更新请求必须携带读取到的 `version`；版本过期返回 `409 MCP_SERVER_VERSION_CONFLICT`，避免多个页面互相覆盖。改变 Transport、命令、URL、Header、环境变量或权限后，旧授权和测试结果立即失效。
|
||||
|
||||
## 3. 启动安全边界
|
||||
Secret 使用带类型和键名哈希的 `mcp.*` 内部 ID 写入 Fernet 凭据存储。API 只返回环境变量或 Header 是否配置，绝不返回明文。删除 Server 或移除 Secret 键会同步清理密文。前端密码框提交后立即清空，不写入 JSON 编辑器、localStorage、普通配置或日志。
|
||||
|
||||
命令不经过 Shell，管道、重定向和拼接字符串不会被解释。Host 只继承启动所需的系统变量，再叠加用户显式配置；`uvx` 可隔离 Python 依赖，但不能限制文件、网络和系统调用。
|
||||
## 3. 启用与运行时规则
|
||||
|
||||
后端会对影响执行的配置计算 SHA-256 摘要。测试或启用前，用户必须确认并回传当前摘要；修改配置会立即撤销旧确认。由于 Python Host 尚无 OS 沙箱，非开发环境硬拒绝启动。第三阶段由 Tauri/Rust Host 提供平台级隔离后再替换这道临时门禁。
|
||||
一次连接按以下顺序执行：
|
||||
|
||||
## 4. 测试与启动
|
||||
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
|
||||
uv run uvicorn app.main:app --reload
|
||||
uv run pytest -q tests/test_mcp_registry.py tests/test_extension_core.py
|
||||
|
||||
cd ../frontend
|
||||
npm run type-check
|
||||
npm test
|
||||
npm run dev
|
||||
npm run build
|
||||
```
|
||||
|
||||
打开知识库后进入左侧“MCP”。保存配置，按提示确认命令，先执行“测试连接”；成功后再启用。默认模板 `uvx mcp-server-fetch` 仅为配置示例，首次下载是否联网由本机 uv 缓存与网络环境决定。
|
||||
后端测试使用无需网络或密钥的 stdio Fixture，以及 `httpx.MockTransport` 驱动的确定性 HTTP/SSE Server Fixture。覆盖摘要授权、Secret 不回显、版本冲突、生产门禁、重启恢复、Streamable HTTP Session/Header/工具调用及旧 SSE 同源校验。前端覆盖模板切换、JSON 校验、Secret 请求期输入、测试失败和删除确认。
|
||||
|
||||
## 5. 后续增量
|
||||
## 6. 后续边界
|
||||
|
||||
- P1：Streamable HTTP 连接、认证 Header 与重连策略；
|
||||
- 兼容项：仅在确有旧服务需求时增加 SSE；
|
||||
- 第三阶段前：把命令确认与进程创建迁移至 Tauri/Rust 沙箱；
|
||||
- 增加面向真实第三方 Server 的兼容矩阵，不用单一 Fixture 代表协议全兼容。
|
||||
- 增加真实第三方 Server 的兼容矩阵；确定性 Fixture 只能证明宿主协议行为，不能代表所有实现兼容；
|
||||
- C.5 在第二阶段开发与测试完成后、第三阶段桌面端实现前冻结沙箱 Contract；
|
||||
- 第三阶段将 stdio 进程创建和 Secret 托管迁移至 Tauri/Rust Host 与 Stronghold/系统 Keychain。
|
||||
|
||||
Reference in New Issue
Block a user