# 独立 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 代表协议全兼容。