# 接入替换文档：qiming-mcp-stdio-proxy → agent-electron-client

将 `crates/agent-electron-client` 中旧的 `mcp-stdio-proxy`（bin: `mcp-proxy`，Rust 二进制）替换为新的 `qiming-mcp-stdio-proxy`（纯 TypeScript/Node.js）。

---

## 一、旧 mcp-proxy 完整能力梳理

通过 `mcp-proxy --help` 确认，旧 Rust 二进制（v0.1.54）支持以下子命令：

| 子命令 | 方向 | 用途 |
|--------|------|------|
| `proxy` | **stdio → Streamable HTTP/SSE** | 将本地 stdio MCP server 暴露为 HTTP 服务 |
| `convert` | **Streamable HTTP/SSE → stdio** | 将远程 HTTP MCP 服务转换为本地 stdio |
| `detect` | — | 自动检测远程服务协议类型 |
| `check` | — | 检查远程服务可用性 |
| `health` | — | 健康检查（MCP 握手级别） |

### `proxy` 子命令详情

```bash
mcp-proxy proxy --port <PORT> --host <HOST> --config '<mcpServers JSON>'
                [--protocol sse|stream]   # 默认 stream (Streamable HTTP)
                [--log-dir <DIR>]
                [--diagnostic]
```

- 启动 HTTP 服务器，聚合 `--config` 中定义的 stdio MCP servers
- 对外暴露 Streamable HTTP（默认）或 SSE 端点
- 支持 `--allow-tools` / `--deny-tools` 工具过滤

### `convert` 子命令详情

```bash
mcp-proxy convert <URL>
                  [--config '<mcpServers JSON>']  # 也支持 config 模式
                  [--auth "Bearer token"]
                  [--protocol sse|stream]
                  [--ping-interval <SEC>]
```

- 将远程 HTTP/SSE MCP 服务转为本地 stdio 接口
- Agent 引擎（claude-code / qimingcode）通过 stdio 消费

---

## 二、Tauri 客户端实际架构（参考基准）

Tauri 客户端使用的是 **stdio → Streamable HTTP → stdio** 双跳架构：

```
┌─ Tauri Main Process ─────────────────────────────────────────────┐
│                                                                   │
│  1. 启动 proxy 进程:                                              │
│     mcp-proxy proxy --port 18099 --host 127.0.0.1                │
│                     --config '{"mcpServers":{...}}'              │
│                     --protocol stream                             │
│                                                                   │
│  2. TCP 健康检查:                                                 │
│     wait_for_mcp_proxy_ready(18099, "127.0.0.1", timeout=15s)    │
│                                                                   │
│  3. 注入 Agent MCP 配置:                                          │
│     { "mcp-proxy": {                                              │
│         "command": "mcp-proxy",                                   │
│         "args": ["convert", "http://127.0.0.1:18099"]            │
│     }}                                                            │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

数据流:

Child MCP Servers (stdio × N)
    ↑ StdioClientTransport
    │
mcp-proxy proxy (Rust, 聚合 + Streamable HTTP 服务器)
    │ http://127.0.0.1:18099
    ↓
mcp-proxy convert http://127.0.0.1:18099 (Rust, HTTP → stdio)
    │ stdio
    ↓
Agent Engine (claude-code / qimingcode)
```

**Tauri 这样做的原因**：
- Rust 原生 `Command::new()` + `CREATE_NO_WINDOW` 避免 Windows 弹窗
- 进程组管理（Unix: setsid, Windows: JobObject）
- TCP 健康检查确认服务就绪

**存在的问题**：
- 需要端口管理（默认 18099，冲突时需要 kill 旧进程）
- 两层 mcp-proxy 进程（proxy + convert）
- Electron 客户端复用此架构时，Rust 二进制 + `.cmd` wrapper 导致 Windows 弹窗

---

## 三、Electron 客户端当前架构（有问题）

Electron 当前**试图复制** Tauri 架构，但有几个问题：

```
Electron Main Process
  │ spawnJsFile() → run-mcp-proxy.js → Rust binary
  │   mcp-proxy proxy --port 8080 --host 127.0.0.1 --config '...'
  ▼
mcp-proxy proxy (Rust binary, HTTP server)
  │ http://127.0.0.1:8080
  ▼
Agent Engine
  │ mcpServers: { "mcp-proxy": { command: "mcp-proxy", args: ["convert", "http://..."] } }
  ▼
mcp-proxy convert (Rust binary, HTTP → stdio)
```

**问题清单**：
1. Windows 上 Rust 二进制 `.cmd` wrapper 弹出控制台窗口
2. `spawnJsFile()` spawn 的是 `run-mcp-proxy.js`（Node.js wrapper），它下载并执行 Rust binary
3. 端口管理复杂（分配、占用检测、kill 占用进程）
4. 单进程限制（Electron 代码中强制过滤为单服务）
5. 两层进程开销

---

## 四、新架构设计

### 方案：纯 stdio 直通（消除 HTTP 中间层）

```
Agent Engine (claude-code / qimingcode)
  │ spawns as MCP server (stdio)
  ▼
qiming-mcp-stdio-proxy --config '{"mcpServers":{...}}'
  │ StdioServerTransport (上游) + StdioClientTransport × N (下游)
  ▼
Child MCP Servers (stdio × N)
```

**核心变化**：
- **消除 HTTP 中间层**：不再需要 `proxy` → HTTP → `convert` 的双跳
- **Agent 直接 spawn proxy**：proxy 是 Agent 引擎的一个 stdio MCP server
- **Electron 不管理 proxy 进程**：生命周期随 Agent 引擎
- **纯 Node.js**：无 Rust 二进制，无 `.cmd` wrapper，Windows 无弹窗

### 架构对比

| | Tauri（旧） | Electron 旧 | Electron 新 |
|---|---|---|---|
| **聚合层** | `mcp-proxy proxy` (Rust, HTTP) | 同左 | `qiming-mcp-stdio-proxy` (Node.js, stdio) |
| **桥接层** | `mcp-proxy convert` (Rust, HTTP→stdio) | 同左 | **无**（直接 stdio） |
| **进程数** | 2 (proxy + convert) | 2 | 1 |
| **通信协议** | stdio → HTTP → stdio | 同左 | stdio → stdio |
| **端口** | 需要 (18099) | 需要 (8080) | **无** |
| **Windows 弹窗** | 无（Rust CREATE_NO_WINDOW） | **有**（.cmd wrapper） | **无**（Node.js） |
| **多服务** | 支持 | 强制单服务 | 支持 N 个 |
| **生命周期** | Tauri 管理 | Electron 管理 | Agent 引擎管理 |

### 为什么可以省掉 HTTP 层

旧架构需要 HTTP 中间层是因为：
- Tauri 的 Rust 进程管理需要一个长驻 HTTP 服务作为控制面
- Agent 引擎通过 `mcp-proxy convert <url>` 以 stdio 方式接入

新架构中：
- `qiming-mcp-stdio-proxy` 本身就是一个 stdio MCP server
- Agent 引擎直接 spawn 它，无需中转
- 配置通过 `--config` 参数传入，无需运行时控制面

---

## 五、配置格式兼容性

新旧 proxy 使用**完全相同**的 `mcpServers` JSON 配置格式：

```typescript
interface McpServersConfig {
  mcpServers: Record<string, {
    command: string;
    args: string[];
    env?: Record<string, string>;
  }>;
}
```

- SQLite 中持久化的 `mcp_proxy_config` 键值可直接复用
- `resolveServersConfig()` 的 uvx 解析和 env 注入逻辑不变

---

## 六、需要修改的文件清单

| # | 文件 | 改动量 | 说明 |
|---|------|--------|------|
| 1 | `src/main/services/packages/mcp.ts` | **大改** | 核心：移除 HTTP 进程管理，改为配置提供者 |
| 2 | `src/main/services/system/dependencies.ts` | 小改 | 更新包名、bin 名、最低版本 |
| 3 | `src/main/ipc/mcpHandlers.ts` | 中改 | 简化 start/stop/restart 为 no-op |
| 4 | `src/main/ipc/processHandlers.ts` | 中改 | restartAll/stopAll 移除 MCP 进程管理 |
| 5 | `src/main/main.ts` | 小改 | cleanup 中移除 mcpProxyManager.cleanup() |
| 6 | `src/renderer/App.tsx` | 中改 | 移除 mcpProxy 进程启动/轮询 |
| 7 | `src/renderer/components/ClientPage.tsx` | 中改 | 移除 mcpProxy 启停逻辑 |
| 8 | `src/renderer/components/MCPSettings.tsx` | 小改 | 移除端口配置 UI |
| 9 | `src/main/services/engines/unifiedAgent.ts` | 无改 | syncMcpConfigToProxyAndReload 已简化 |
| 10 | `src/main/ipc/agentHandlers.ts` | 无改 | getAgentMcpConfig() 返回值已变 |

---

## 七、逐文件改动详解

### 7.1 `src/main/services/packages/mcp.ts` — 核心重构

旧文件约 692 行，重构后预计约 300 行。

#### 7.1.1 删除的代码（约 400 行）

| 删除项 | 原因 |
|--------|------|
| `import { spawn, ChildProcess, exec }` | 不再 spawn 进程 |
| `import * as net` | 不再管理端口 |
| `import { DEFAULT_MCP_PROXY_PORT, DEFAULT_MCP_PROXY_HOST }` | 不再使用端口/主机 |
| `isPortInUse()` 函数 | 不再管理端口 |
| `killProcessOnPort()` 函数 | 不再管理端口 |
| `McpProxyManager.process` / `.port` / `.host` / `.startPromise` 字段 | 无进程实例 |
| `McpProxyManager.start()` 方法体（进程 spawn 逻辑） | 整体重写为验证 |
| `McpProxyManager.stop()` / `.restart()` 方法体 | 简化为 no-op |
| `McpProxyManager.isProcessRunning()` | 无进程 |
| `McpProxyManager.getPort()` / `.setPort()` | 不再使用端口 |
| `McpProxyManager.cleanup()` 方法体 | 简化为 no-op |
| `McpProxyStatus.pid` / `.port` / `.host` 字段 | 不再使用 |
| `McpProxyStartConfig` 接口 | 不再使用 |
| `extractRealServersFromMcpServers()` 中解析 `mcp-proxy convert` 桥接项 | 无桥接模式 |

#### 7.1.2 保留的代码（约 200 行）

| 保留项 | 说明 |
|--------|------|
| `getUvBinDir()` / `resolveUvCommand()` | 仍需为 child server 解析 uvx |
| `resolveServersConfig()` | 仍需注入 env + 解析 uvx |
| `DEFAULT_MCP_PROXY_CONFIG` | 默认配置不变 |
| `McpServerEntry` / `McpServersConfig` 接口 | 配置格式不变 |
| `McpProxyManager.config` + get/set/add/remove | 配置管理不变 |
| `syncMcpConfigToProxyAndReload()` | 保留但简化（不 restart） |

#### 7.1.3 `McpProxyManager` 类重写

```typescript
class McpProxyManager {
  private config: McpServersConfig = JSON.parse(JSON.stringify(DEFAULT_MCP_PROXY_CONFIG));

  /**
   * 获取 qiming-mcp-stdio-proxy 脚本路径
   */
  private getProxyScriptPath(): string | null {
    const dirs = getAppPaths();
    const packageDir = path.join(dirs.nodeModules, 'qiming-mcp-stdio-proxy');
    if (!fs.existsSync(packageDir)) return null;
    return resolveNpmPackageEntry(packageDir, 'qiming-mcp-stdio-proxy');
  }

  /**
   * start() → 仅验证 binary 可用性（不再启动进程）
   */
  async start(): Promise<{ success: boolean; error?: string }> {
    if (!isInstalledLocally('qiming-mcp-stdio-proxy')) {
      return { success: false, error: 'qiming-mcp-stdio-proxy 未安装' };
    }
    const scriptPath = this.getProxyScriptPath();
    if (!scriptPath) {
      return { success: false, error: 'qiming-mcp-stdio-proxy 入口文件未找到' };
    }
    log.info('[McpProxy] qiming-mcp-stdio-proxy 就绪:', scriptPath);
    return { success: true };
  }

  async stop(): Promise<{ success: boolean }> { return { success: true }; }
  async restart(): Promise<{ success: boolean; error?: string }> { return this.start(); }

  getStatus(): McpProxyStatus {
    const serverNames = Object.keys(this.config.mcpServers || {});
    return {
      running: !!this.getProxyScriptPath(),
      serverCount: serverNames.length,
      serverNames,
    };
  }

  /**
   * getAgentMcpConfig() — 核心变更
   *
   * 旧: 返回 { "mcp-proxy": { command: "mcp-proxy", args: ["convert", "http://127.0.0.1:8080"] } }
   * 新: 返回 { "mcp-proxy": { command: "node", args: ["proxy.js", "--config", "..."] } }
   *
   * Agent 引擎直接 spawn qiming-mcp-stdio-proxy 作为 stdio MCP server，
   * 不再经过 HTTP 中间层。
   */
  getAgentMcpConfig(): Record<string, {
    command: string; args: string[]; env?: Record<string, string>;
  }> | null {
    const servers = this.config.mcpServers;
    if (!servers || Object.keys(servers).length === 0) return null;

    const scriptPath = this.getProxyScriptPath();
    if (!scriptPath) {
      // fallback: 直接返回解析后的各 server stdio 配置（无聚合）
      return resolveServersConfig(servers);
    }

    // 解析配置：uvx → 应用内路径，注入 env
    const resolvedConfig: McpServersConfig = {
      mcpServers: resolveServersConfig(servers),
    };
    const configJson = JSON.stringify(resolvedConfig);

    // Windows: 用 Electron 的 Node.js 执行（避免 .cmd 弹窗）
    // macOS/Linux: 用系统 node
    if (isWindows()) {
      return {
        'mcp-proxy': {
          command: process.execPath,
          args: [scriptPath, '--config', configJson],
          env: { ELECTRON_RUN_AS_NODE: '1' },
        },
      };
    }

    return {
      'mcp-proxy': {
        command: 'node',
        args: [scriptPath, '--config', configJson],
      },
    };
  }

  cleanup(): void { /* no-op */ }

  // getConfig / setConfig / addServer / removeServer — 保持不变
}
```

#### 7.1.4 `McpProxyStatus` 接口简化

```typescript
// 旧
export interface McpProxyStatus {
  running: boolean;
  pid?: number;       // ← 删除
  port?: number;      // ← 删除
  host?: string;      // ← 删除
  serverCount?: number;
  serverNames?: string[];
}

// 新
export interface McpProxyStatus {
  running: boolean;    // 语义变化："binary 可用" 而非 "进程在运行"
  serverCount?: number;
  serverNames?: string[];
}
```

#### 7.1.5 `syncMcpConfigToProxyAndReload()` 简化

```typescript
export async function syncMcpConfigToProxyAndReload(
  mcpServers: Record<string, { command: string; args?: string[]; env?: Record<string, string> }>,
): Promise<void> {
  if (!mcpServers || Object.keys(mcpServers).length === 0) return;

  // 提取真实服务（过滤旧桥接项 command==='mcp-proxy'）
  const realOnly: Record<string, { command: string; args: string[]; env?: Record<string, string> }> = {};
  for (const [name, entry] of Object.entries(mcpServers)) {
    if (!entry || entry.command === 'mcp-proxy') continue;
    realOnly[name] = { command: entry.command, args: Array.isArray(entry.args) ? entry.args : [], env: entry.env };
  }
  if (Object.keys(realOnly).length === 0) return;

  log.info('[McpProxy] 同步 MCP 配置:', Object.keys(realOnly).join(', '));
  mcpProxyManager.setConfig({ mcpServers: realOnly });

  // 持久化到 SQLite
  try {
    const { getDb } = await import('../../db');
    const db = getDb();
    db?.prepare('INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)')
      .run('mcp_proxy_config', JSON.stringify({ mcpServers: realOnly }));
  } catch (e) {
    log.warn('[McpProxy] 持久化 MCP 配置失败:', e);
  }

  // 不再需要 restart — 无后台进程
  // Agent 下次 init 时 getAgentMcpConfig() 会使用新配置
}
```

---

### 7.2 `src/main/services/system/dependencies.ts`

**改动 1**：`SETUP_REQUIRED_DEPENDENCIES` 中更新 MCP 条目

```typescript
// 旧
{
  name: "mcp-stdio-proxy",
  displayName: "MCP 服务",
  type: "npm-local",
  description: "MCP 协议转换工具（应用内安装）",
  required: true,
  minVersion: "0.1.48",
  binName: "mcp-proxy",
},

// 新
{
  name: "qiming-mcp-stdio-proxy",
  displayName: "MCP 服务",
  type: "npm-local",
  description: "MCP 协议聚合代理（应用内安装）",
  required: true,
  minVersion: "1.0.0",
  binName: "qiming-mcp-stdio-proxy",
},
```

**改动 2**：`checkAllDependencies()` 中更新 case

```diff
- case 'mcp-stdio-proxy':
+ case 'qiming-mcp-stdio-proxy':
```

---

### 7.3 `src/main/ipc/mcpHandlers.ts`

- `mcp:start` → 移除 options 参数（port/host/configJson），调用 `mcpProxyManager.start()`（仅验证）
- `mcp:stop` → 调用 `mcpProxyManager.stop()`（no-op）
- `mcp:restart` → 调用 `mcpProxyManager.restart()`（仅验证）
- `mcp:getPort` / `mcp:setPort` → 保留为 no-op 向后兼容
- `mcp:getConfig` / `mcp:setConfig` → 不变

---

### 7.4 `src/main/ipc/processHandlers.ts`

`services:restartAll`:
- 移除 `mcpProxyManager.stop()` 调用
- `mcpProxyManager.start()` 保留但语义变为"验证可用性"

`services:stopAll`:
- MCP Proxy 部分改为 `results.mcpProxy = { success: true }` (no-op)

---

### 7.5 `src/main/main.ts`

`cleanupAllProcesses()` 中移除或注释 `mcpProxyManager.cleanup()`（已 no-op）。

---

### 7.6 `src/renderer/App.tsx` + `ClientPage.tsx`

`mcpProxy` 在 serviceKeys/startOrder 中**保留**，因为 `mcp.start()` 已变为轻量验证。UI 展示的 `running` 状态语义从"进程运行中"变为"binary 可用"。

可选移除 `pid` 字段的展示。

---

### 7.7 `src/renderer/components/MCPSettings.tsx`

- 移除端口配置 UI（不再使用端口）
- 启动/停止按钮可保留（已为 no-op）或改为"检测可用性"
- MCP server 列表编辑功能保留不变

---

## 八、关键行为变更对照表

| 行为 | 旧（mcp-proxy Rust） | 新（qiming-mcp-stdio-proxy TS） |
|------|----------------------|-------------------------------|
| **binary 类型** | Rust 编译二进制 | Node.js 脚本 |
| **通信链路** | stdio → HTTP (Streamable) → stdio | stdio → stdio |
| **进程数** | 2 (proxy + convert) | 1 |
| **端口** | 需要（默认 8080/18099） | **无** |
| **进程管理** | Electron spawn + 监控 + cleanup | Agent 引擎自动管理 |
| **多服务聚合** | 支持（但 Electron 强制单服务） | 支持 N 个 |
| **Agent 注入** | `mcp-proxy convert http://...` | `node proxy.js --config '...'` |
| **Windows 弹窗** | 有（.cmd wrapper） | **无**（Node.js + ELECTRON_RUN_AS_NODE） |
| **配置热更新** | restart proxy HTTP 进程 | 更新配置，Agent 下次 init 使用 |
| **健康检查** | TCP 连接测试 | 不需要（无 HTTP 服务） |
| **远程 MCP 服务** | 支持（convert URL → stdio） | 不支持（仅聚合本地 stdio servers） |

### 注意：远程 MCP 服务能力

旧 `mcp-proxy` 的 `convert` 子命令支持将远程 SSE/Streamable HTTP MCP 服务转为 stdio。新的 `qiming-mcp-stdio-proxy` 仅支持聚合本地 stdio servers。

如果需要访问远程 MCP 服务，有两个选项：
1. **保留旧 `mcp-proxy` 作为 convert 工具**：远程服务配置为 `{ command: "mcp-proxy", args: ["convert", "https://..."] }`，作为 `qiming-mcp-stdio-proxy` 的一个 child server
2. **后续为 qiming-mcp-stdio-proxy 添加 HTTP client transport**

---

## 九、实施步骤

### Phase 1: 发布 npm 包

```bash
cd crates/qiming-mcp-stdio-proxy
npm run build
npm publish
```

### Phase 2: 修改 Electron 客户端

按以下顺序修改（每步可独立提交）：

1. `dependencies.ts` — 更新包名/bin 名/版本
2. `mcp.ts` — 核心重构
3. `mcpHandlers.ts` — 简化 IPC
4. `processHandlers.ts` — 移除 MCP 进程管理
5. `main.ts` — 移除 cleanup
6. `App.tsx` + `ClientPage.tsx` — UI 适配
7. `MCPSettings.tsx` — 移除端口配置

### Phase 3: 测试验证

- [ ] 初始化向导自动安装 `qiming-mcp-stdio-proxy`
- [ ] `getAgentMcpConfig()` 返回 `{ command: "node", args: ["proxy.js", "--config", "..."] }`
- [ ] Agent 通过 proxy 聚合多个 MCP server 的 tools
- [ ] Windows 上无控制台弹窗
- [ ] macOS/Linux 上功能正常
- [ ] MCP 设置页可编辑 server 列表
- [ ] 配置修改后 Agent 重新 init 生效
- [ ] 远程 MCP 服务可通过 `mcp-proxy convert` 作为 child server 接入

---

## 十、回滚方案

若需回滚到旧 `mcp-proxy`：

1. `dependencies.ts` 改回 `name: "mcp-stdio-proxy"`, `binName: "mcp-proxy"`
2. `mcp.ts` 恢复进程管理逻辑
3. 重新安装 `npm install mcp-stdio-proxy`

配置格式完全兼容，SQLite 数据无需迁移。

---

## 十一、共享类型更新

如果 `@shared/types/electron.ts` 导出了 `McpProxyStatus`，需同步移除 `pid` / `port` / `host` 字段：

```typescript
export interface McpProxyStatus {
  running: boolean;
  serverCount?: number;
  serverNames?: string[];
}
```

同时删除 `McpProxyStartConfig` 接口。