# MCP Bridge 与 Plugin Host 开发说明

> 更新日期：2026-09-01。本文记录第二阶段阶段 C 已实现的本地 stdio MCP Bridge、隔离 Plugin Host、Tool Contract 转换和离线测试方式。Plugin Command 与 Settings 属于阶段 D，不在本文实现范围内。

## 1. 目标与实现状态

阶段 C 的目标是让外部 MCP Server 进入既有 Plugin、Tool、Permission、Agent 和 Trace 链路，同时避免 Agent Runtime、前端或 Benchmark 直接依赖 MCP 原始消息。

当前链路：

```text
Plugin Manifest
→ Plugin Runtime
→ 独立 stdio MCP Server 进程
→ initialize / capability negotiation
→ tools/list 分页发现与校验
→ NotesAgent ToolDefinition
→ Tool Registry / Permission Manager
→ Agent Runtime / Agent Trace
```

已经实现：

- 本地 stdio 子进程启动、关闭和异常退出检测；
- UTF-8、换行分隔的 JSON-RPC 2.0 消息；
- initialize、协议版本与 tools capability 协商；
- `notifications/initialized`；
- 分页 `tools/list`；
- `tools/call`、业务错误与 JSON-RPC 错误转换；
- 超时和 `notifications/cancelled`；
- Tool 命名空间、JSON Schema、权限和 Manifest 集合校验；
- Host 状态查询、重启和异常后的 Tool 自动注销；
- stderr 隔离、环境变量裁剪、消息及结果大小限制；
- 无网络、无密钥的确定性 MCP Fixture。

实现依据为 MCP 官方 [Lifecycle 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)、[Transports 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) 和 [Tools 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)。

## 2. 代码位置

```text
backend/app/extensions/mcp.py
    stdio 进程、JSON-RPC、MCP 生命周期、发现、调用和 Host 状态

backend/app/extensions/runtime.py
    Plugin Manifest、权限、MCP Tool 批量注册/回滚和生命周期集成

backend/app/agent/tools.py
    内部 Tool 参数校验、结构化执行错误和线程安全 Registry

backend/extensions/fixtures/mcp-echo/
    确定性 stdio MCP Server 与 Plugin Manifest
```

## 3. Plugin Manifest

MCP Plugin 的后端配置示例：

```yaml
id: example-mcp
name: Example MCP
version: 1.0.0
permissions:
  - notes.read
contributes:
  tools:
    - example-mcp.search
backend:
  type: mcp
  transport: stdio
  command: uvx
  args: [--isolated, --from, example-mcp==1.2.3, example-mcp]
  startup_timeout_seconds: 60
  tool_timeout_seconds: 30
```

约束：

- 阶段 C 只接受 `type: mcp` 与 `transport: stdio`；
- 命令和参数通过数组直接传给 `subprocess.Popen`，不经过 Shell；
- Python 包形式的 MCP Server 推荐使用 `uvx --isolated --from <package>==<version> <command>`，固定版本并与 NotesAgent 项目环境隔离；
- Plugin 包内自带且不需要第三方依赖的 Python 脚本可以使用 `python server.py`；Node、Rust 等 Server 继续使用各自受控启动器，因此 Host 不强制所有 MCP 都经过 `uvx`；
- PATH 中的 executable 使用名称，例如 `uvx`、`python`、`node`；
- manifest 中带目录的 executable 必须解析到 Plugin 包内部；
- `contributes.tools` 使用 `<plugin_id>.<remote_name>`；
- 安装阶段只读 Manifest，不启动第三方进程；
- 完成用户授权后，`enable` 才启动 Host。

## 4. 生命周期

### 4.1 启动

启用 MCP Plugin 时依次执行：

1. 检查 Plugin 声明权限是否全部获得授权；
2. 检查 Manifest 声明的 Tool ID 是否与现有 Registry 冲突；
3. 启动独立 stdio Server；
4. 发送 `initialize`；
5. 校验协商版本和 `tools` capability；
6. 发送 `notifications/initialized`；
7. 分页读取 `tools/list`；
8. 校验全部 Tool；
9. 确认发现集合与 Manifest 完全一致；
10. 将完整集合注册到 Tool Registry；
11. Plugin 和 Host 进入 `ready`。

任何步骤失败都会注销本轮已注册 Tool、关闭子进程并把 Plugin 标记为 `error`，不会留下半启用状态。

### 4.2 停止与异常退出

停用、卸载或应用关闭时，先注销 Tool，再关闭 stdin，等待 Server 正常退出。超时后依次 terminate 和 kill。

Server 异常退出、stdout 出现非 JSON-RPC 内容或发送超大协议消息时：

- 未完成请求返回 `PLUGIN_HOST_UNAVAILABLE`；
- Host 进入 `unhealthy`；
- Plugin 进入 `error`；
- 对应 Tool 从 Registry 中立即注销；
- 用户可以调用 Host Restart 接口重新协商和发现。

Server 发送 `notifications/tools/list_changed` 时不会直接信任新集合。当前实现先把 Host 标记为不健康并注销旧 Tool，要求通过 Restart 重新执行完整发现与校验。

## 5. Tool Contract 转换

MCP Tool：

```json
{
  "name": "search",
  "description": "Search notes",
  "inputSchema": { "type": "object", "properties": {} },
  "_meta": { "notesagent/permission": "notes.read" }
}
```

进入系统后转换为：

```json
{
  "name": "example-mcp.search",
  "description": "Search notes",
  "parameters": { "type": "object", "properties": {} },
  "permission": "notes.read",
  "source": "plugin"
}
```

转换规则：

- 远端名称必须能转换为合法且稳定的项目 Tool ID；
- `inputSchema` 必须是有效的 object JSON Schema；
- `additionalProperties`、`patternProperties` 等动态字段先由完整 JSON Schema 校验，Pydantic 参数载体不会再次误拒绝合法字段；
- `_meta.notesagent/permission` 必须属于项目已知权限；
- Tool 权限必须同时出现在 Plugin Manifest 中；
- Agent 仍通过 Tool Registry 执行参数校验、Permission、超时和 Trace；
- MCP `structuredContent` 存在时映射为内部 output；否则保留为受控 `content` 数组；
- MCP `isError: true` 映射为 `MCP_TOOL_CALL_FAILED`；
- 结果超过 256 KiB 映射为 `MCP_TOOL_RESULT_TOO_LARGE`。

## 6. 隔离与安全边界

当前隔离是“独立进程 + 协议边界”，不是完整的操作系统沙箱。

`uvx` 解决的是 Python 工具依赖隔离：它等价于 `uv tool run`，在 uv 缓存中使用可丢弃的独立虚拟环境。它不会限制 Server 读取用户文件、访问网络、创建子进程或调用系统 API，因此不能代替安全沙箱。当前开发模式下，首次 `enable` 尚未缓存的包可能访问包索引，因此示例使用 60 秒启动上限；生产实现不得依赖该行为，必须在用户确认后的安装/更新阶段预取和验证固定版本，运行阶段只启动已准备好的环境。

已经执行的保护：

- 第三方模块不 import 到 AI Core；
- 子进程 `cwd` 固定为 Plugin 包目录；
- 不使用 Shell 拼接命令；
- 不把 Provider API Key、`APP_DB_PATH`、Vault 路径和其他宿主环境变量传入子进程；
- stderr 与 JSON-RPC stdout 分离，stderr 不进入 API 和 Agent Trace；
- stdout 只能发送合法 MCP JSON-RPC；
- stdout 在读取完整行前即应用有界读取，单条协议消息上限 2 MiB；stderr 也按固定大小分块读取；
- 单次 Tool Result 上限 256 KiB；
- MCP Tool 不绕过 Permission Manager 和 Agent Tool Timeout。
- 调用被 Agent 取消时，同时通知 Server 并唤醒本地 pending Queue，阻塞线程不会继续占用线程池直至远端超时。

当前尚未提供容器、受限系统账户、seccomp、Windows AppContainer 或 macOS Sandbox，因此 Plugin 进程仍具有当前操作系统用户授予的一般文件访问能力。正式社区插件分发或“一键安装”前必须完成以下安全门槛：

- 由 Tauri/Rust Host 统一启动进程并提供平台级文件、网络、子进程和资源配额限制；
- 安装/更新时完整展示 executable 与全部参数，明确警告并要求用户主动确认；
- 固定包来源和版本，增加包哈希/签名与可信发布者校验；
- 默认禁止访问 Vault、凭据和宿主环境，只通过声明 Permission 与受控 Host API 授权；
- 关闭 Host 时终止完整进程树，不只结束直接子进程。

在这些门槛完成前，当前 MCP Host 只适用于内置 Fixture、团队可信插件和开发联调；不得把它描述为可以安全执行任意社区代码。上述安装确认要求遵循 MCP [SEP-1024](https://modelcontextprotocol.io/seps/1024-mcp-client-security-requirements-for-local-server-)；`uvx` 行为依据 uv 官方 [Using tools](https://docs.astral.sh/uv/guides/tools/) 文档。

后端通过 `APP_ENVIRONMENT` 强制该边界：只有 `development` 可以启动当前未沙箱化的 MCP Host；其他环境返回 `403 MCP_TRUST_APPROVAL_REQUIRED`，且不会创建进程或注册 Tool。后续 Tauri/Rust Host 提供沙箱与绑定完整命令摘要的可信许可后，再替换此临时门禁。

## 7. Host API

```http
GET  /api/plugins/{plugin_id}/host
POST /api/plugins/{plugin_id}/host/restart
```

状态响应包含：

```text
plugin_id
backend_type / transport
status
tools_count
started_at / last_seen_at
protocol_version
server_name / server_version
error
```

状态值：

```text
stopped
starting
ready
unhealthy
error
```

Restart 返回 `202 OperationResponse`。接口返回前已完成本地 Host 重启和 Tool 重新发现；`message` 中给出最终 Host 状态。Restart 只用于运行中或异常 Host；用户主动停用、尚未启用或等待授权的 Plugin 返回 `409 PLUGIN_HOST_UNAVAILABLE`，必须通过 Enable 明确启动。

## 8. 离线 Fixture

Fixture 位于：

```text
backend/extensions/fixtures/mcp-echo
```

它提供：

- `mcp-fixture.echo`：返回 structuredContent；
- `mcp-fixture.fail`：返回 `isError: true`；
- `mcp-fixture.sleep`：验证超时和取消；
- `mcp-fixture.large`：验证结果大小上限；
- `mcp-fixture.environment`：验证宿主 Secret/路径没有进入子进程；
- `mcp-fixture.exit`：验证异常退出、Tool 注销和 Restart。

Fixture 的 `tools/list` 使用两页响应，用于覆盖分页发现。测试还会启动缺少 tools capability、返回无效 Schema/initialize result，以及输出超长无换行 stdout 的变体。

## 9. 验证

```powershell
cd backend
uv run python -m compileall -q app
uv run pytest

cd ../frontend
pnpm test
pnpm type-check
pnpm build
```

阶段 C 新增测试覆盖：

- initialize、版本和 capability negotiation；
- 分页 `tools/list` 与命名空间映射；
- Permission、JSON Schema 与 Contribution 集合；
- Tool 成功、业务错误、结果过大和超时；
- Agent 取消后 pending 等待线程及时释放；
- `additionalProperties` 动态参数保持 JSON Schema 语义；
- Agent Runtime 调用 MCP Tool 并写入正式 Trace；
- Secret/Vault 环境隔离；
- Server 异常退出、Tool 注销和 Host Restart；
- 缺少 capability、无效 initialize result、无效 MCP Schema 和超长无换行 stdout；
- disabled Plugin 不会被 Host Restart 隐式重新启用；
- OpenAPI 发布 Host 状态和重启路径。

## 10. 当前边界与后续阶段

阶段 C 不包含：

- Streamable HTTP MCP transport；
- Resources、Prompts、Sampling、Elicitation 和 MCP Tasks；
- Plugin Command 与 Settings Contribution；
- Secret Reference 注入；
- Plugin Registry 持久化、签名与社区来源校验；
- 操作系统级沙箱；
- 一键安装前的完整命令展示与确认 UI；
- Tool 列表热更新的无中断替换。

阶段 D 将在当前 Plugin Runtime 上继续增加 Command、Settings、Secret Contract 和命名空间 Storage，不修改 Agent 使用内部 Tool Contract 的原则。