chore: initialize qiming workspace repository
This commit is contained in:
Codex
327
qimingclaw/docs/persistent-mcp-bridge-architecture.md
Normal file
327
qimingclaw/docs/persistent-mcp-bridge-architecture.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# 持久化 MCP Server Bridge 架构设计
|
||||
|
||||
## 背景与问题
|
||||
|
||||
### 原有方案
|
||||
|
||||
`qiming-mcp-stdio-proxy` 作为 MCP 聚合代理，由 ACP 引擎在每个 session 启动时 spawn，聚合所有用户配置的 MCP server 到一个 stdio endpoint。
|
||||
|
||||
```
|
||||
ACP Session
|
||||
└── qiming-mcp-stdio-proxy (stdio)
|
||||
├── chrome-devtools-mcp (子进程)
|
||||
├── filesystem-mcp (子进程)
|
||||
└── ...
|
||||
```
|
||||
|
||||
**核心问题**：proxy 进程的生命周期与 ACP session 绑定 — session 结束 → proxy 进程退出 → 所有 MCP server 子进程被 kill。
|
||||
|
||||
对于 chrome-devtools-mcp 这类有状态（stateful）的 MCP server：
|
||||
|
||||
| 问题 | 说明 |
|
||||
|------|------|
|
||||
| 状态丢失 | 每次 session 启动都 spawn 新 chrome-devtools-mcp → 启动新 Chrome → 之前的浏览器状态（页面、登录态、DOM 修改）全部丢失 |
|
||||
| `--isolated` 模式 | 避免 Chrome profile 冲突，但每次都是全新浏览器，无法跨 session 连续操作 |
|
||||
| 非 `--isolated` 模式 | Chrome profile 锁冲突："browser already running"，因为上一个 Chrome 可能还没完全退出 |
|
||||
|
||||
### 设计目标
|
||||
|
||||
将需要持久化状态的 MCP server 的生命周期从 ACP session 中解耦，由 Electron 主进程管理。
|
||||
|
||||
---
|
||||
|
||||
## 新方案：双通道架构
|
||||
|
||||
### 概览
|
||||
|
||||
引入 `persistent` 标志位，将 MCP server 分为两类，走不同的通道：
|
||||
|
||||
| 类型 | 标志 | 生命周期 | 通道 |
|
||||
|------|------|---------|------|
|
||||
| **临时 server**（ephemeral） | `persistent: false`（默认） | 跟随 ACP session | qiming-mcp-stdio-proxy 聚合（不变） |
|
||||
| **持久化 server**（persistent） | `persistent: true` | 跟随 Electron 主进程 | PersistentMcpBridge HTTP ← qiming-mcp-stdio-proxy bridge 入口（{ url }） |
|
||||
|
||||
### 架构图
|
||||
|
||||
```
|
||||
Electron Main Process（长生命周期）
|
||||
│
|
||||
├── PersistentMcpBridge（新组件，单例）
|
||||
│ │
|
||||
│ ├── 持久化子进程: chrome-devtools-mcp（stdio，主进程 spawn）
|
||||
│ │ └── MCP Client ← StdioClientTransport → 子进程 stdin/stdout
|
||||
│ │
|
||||
│ ├── HTTP Server（127.0.0.1，自动分配端口）
|
||||
│ │ └── 路由: POST/GET/DELETE /mcp/<serverId>
|
||||
│ │ └── 每个 HTTP client session → Server + StreamableHTTPServerTransport
|
||||
│ │ └── 代理 tools/list, tools/call → 共享的 MCP Client
|
||||
│ │
|
||||
│ └── 自动重启 + 健康检查 + session 清理
|
||||
│
|
||||
└── McpProxyManager.getAgentMcpConfig()
|
||||
└── 单一 mcp-proxy：qiming-mcp-stdio-proxy --config '{ mcpServers: { stdio... | url... } }'
|
||||
├── 临时 server → { command, args, env }（stdio 子进程）
|
||||
└── 持久化 server → { url }（bridge，StreamableHTTP → PersistentMcpBridge）
|
||||
|
||||
Per ACP Session（短生命周期）
|
||||
│
|
||||
└── qiming-mcp-stdio-proxy（单一进程，混合 stdio + bridge）
|
||||
├── 临时 server：stdio 子进程
|
||||
└── 持久化 server：StreamableHTTPClientTransport → PersistentMcpBridge HTTP
|
||||
```
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
Agent 引擎（claude-code / qimingcode）
|
||||
│
|
||||
└── mcp_servers.mcp-proxy (stdio) ← 单一入口
|
||||
└── qiming-mcp-stdio-proxy --config '{ mcpServers: {...} }'
|
||||
├── stdio 条目 → 子进程（临时 server）
|
||||
└── bridge 条目 { url } → StreamableHTTPClientTransport
|
||||
└── HTTP POST /mcp/<serverId> → Electron PersistentMcpBridge
|
||||
└── MCP Client (StdioClientTransport) → chrome-devtools-mcp（持久化子进程）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 1. McpServerEntry — 配置类型
|
||||
|
||||
```typescript
|
||||
interface McpServerEntry {
|
||||
command: string;
|
||||
args: string[];
|
||||
env?: Record<string, string>;
|
||||
persistent?: boolean; // 标记为持久化 server
|
||||
}
|
||||
```
|
||||
|
||||
`persistent: true` 的 server 由 PersistentMcpBridge 管理，不再传给 qiming-mcp-stdio-proxy。
|
||||
|
||||
### 2. PersistentMcpBridge — 主进程 HTTP Bridge
|
||||
|
||||
**文件**: `src/main/services/packages/persistentMcpBridge.ts`
|
||||
|
||||
**职责**：
|
||||
- 管理持久化 MCP server 子进程的完整生命周期
|
||||
- 提供 HTTP bridge 供 ACP session 的 bridge client 连接
|
||||
- 工具列表缓存、子进程自动重启、session 清理
|
||||
|
||||
**关键设计**：
|
||||
|
||||
| 设计点 | 方案 |
|
||||
|--------|------|
|
||||
| 子进程管理 | MCP SDK `StdioClientTransport` 内部 spawn，通过 `Client.connect()` 启动 |
|
||||
| HTTP 协议 | MCP SDK `StreamableHTTPServerTransport`（非 SSE，StreamableHTTP 是最新标准） |
|
||||
| 端口分配 | `server.listen(0, '127.0.0.1')` 系统自动分配，仅监听 loopback |
|
||||
| 路径路由 | 单端口，`/mcp/<serverId>` 路由到对应 server |
|
||||
| Session 模型 | 每个 HTTP client session 独立的 `Server` + `StreamableHTTPServerTransport` 对，共享底层 `Client` |
|
||||
| 并发安全 | MCP SDK `Client.callTool()` 内部使用 JSON-RPC 请求 ID 做响应关联，天然支持并发 |
|
||||
| 自动重启 | 子进程退出 → 5 秒冷却 → 自动重新 spawn + connect |
|
||||
| 安全防护 | HTTP body 10MB 限制、stale session 60 秒定期清理、进程 force-kill 兜底 |
|
||||
|
||||
**API**：
|
||||
|
||||
```typescript
|
||||
class PersistentMcpBridge {
|
||||
start(servers: Record<string, McpServerEntry>): Promise<void>; // 启动 bridge
|
||||
stop(): Promise<void>; // 停止 bridge
|
||||
getBridgeUrl(serverId: string): string | null; // 获取 HTTP URL
|
||||
isRunning(): boolean; // 是否在运行
|
||||
isServerHealthy(serverId: string): boolean; // server 健康检查
|
||||
}
|
||||
|
||||
export const persistentMcpBridge: PersistentMcpBridge; // 单例
|
||||
```
|
||||
|
||||
### 3. Bridge 入口（已并入 qiming-mcp-stdio-proxy）
|
||||
|
||||
持久化 server 的桥接不再使用独立脚本，由 **qiming-mcp-stdio-proxy** 的 `--config` 中 `{ url }` 条目完成：
|
||||
|
||||
- **stdio 条目**：`{ command, args, env }` → proxy 内部 spawn 子进程（临时 server）
|
||||
- **bridge 条目**：`{ url: "http://127.0.0.1:PORT/mcp/<serverId>" }` → proxy 内部用 `StreamableHTTPClientTransport` 连接 PersistentMcpBridge
|
||||
|
||||
协议桥接：
|
||||
```
|
||||
Agent 引擎 (stdio)
|
||||
↕
|
||||
qiming-mcp-stdio-proxy（单一进程）
|
||||
├── stdio 上游 → 子进程
|
||||
└── bridge 上游 → StreamableHTTPClientTransport → PersistentMcpBridge HTTP
|
||||
```
|
||||
|
||||
### 4. McpProxyManager — 配置分发
|
||||
|
||||
**文件**: `src/main/services/packages/mcp.ts`
|
||||
|
||||
`getAgentMcpConfig()` 构建**单一** mcp-proxy 配置，临时与持久化 server 均写入同一份 `mcpServers`：
|
||||
|
||||
```typescript
|
||||
getAgentMcpConfig() {
|
||||
const proxyServers = {};
|
||||
// 临时 server → { command, args, env }
|
||||
for (const [name, entry] of ephemeral) {
|
||||
proxyServers[name] = resolveServersConfig({ [name]: entry })[name];
|
||||
}
|
||||
// 持久化 server → { url: persistentMcpBridge.getBridgeUrl(name) }
|
||||
if (persistentMcpBridge.isRunning()) {
|
||||
for (const [name, entry] of persistent) {
|
||||
const url = persistentMcpBridge.getBridgeUrl(name);
|
||||
if (url) proxyServers[name] = { url };
|
||||
}
|
||||
}
|
||||
return {
|
||||
'mcp-proxy': {
|
||||
command: process.execPath,
|
||||
args: [proxyScript, '--config', JSON.stringify({ mcpServers: proxyServers })],
|
||||
env: { ELECTRON_RUN_AS_NODE: '1' },
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Agent 引擎收到的 MCP 配置（仅一个 key）：
|
||||
```json
|
||||
{
|
||||
"mcp-proxy": {
|
||||
"command": "/path/to/electron",
|
||||
"args": ["/path/to/qiming-mcp-stdio-proxy", "--config", "{\"mcpServers\":{\"filesystem\":{\"command\":\"npx\",\"args\":[\"...\"]},\"chrome-devtools\":{\"url\":\"http://127.0.0.1:PORT/mcp/chrome-devtools\"}}}"],
|
||||
"env": { "ELECTRON_RUN_AS_NODE": "1" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 生命周期管理
|
||||
|
||||
### 启动流程
|
||||
|
||||
```
|
||||
app.whenReady() → runStartupTasks()
|
||||
└── mcpProxyManager.start()
|
||||
├── 验证 qiming-mcp-stdio-proxy 已安装（缓存脚本路径）
|
||||
└── persistentMcpBridge.start(persistentServers)
|
||||
├── 为每个 persistent server 创建 StdioClientTransport + Client
|
||||
├── Client.connect() → spawn 子进程 → MCP initialize
|
||||
├── Client.listTools() → 缓存 tool 列表
|
||||
└── 启动 HTTP server（自动端口） + session 清理定时器
|
||||
```
|
||||
|
||||
### ACP Session 流程
|
||||
|
||||
```
|
||||
agentService.init() → getAgentMcpConfig()
|
||||
└── mcp-proxy: ACP 引擎 spawn 单一 qiming-mcp-stdio-proxy
|
||||
├── stdio 上游 → 临时 server 子进程
|
||||
└── bridge 上游 → HTTP 连接 PersistentMcpBridge（持久化 server）
|
||||
|
||||
Session 结束:
|
||||
└── qiming-mcp-stdio-proxy 进程退出
|
||||
├── 临时 server 子进程全部退出 ✓
|
||||
└── bridge HTTP 连接关闭，持久化 MCP server 子进程继续运行 ✓ (关键!)
|
||||
```
|
||||
|
||||
### 停止/退出流程
|
||||
|
||||
```
|
||||
app 退出 / services:stopAll
|
||||
└── mcpProxyManager.cleanup() / mcpProxyManager.stop()
|
||||
└── persistentMcpBridge.stop()
|
||||
├── 清理 session cleanup 定时器
|
||||
├── 关闭所有 HTTP session transport
|
||||
├── 关闭 HTTP server
|
||||
└── 逐个停止持久化 server:
|
||||
├── Client.close()
|
||||
├── transport.close() → 子进程终止
|
||||
└── 兜底: process.kill(pid, SIGTERM/SIGKILL)
|
||||
```
|
||||
|
||||
### 子进程自动重启
|
||||
|
||||
```
|
||||
子进程异常退出 → transport.onclose 触发
|
||||
└── scheduleRestart(5秒冷却)
|
||||
└── 清理旧 client/transport → spawnAndConnect()
|
||||
└── 新 StdioClientTransport + Client → listTools()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
### 默认配置
|
||||
|
||||
```typescript
|
||||
const DEFAULT_MCP_PROXY_CONFIG = {
|
||||
mcpServers: {
|
||||
'chrome-devtools': {
|
||||
command: 'chrome-devtools-mcp',
|
||||
args: [],
|
||||
persistent: true, // 持久化: 由 PersistentMcpBridge 管理
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 用户自定义 Server
|
||||
|
||||
通过 UI（MCPSettings 组件）添加的 server 默认为临时（ephemeral），走 qiming-mcp-stdio-proxy 聚合。
|
||||
|
||||
需要持久化的 server 需在配置中设置 `persistent: true`。
|
||||
|
||||
---
|
||||
|
||||
## 依赖
|
||||
|
||||
| 依赖 | 用途 | 位置 |
|
||||
|------|------|------|
|
||||
| `@modelcontextprotocol/sdk` | MCP Client/Server/Transport 实现 | `package.json` devDependencies |
|
||||
| `qiming-mcp-stdio-proxy` | 临时 + 持久化 聚合（stdio + bridge 入口） | 应用依赖 + `~/.qiming-agent/node_modules/` |
|
||||
|
||||
### TypeScript 兼容性
|
||||
|
||||
MCP SDK 使用 package.json `exports` 字段的子路径导出，但项目 `tsconfig.main.json` 的 `moduleResolution: "node"` 不支持。
|
||||
|
||||
解决方案：`src/shared/types/mcp-sdk.d.ts` 提供 ambient module 声明，为以下子路径提供类型：
|
||||
- `@modelcontextprotocol/sdk/client`
|
||||
- `@modelcontextprotocol/sdk/server`
|
||||
- `@modelcontextprotocol/sdk/client/stdio.js`
|
||||
- `@modelcontextprotocol/sdk/server/streamableHttp.js`
|
||||
- `@modelcontextprotocol/sdk/server/stdio.js`
|
||||
- `@modelcontextprotocol/sdk/client/streamableHttp.js`
|
||||
- `@modelcontextprotocol/sdk/types.js`
|
||||
|
||||
---
|
||||
|
||||
## 文件清单
|
||||
|
||||
| 文件 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/main/services/packages/persistentMcpBridge.ts` | 新建 | 核心 bridge 服务 |
|
||||
| `src/main/services/packages/mcp.ts` | 修改 | 统一 mcp-proxy 配置（stdio + bridge 合并进一份 config） |
|
||||
| `src/shared/types/mcp-sdk.d.ts` | 新建 | MCP SDK 子路径类型声明 |
|
||||
| `src/main/services/packages/mcp.test.ts` | 修改 | 新增持久化相关测试 |
|
||||
| `src/main/main.ts` | 小改 | cleanup 流程说明 |
|
||||
| `src/main/ipc/processHandlers.ts` | 小改 | stopAll/restartAll 说明 |
|
||||
| `package.json` | 修改 | SDK 依赖 + extraResources |
|
||||
|
||||
---
|
||||
|
||||
## 验证
|
||||
|
||||
1. `npm run build` → TypeScript 编译通过
|
||||
2. `npm run test` → 所有测试通过（含新增的 persistent bridge 测试用例）
|
||||
3. `npm run electron:dev` → 开发模式验证:
|
||||
- PersistentMcpBridge 启动 → chrome-devtools-mcp 成功 spawn → 28 tools 就绪
|
||||
- HTTP bridge 监听自动分配端口（如 57278）
|
||||
- ACP session 收到单一 `mcp-proxy` 配置（config 内含 stdio + bridge 条目）
|
||||
- qiming-mcp-stdio-proxy 内 bridge 连接 PersistentMcpBridge HTTP → tools 正常列出和调用
|
||||
4. 多 session 测试 → 同一 Chrome 实例跨 session 持续可用
|
||||
5. 应用退出 → 无残留进程
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-02-27*
|
||||
Reference in New Issue
Block a user