feat(mcp): complete remote transports and configuration workflow
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
> 文档状态：接口冻结草案
|
||||
>
|
||||
> 更新日期：2026-09-02
|
||||
> 更新日期：2026-09-03
|
||||
>
|
||||
> 依据：`../architecture/第二阶段团队分工表.md`、`../architecture/AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md`
|
||||
|
||||
@@ -47,12 +47,13 @@
|
||||
| Agent Trace | GET | `/api/agent/runs/{run_id}/trace` | 已实现 | 分页读取可回放 Trace 快照 |
|
||||
| Plugin Host | GET | `/api/plugins/{plugin_id}/host` | 已实现 | 获取 MCP Host 健康状态 |
|
||||
| Plugin Host | POST | `/api/plugins/{plugin_id}/host/restart` | 已实现 | 重启异常 Host 并重新发现 Tool |
|
||||
| MCP Server | GET/POST | `/api/mcp/servers` | 已实现（C.1/P0） | 列出、创建独立 MCP Server 配置 |
|
||||
| MCP Server | GET/PUT/DELETE | `/api/mcp/servers/{server_id}` | 已实现（C.1/P0） | 读取、修改、删除独立配置 |
|
||||
| MCP Server | POST | `/api/mcp/servers/{server_id}/trust` | 已实现（C.1/P0） | 确认当前可执行配置摘要 |
|
||||
| MCP Server | POST | `/api/mcp/servers/{server_id}/test` | 已实现（C.1/P0） | 隔离启动、握手、发现工具后退出 |
|
||||
| MCP Server | POST | `/api/mcp/servers/{server_id}/enable`、`disable` | 已实现（C.1/P0） | 控制 Host 与动态 Tool 生命周期 |
|
||||
| MCP Server | PUT/DELETE | `/api/mcp/servers/{server_id}/secrets/{key}` | 已实现（C.1/P0） | 写入或删除加密环境变量 |
|
||||
| MCP Server | GET/POST | `/api/mcp/servers` | 已实现（C.1） | 列出、创建独立 MCP Server 配置 |
|
||||
| MCP Server | GET/PUT/DELETE | `/api/mcp/servers/{server_id}` | 已实现（C.1） | 读取、版本化修改、删除独立配置 |
|
||||
| MCP Server | GET | `/api/mcp/servers/{server_id}/tools` | 已实现（C.1） | 获取映射后的 Tool 摘要 |
|
||||
| MCP Server | POST | `/api/mcp/servers/{server_id}/trust` | 已实现（C.1） | 确认当前连接配置摘要 |
|
||||
| MCP Server | POST | `/api/mcp/servers/{server_id}/test` | 已实现（C.1） | 临时连接、握手、发现工具后关闭 |
|
||||
| MCP Server | POST | `/api/mcp/servers/{server_id}/enable`、`disable` | 已实现（C.1） | 控制连接与动态 Tool 生命周期 |
|
||||
| MCP Server | PUT/DELETE | `/api/mcp/servers/{server_id}/secrets/{key}` | 已实现（C.1） | 按 `kind` 写入或删除加密环境变量/Header |
|
||||
| Plugin Command | GET | `/api/plugin-contributions/commands` | 已实现 | 获取前端可展示的 Command |
|
||||
| Plugin Command | POST | `/api/plugin-contributions/commands/{command_id}/execute` | 已实现 | 受控执行 Command |
|
||||
| Plugin Settings | GET | `/api/plugins/{plugin_id}/settings` | 已实现 | 获取 Schema 与非敏感配置 |
|
||||
@@ -659,9 +660,19 @@ MCP_TRANSPORT_UNSUPPORTED
|
||||
MCP_SERVER_NOT_FOUND
|
||||
MCP_SERVER_NAME_INVALID
|
||||
MCP_SERVER_ALREADY_ENABLED
|
||||
MCP_SERVER_VERSION_CONFLICT
|
||||
MCP_REGISTRY_WRITE_FAILED
|
||||
MCP_REGISTRY_INVALID
|
||||
MCP_CONNECTION_TEST_REQUIRED
|
||||
MCP_CONFIG_INVALID
|
||||
MCP_COMMAND_INVALID
|
||||
MCP_URL_INVALID
|
||||
MCP_HEADER_INVALID
|
||||
MCP_HTTP_REQUEST_FAILED
|
||||
MCP_HTTP_RESPONSE_INVALID
|
||||
MCP_SECRET_REQUIRED
|
||||
MCP_SECRET_NOT_DECLARED
|
||||
MCP_SECRET_KIND_INVALID
|
||||
MCP_SECRET_STORE_ERROR
|
||||
MCP_ENVIRONMENT_INVALID
|
||||
MCP_PERMISSION_INVALID
|
||||
@@ -690,11 +701,15 @@ CREDENTIAL_NAMESPACE_RESERVED
|
||||
|
||||
### 7.8 独立 MCP Server Registry（C.1）
|
||||
|
||||
独立 Server 不依附 Plugin Manifest，配置持久化于 `APP_DATA_DIR/mcp/servers.json`，敏感环境变量只以 `mcp.*` 引用进入加密凭据存储。响应仅返回每个 Secret 是否已配置，不返回明文。动态工具使用 `mcp.{server_id}.{remote_tool}` 命名空间，来源标记为 `mcp_server`，仍通过统一 Tool Registry、Permission Manager 与 Agent Trace。
|
||||
独立 Server 不依附 Plugin Manifest，配置持久化于 `APP_DATA_DIR/mcp/servers.json`。`transport` 支持 `stdio`、`streamable_http` 和兼容旧服务的 `sse`。敏感环境变量与认证 Header 只以 `mcp.*` 引用进入加密凭据存储；读取响应以 `secret_environment`、`secret_headers` 的布尔值表示配置状态，不返回明文。动态工具使用 `mcp.{server_id}.{remote_tool}` 命名空间，来源标记为 `mcp_server`，仍通过统一 Tool Registry、Permission Manager 与 Agent Trace。
|
||||
|
||||
P0 只真实支持 `stdio`。`streamable_http` 与 `sse` 已作为后续 Contract 枚举保留，但测试或启用会返回 `501 MCP_TRANSPORT_UNSUPPORTED`，前端不可伪装为可用。命令始终以 executable 与 args 数组通过 `shell=False` 启动；普通环境变量和加密 Secret 显式注入，不继承 Provider Key、数据库或 Vault 路径。
|
||||
stdio 配置使用 `command`、`args`、`environment` 和 `secret_environment_keys`；HTTP/SSE 配置使用 `url`、`headers` 和 `secret_header_keys`，两组 Transport 字段不可混用。更新请求必须携带当前 `version`，成功后版本递增；过期版本返回 `409 MCP_SERVER_VERSION_CONFLICT`。`GET /tools` 返回 `name`、`remote_name`、`description` 和可选 `permission`。
|
||||
|
||||
创建或编辑配置后，调用方必须向 `/trust` 回传服务端计算的 `command_digest`。后端只接受与当前 transport、command、args、环境变量键值及权限完全一致的摘要；配置变化会撤销旧信任。测试连接同样会实际启动进程，因此也要求确认。当前 Python Host 仅在 `APP_ENVIRONMENT=development` 时允许启动；其他环境返回 `403 MCP_SANDBOX_REQUIRED`，等待第三阶段桌面端沙箱接管。
|
||||
创建或编辑配置后，调用方必须向 `/trust` 回传服务端计算的 `command_digest`。后端只接受与当前 Transport、连接参数、环境/Header 及权限完全一致的摘要；配置变化会撤销旧信任和测试结果。只有当前摘要通过 `/test`，才能调用 `/enable`。测试失败也会持久化时间和失败状态。
|
||||
|
||||
Streamable HTTP 支持 Session ID、`MCP-Protocol-Version`、JSON 或 SSE POST 响应、可选 GET 事件流及 `Last-Event-ID`；旧 SSE 按 endpoint 事件确定 POST 地址，并要求与初始 URL 同源。Secret 接口用 `?kind=environment` 或 `?kind=header` 区分类型。HTTP URL 不允许内嵌凭据或 Fragment，配置不得覆盖协议保留 Header。
|
||||
|
||||
stdio 命令始终以 executable 与 args 数组通过 `shell=False` 启动；普通环境变量和加密 Secret 显式注入，不继承 Provider Key、数据库或 Vault 路径。当前 Python Host 仅在 `APP_ENVIRONMENT=development` 时允许启动 stdio；其他环境返回 `403 MCP_SANDBOX_REQUIRED`。远程 HTTP Transport 不创建本机进程，但仍受摘要确认、成功测试、超时、消息限长与 Secret 隔离约束。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user