feat(mcp): add standalone server registry

Implement C.1 stdio MCP server CRUD, encrypted environment secrets, command digest approval, connection tests, lifecycle recovery, and dynamic tool registration. Add the standalone frontend configuration center, contracts, regression tests, and development documentation.
2026-09-03 14:49:49 +08:00
parent ed2e867db1
commit 2dc984401d
18 changed files with 1160 additions and 12 deletions
@@ -0,0 +1,47 @@
+# 独立 MCP Server 配置中心开发说明
+
+> 更新日期：2026-09-03。本文记录第二阶段 C.1 的 P0 实现；它与 Plugin 自带的 MCP Host 是两个并列入口。
+
+## 1. 已实现范围
+
+- 独立 Server 的创建、读取、编辑和删除；
+- stdio 命令、参数、普通环境变量、加密环境变量及超时配置；
+- 命令摘要确认、测试连接、启用、停用和异常状态展示；
+- MCP initialize、`tools/list` 与动态 Tool 注册，工具命名为 `mcp.{server_id}.{tool}`；
+- 启用状态持久化与开发服务重启恢复；
+- 前端独立“MCP”导航与配置弹窗，提供 stdio/uvx 模板；
+- Streamable HTTP 与旧 SSE 仅作为后续选项展示为禁用，不属于本次完成范围。
+
+## 2. 数据与 Secret
+
+普通配置原子写入 `APP_DATA_DIR/mcp/servers.json`。Secret 使用 `mcp.{server_id}.{key_hash}` 作为内部引用写入现有 Fernet 凭据存储；API 和前端只看到 `configured: true/false`。删除 Server 或移除 Secret 键时同步清理密文。
+
+前端 Secret 输入使用密码框，提交后立即清空，不写入 localStorage、普通配置 JSON 或日志。`mcp.*` 同 `plugin.*` 一样属于保留凭据命名空间，Provider 配置与通用凭据 API 无权读取。
+
+## 3. 启动安全边界
+
+命令不经过 Shell，管道、重定向和拼接字符串不会被解释。Host 只继承启动所需的系统变量，再叠加用户显式配置；`uvx` 可隔离 Python 依赖，但不能限制文件、网络和系统调用。
+
+后端会对影响执行的配置计算 SHA-256 摘要。测试或启用前，用户必须确认并回传当前摘要；修改配置会立即撤销旧确认。由于 Python Host 尚无 OS 沙箱，非开发环境硬拒绝启动。第三阶段由 Tauri/Rust Host 提供平台级隔离后再替换这道临时门禁。
+
+## 4. 测试与启动
+
+```powershell
+cd backend
+uv run pytest -q tests/test_mcp_registry.py
+uv run uvicorn app.main:app --reload
+
+cd ../frontend
+npm run type-check
+npm test
+npm run dev
+```
+
+打开知识库后进入左侧“MCP”。保存配置，按提示确认命令，先执行“测试连接”；成功后再启用。默认模板 `uvx mcp-server-fetch` 仅为配置示例，首次下载是否联网由本机 uv 缓存与网络环境决定。
+
+## 5. 后续增量
+
+- P1：Streamable HTTP 连接、认证 Header 与重连策略；
+- 兼容项：仅在确有旧服务需求时增加 SSE；
+- 第三阶段前：把命令确认与进程创建迁移至 Tauri/Rust 沙箱；
+- 增加面向真实第三方 Server 的兼容矩阵，不用单一 Fixture 代表协议全兼容。