zen-gitsync 2.17.46 → 2.17.48

package/src/cli/ai/mcp.js

@@ -12,19 +12,32 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
-// g ai 的 MCP(Model Context Protocol)客户端 — stdio 传输实现。
+// g ai 的 MCP(Model Context Protocol)客户端 — 支持 stdio 与 Streamable HTTP 两种传输。
 //
 // 为什么自己实现而不是装 SDK:
-//   本包 dependencies 一直保持精简,而 stdio 这一层的协议面很小
-//   (newline-delimited JSON-RPC + initialize / tools/list / tools/call 三个方法),
-//   自己写≈200 行,换取零依赖 + 完全可控的超时与降级行为。
+//   本包 dependencies 一直保持精简,而这两种传输的协议面都很小
+//   (JSON-RPC + initialize / tools/list / tools/call 三个方法),自己写换取
+//   零依赖 + 完全可控的超时与降级行为。
 //
 // 配置来源(两级,项目级覆盖全局同名 server):
 //   1) ~/.zen-gitsync/ai/mcp.json                    「g ai 智能体」全局安装(对所有项目生效)
 //   2) <cwd>/.zen-gitsync/ai/mcp.json                项目级安装
 //   形状沿用生态通行的 mcpServers。项目级路径常量与广场安装端共用 src/paths.js 那一份;
 //   项目级**不再读** <cwd>/.mcp.json(那是 Claude Code 一系的约定路径,2026-09-30 迁出)。
-//   { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@..."], "env": {} } } }
+//
+// 两种条目形状,按有没有 command 自动区分(同一条目同时有两者时以 command 为准):
+//   { "github": { "command": "npx", "args": ["-y", "@..."], "env": {} } }
+//   { "todo":   { "type": "http", "url": "https://.../api/mcp", "headers": { "Authorization": "Bearer ..." } } }
+//
+// HTTP 侧只说 Streamable HTTP(2025-03-26 起规范里的那套):
+//   POST JSON-RPC → 200 application/json 或 text/event-stream(取 id 匹配的那一帧);
+//   响应头里的 Mcp-Session-Id 会被记住并在后续请求回传;关闭时尽力 DELETE 结束会话。
+//   老式 "HTTP+SSE"(2024-11-05 的 GET /sse + POST endpoint)不在此列 —— 那种服务端
+//   自己也在陆续迁走,真需要时用 mcp-remote 桥成 stdio 更省事。
+//
+// ⚠️ HTTPS 的证书链:fetch 走 Node 内置根证书,不读 Windows/macOS 证书库。
+//   站点只发叶证书、中间证书没带全时,Node 会报 unable to verify the first certificate,
+//   而浏览器/curl 都正常。这里**不擅自关校验**(那是安全红线),只在报错里把可操作的做法写清楚。
 //
 // ⚠️ Windows 上 spawn 的两个坑(已实测,不要"优化"掉):
 //   1) 带空格的参数在 shell:true 下会被 cmd 拆碎 ——
@@ -46,6 +59,11 @@ const IS_WIN = process.platform === 'win32';
 // 工具名前缀。OpenAI function calling 允许 [A-Za-z0-9_-],用双下划线分段。
 export const MCP_TOOL_PREFIX = 'mcp__';
 
+// 握手时声明的协议版本。stdio 沿用旧值不动(现有 server 都是照这个档位对接的);
+// HTTP 侧必须报 Streamable HTTP 那一版,否则部分服务端会按老式 HTTP+SSE 处理。
+const STDIO_PROTOCOL_VERSION = '2024-11-05';
+const HTTP_PROTOCOL_VERSION = '2025-03-26';
+
 // 初始化握手超时。
 // ⚠️ 别按"握手只需要几百毫秒"来定这个值:command 是 npx -y 时,**首次**会现场下载
 // 整个 server 包及其依赖。国内直连 registry(无代理)实测这一步能轻松吃掉 30s+,
@@ -144,6 +162,9 @@ export function buildSpawnSpec(command, args, env) {
 /**
  * 读取一个 mcp.json 形状的配置文件,返回 mcpServers 对象。
  * 文件不存在 / 坏了都只当"没有配置",不抛错 —— 一个坏文件不该让 g ai 起不来。
+ *
+ * 保留条件:有 command(stdio)或有 http(s) 的 url(Streamable HTTP)。
+ * 两者都没有的条目直接丢掉 —— 免得后面按 undefined 去 spawn 炸得莫名其妙。
  */
 async function readServersFile(file) {
   const raw = await fs.readFile(file, 'utf8').catch(() => '');
@@ -155,7 +176,9 @@ async function readServersFile(file) {
     const out = {};
     for (const [id, cfg] of Object.entries(servers)) {
       if (!cfg || typeof cfg !== 'object') continue;
-      if (!cfg.command || typeof cfg.command !== 'string') continue;
+      const hasCommand = typeof cfg.command === 'string' && cfg.command.trim() !== '';
+      const hasUrl = typeof cfg.url === 'string' && /^https?:\/\//i.test(cfg.url.trim());
+      if (!hasCommand && !hasUrl) continue;
       out[id] = cfg;
     }
     return out;
@@ -187,11 +210,55 @@ export async function loadMcpServers({ cwd, globalFile = AI_MCP_FILE, projectFil
 // 单个 server 的连接
 // ──────────────────────────────────────────────
 
+/**
+ * 这个条目该走哪种传输:有 command 就是 stdio(优先级高于 url),
+ * 否则 url 是 http(s) 时走 Streamable HTTP。
+ *
+ * @param {object} config
+ * @returns {'stdio'|'http'|null} null = 两边都不像,调用方应跳过
+ */
+export function serverTransport(config) {
+  if (!config || typeof config !== 'object') return null;
+  if (typeof config.command === 'string' && config.command.trim() !== '') return 'stdio';
+  if (typeof config.url === 'string' && /^https?:\/\//i.test(config.url.trim())) return 'http';
+  return null;
+}
+
 // 工具名会被拼进 OpenAI 的 function name,必须收敛到安全字符集
 function sanitizeToolName(name) {
   return String(name || '').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 48);
 }
 
+/**
+ * 两种传输共用的握手:initialize → notifications/initialized → tools/list。
+ * 请求/通知都通过参数注入,stdio 与 HTTP 各交各的实现。
+ *
+ * @param {{ id: string, protocolVersion: string,
+ *           request: (method: string, params: object, timeoutMs: number) => Promise<any>,
+ *           notify: (method: string, params: object) => any }} io
+ * @returns {Promise<Array<object>>} 归一化后的工具定义
+ */
+async function handshake({ id, protocolVersion, request, notify }) {
+  await request('initialize', {
+    protocolVersion,
+    capabilities: {},
+    clientInfo: { name: 'zen-gitsync-g-ai', version: '1.0.0' },
+  }, INIT_TIMEOUT_MS);
+  await notify('notifications/initialized', {});
+
+  const listed = await request('tools/list', {}, INIT_TIMEOUT_MS);
+  return (Array.isArray(listed?.tools) ? listed.tools : [])
+    .filter(tool => tool && typeof tool.name === 'string')
+    .map(tool => ({
+      serverId: id,
+      name: tool.name,
+      description: tool.description || '',
+      inputSchema: tool.inputSchema && typeof tool.inputSchema === 'object'
+        ? tool.inputSchema
+        : { type: 'object', properties: {} },
+    }));
+}
+
 class McpConnection {
   /**
    * @param {string} id - server 标识(配置里的键名)
@@ -216,6 +283,11 @@ class McpConnection {
     return sanitizeToolName(this.id);
   }
 
+  /** 传输类型。诊断(/mcp)与 UI 展示用,连接本身不依赖它。 */
+  get transport() {
+    return 'stdio';
+  }
+
   /**
    * 启动子进程并完成 initialize + tools/list 握手。
    * 任何失败都写进 this.error 并返回 false,由调用方决定是否提示用户。
@@ -246,24 +318,12 @@ class McpConnection {
       this.spawnFailed = spawnFailed;
       spawnFailed.catch(() => {});
 
-      await this.#request('initialize', {
-        protocolVersion: '2024-11-05',
-        capabilities: {},
-        clientInfo: { name: 'zen-gitsync-g-ai', version: '1.0.0' },
-      }, INIT_TIMEOUT_MS);
-      this.#notify('notifications/initialized', {});
-
-      const listed = await this.#request('tools/list', {}, INIT_TIMEOUT_MS);
-      this.tools = (Array.isArray(listed?.tools) ? listed.tools : [])
-        .filter(tool => tool && typeof tool.name === 'string')
-        .map(tool => ({
-          serverId: this.id,
-          name: tool.name,
-          description: tool.description || '',
-          inputSchema: tool.inputSchema && typeof tool.inputSchema === 'object'
-            ? tool.inputSchema
-            : { type: 'object', properties: {} },
-        }));
+      this.tools = await handshake({
+        id: this.id,
+        protocolVersion: STDIO_PROTOCOL_VERSION,
+        request: (method, params, timeoutMs) => this.#request(method, params, timeoutMs),
+        notify: (method, params) => this.#notify(method, params),
+      });
       return true;
     } catch (err) {
       this.error = err.message;
@@ -360,6 +420,237 @@ class McpConnection {
   }
 }
 
+// ──────────────────────────────────────────────
+// Streamable HTTP 传输
+// ──────────────────────────────────────────────
+
+// Node 内置根证书不认站点证书链时的错误码 —— 单独识别出来,好把"该怎么修"写进提示
+const TLS_ERROR_CODES = new Set([
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'CERT_HAS_EXPIRED',
+  'ERR_TLS_CERT_ALTNAME_INVALID',
+]);
+
+function shortText(text, max) {
+  const clean = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}
+
+/**
+ * 把 fetch 的失败翻译成用户能照着做的中文。
+ * 证书链那条是本项目实测踩过的坑:服务端只发叶证书时,浏览器和 curl 都正常,
+ * 唯独 Node 报 unable to verify the first certificate —— 只说 "fetch failed" 等于没说。
+ */
+function describeHttpError(err, id) {
+  const message = err?.message || String(err);
+  // 已经翻译过的(#send 里翻过一次)不要二次加工成"连接 x 失败: 连接 x 失败: ..."
+  if (message.startsWith(`连接 "${id}"`)) return message;
+
+  const cause = err?.cause;
+  const code = cause?.code || '';
+  if (TLS_ERROR_CODES.has(code)) {
+    return `连接 "${id}" 失败:服务器证书链不被 Node 内置根证书信任(${code})。`
+      + '可任选一种办法:① 启动 g ai 前设 NODE_EXTRA_CA_CERTS=<站点 CA 文件路径>;'
+      + '② Node ≥ 22.15 时用 NODE_OPTIONS=--use-system-ca 改走系统证书库;'
+      + '③ 让服务端补齐中间证书。';
+  }
+  if (message === 'fetch failed' && (code || cause?.message)) {
+    // 优先用错误码:undici 的 cause.message 往往还是那句 "fetch failed",没有信息量
+    const detail = code || cause.message;
+    return `连接 "${id}" 失败: ${message} (${detail})`;
+  }
+  return `连接 "${id}" 失败: ${message}`;
+}
+
+/** SSE 帧 → JSON-RPC 消息。只认 data: 行,event: / id: / 注释行一律忽略。 */
+function parseSseFrame(frame) {
+  const data = frame.split(/\r?\n/)
+    .filter(line => line.startsWith('data:'))
+    .map(line => line.slice(5).trimStart())
+    .join('\n');
+  if (!data.trim()) return null;
+  try { return JSON.parse(data) } catch { return null }
+}
+
+/**
+ * 一个远程 MCP 服务(Streamable HTTP)的连接。
+ * 对外接口与 stdio 版完全一致(start / tools / callTool / close / error),
+ * 上层 McpManager 不需要知道下面是怎么连的。
+ */
+export class HttpConnection {
+  /**
+   * @param {string} id - server 标识(配置里的键名)
+   * @param {object} config - { url, headers?, disabled? }
+   * @param {string} cwd - 只是保持与 stdio 版的构造签名一致(HTTP 没有子进程)
+   */
+  constructor(id, config, cwd) {
+    this.id = id;
+    this.config = config;
+    this.cwd = cwd || process.cwd();
+    this.tools = [];
+    this.error = null;
+    // 与 stdio 版同形状:那边把子进程 stderr 留在这里,HTTP 没有对应物
+    this.stderr = '';
+    this.closed = false;
+    this.sessionId = '';
+    this.nextId = 1;
+  }
+
+  get safeId() { return sanitizeToolName(this.id) }
+
+  get transport() { return 'http' }
+
+  get endpoint() { return String(this.config.url || '').trim() }
+
+  /**
+   * 握手(initialize → notifications/initialized → tools/list)。
+   * 失败写进 this.error 并返回 false,由 McpManager 汇总,不影响其他 server。
+   */
+  async start() {
+    try {
+      if (!/^https?:\/\//i.test(this.endpoint)) {
+        throw new Error(`url 不合法: ${this.endpoint || '(空)'}`);
+      }
+      this.tools = await handshake({
+        id: this.id,
+        protocolVersion: HTTP_PROTOCOL_VERSION,
+        request: (method, params, timeoutMs) => this.#request(method, params, timeoutMs),
+        // 通知失败不拖垮握手(与 stdio 版一个态度),只在后台记账
+        notify: (method, params) => { this.#notify(method, params).catch(() => {}) },
+      });
+      return true;
+    } catch (err) {
+      this.error = describeHttpError(err, this.id);
+      this.closed = true;
+      return false;
+    }
+  }
+
+  #headers() {
+    const headers = {
+      'Content-Type': 'application/json',
+      // 少写 text/event-stream 会被规范型实现判 406,这是 Streamable HTTP 的硬要求
+      'Accept': 'application/json, text/event-stream',
+    };
+    for (const [key, value] of Object.entries(this.config.headers || {})) {
+      if (!key || value === undefined || value === null) continue;
+      headers[key] = String(value);
+    }
+    if (this.sessionId) headers['Mcp-Session-Id'] = this.sessionId;
+    return headers;
+  }
+
+  /** 发一条 JSON-RPC,返回 result(通知类无响应体时是 null);失败抛已翻译过的 Error。 */
+  async #send(payload, timeoutMs) {
+    if (this.closed) throw new Error('MCP 连接已关闭');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      let response;
+      try {
+        response = await fetch(this.endpoint, {
+          method: 'POST',
+          headers: this.#headers(),
+          body: JSON.stringify(payload),
+          signal: controller.signal,
+        });
+      } catch (err) {
+        const failure = err?.name === 'AbortError'
+          ? new Error(`请求超时(${Math.round(timeoutMs / 1000)}s)`)
+          : err;
+        throw new Error(describeHttpError(failure, this.id));
+      }
+
+      const sessionId = response.headers.get('mcp-session-id');
+      if (sessionId) this.sessionId = sessionId;
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`HTTP ${response.status}${body ? `: ${shortText(body, 300)}` : ''}`);
+      }
+
+      const contentType = String(response.headers.get('content-type') || '');
+      if (contentType.includes('text/event-stream')) {
+        return await this.#readSseResult(response, payload.id);
+      }
+
+      const text = await response.text();
+      if (!text.trim()) return null; // 202 Accepted:通知类请求没有响应体
+      let message;
+      try { message = JSON.parse(text) } catch {
+        throw new Error(`响应不是合法 JSON: ${shortText(text, 200)}`);
+      }
+      if (message?.error) throw new Error(message.error.message || `MCP error ${message.error.code}`);
+      return message?.result ?? null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * 读 SSE 响应,取 id 匹配的那一帧。
+   *
+   * 用流式 reader 而不是 await response.text():服务端完全可以在返回响应后继续推通知、
+   * 把流一直挂着,等整条流读完就会一路挂到超时。拿到目标帧立刻 cancel。
+   */
+  async #readSseResult(response, wantedId) {
+    const reader = response.body?.getReader?.();
+    if (!reader) return null;
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let found = null;
+    try {
+      while (!found) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let index;
+        while ((index = buffer.search(/\r?\n\r?\n/)) >= 0) {
+          const frame = buffer.slice(0, index);
+          buffer = buffer.slice(index).replace(/^\r?\n\r?\n/, '');
+          const message = parseSseFrame(frame);
+          if (!message) continue;
+          // 服务器主动推的通知(没有 id)直接忽略
+          if (wantedId === undefined || message.id === wantedId) { found = message; break }
+        }
+      }
+    } finally {
+      reader.cancel().catch(() => {});
+    }
+    if (!found) return null;
+    if (found.error) throw new Error(found.error.message || `MCP error ${found.error.code}`);
+    return found.result ?? null;
+  }
+
+  #request(method, params, timeoutMs) {
+    const id = this.nextId++;
+    return this.#send({ jsonrpc: '2.0', id, method, params }, timeoutMs);
+  }
+
+  #notify(method, params) {
+    return this.#send({ jsonrpc: '2.0', method, params }, INIT_TIMEOUT_MS);
+  }
+
+  /** 调用一个工具。口径与 stdio 版一致:content 数组拍平成字符串回喂给模型。 */
+  async callTool(name, args) {
+    const result = await this.#request('tools/call', { name, arguments: args || {} }, CALL_TIMEOUT_MS);
+    return flattenToolResult(result);
+  }
+
+  async close() {
+    this.closed = true;
+    const url = this.endpoint;
+    if (!url || !this.sessionId) return;
+    // 规范里结束会话是 DELETE(带 session 头),不是所有服务端都实现 —— 尽力而为
+    try {
+      await fetch(url, { method: 'DELETE', headers: this.#headers(), signal: AbortSignal.timeout(5000) });
+    } catch { /* noop */ }
+  }
+}
+
 // MCP tools/call 返回 { content: [{type:'text',text} | {type:'image',...} | {type:'resource',...}], isError? }
 function flattenToolResult(result) {
   const parts = Array.isArray(result?.content) ? result.content : [];
@@ -420,7 +711,10 @@ export class McpManager {
     const enabled = Object.entries(resolved).filter(([, cfg]) => !cfg.disabled);
 
     const settled = await Promise.all(enabled.map(async ([id, cfg]) => {
-      const connection = new McpConnection(id, cfg, cwd || process.cwd());
+      // 有 command → 本地子进程;只有 url → 远程 Streamable HTTP(serverTransport 已判过一遍)
+      const connection = serverTransport(cfg) === 'http'
+        ? new HttpConnection(id, cfg, cwd || process.cwd())
+        : new McpConnection(id, cfg, cwd || process.cwd());
       const ok = await connection.start();
       if (!ok && onWarn) onWarn(`MCP "${id}" 连接失败: ${connection.error}`);
       return connection;
@@ -471,7 +765,9 @@ export class McpManager {
   status() {
     return this.connections.map(connection => ({
       id: connection.id,
-      command: connection.config.command,
+      transport: connection.transport,
+      // http 型没有 command,退回显示 url —— 渲染端只认这一个字段
+      command: connection.config.command || connection.config.url || '',
       tools: connection.tools.length,
       error: connection.error,
     }));
@@ -496,4 +792,4 @@ export class McpManager {
   }
 }
 
-export default { McpManager, loadMcpServers, buildSpawnSpec, MCP_TOOL_PREFIX };
+export default { McpManager, HttpConnection, loadMcpServers, buildSpawnSpec, serverTransport, MCP_TOOL_PREFIX };

package/src/cli/ai/mcp.test.js

@@ -12,17 +12,21 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //
-// MCP stdio 客户端的回归测试。
+// MCP 客户端(stdio + Streamable HTTP)的回归测试。
 //
 // 这里最值钱的一条是 buildSpawnSpec 的转义用例 —— Windows 上
 // `spawn(cmd, args, { shell: true })` 会把含空格的参数拆碎(实测 C:\a b\proj
 // 会变成 "C:a" + "bproj"),而直接 spawn .cmd 又会被 Node 拒绝(EINVAL)。
 // 项目路径带空格是常态,这两条任一回归都会让"装了 MCP 但连不上"变成玄学问题。
+//
+// HTTP 那半边的重点在:响应可能是 JSON 也可能是 SSE、流可能一直挂着不关、
+// session 头要回传 —— 任一条错都表现为"远程 MCP 连不上"。
 
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { promises as fs } from 'node:fs';
 import { spawn } from 'node:child_process';
+import http from 'node:http';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -33,7 +37,7 @@ process.env.HOME = sandboxHome;
 delete process.env.HOMEDRIVE;
 delete process.env.HOMEPATH;
 
-const { buildSpawnSpec, loadMcpServers, McpManager } = await import('./mcp.js');
+const { buildSpawnSpec, loadMcpServers, McpManager, serverTransport } = await import('./mcp.js');
 const { AI_MCP_FILE } = await import('../../paths.js');
 
 const IS_WIN = process.platform === 'win32';
@@ -285,3 +289,199 @@ test('McpManager: 没有配置任何 server 时是空管理器,不影响内置
     await manager.close();
   }
 });
+
+// ── Streamable HTTP 往返 ──────────────────────────────────────
+
+test('serverTransport: 有 command 就是 stdio,只有 url 才是 http,都没有则两边都不是', () => {
+  assert.equal(serverTransport({ command: 'npx', args: ['-y', 'x'] }), 'stdio');
+  assert.equal(serverTransport({ type: 'http', url: 'https://example.com/mcp' }), 'http');
+  // 同时给了两者时以 command 为准 —— 本地子进程更可控,也是生态里的通行优先级
+  assert.equal(serverTransport({ command: 'npx', url: 'https://example.com/mcp' }), 'stdio');
+  assert.equal(serverTransport({ args: ['no-command-no-url'] }), null);
+  assert.equal(serverTransport({ url: 'ftp://example.com' }), null, '只认 http(s)');
+  assert.equal(serverTransport(null), null);
+});
+
+test('loadMcpServers: url 型(Streamable HTTP)条目不再被当成坏配置丢掉', async () => {
+  const project = await fs.mkdtemp(path.join(os.tmpdir(), 'zen-mcp-http-merge-'));
+  const file = path.join(project, '.zen-gitsync', 'ai', 'mcp.json');
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify({
+    mcpServers: {
+      remote: { type: 'http', url: 'https://example.com/api/mcp', headers: { Authorization: 'Bearer t' } },
+      local: { command: 'npx', args: ['-y', 'whatever'] },
+      broken: { args: ['no-command-no-url'] },
+    },
+  }), 'utf8');
+
+  const { servers } = await loadMcpServers({ cwd: project });
+  assert.equal(servers.remote?.url, 'https://example.com/api/mcp');
+  assert.equal(servers.local?.command, 'npx');
+  assert.equal(servers.broken, undefined, '两边都没有的条目仍要被丢弃');
+});
+
+// 一个最小可用的远程 MCP server。按 method 回 JSON 或 SSE;可要求客户端回传 session 头。
+function startFakeHttpMcp({ sse = false, holdSse = false, session = 'sess-abc' } = {}) {
+  const state = { requests: [], session };
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.setEncoding('utf8');
+    req.on('data', chunk => { body += chunk });
+    req.on('end', () => {
+      if (req.method === 'DELETE') {
+        state.requests.push({ method: 'DELETE', headers: req.headers });
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      const message = JSON.parse(body || '{}');
+      state.requests.push({ method: message.method, headers: req.headers, message });
+
+      const reply = payload => {
+        const headers = { 'Content-Type': sse ? 'text/event-stream' : 'application/json' };
+        if (session && state.session && message.method === 'initialize') headers['Mcp-Session-Id'] = state.session;
+        res.writeHead(200, headers);
+        const text = JSON.stringify(payload);
+        if (!sse) { res.end(text); return }
+        res.write(`event: message\ndata: ${text}\n\n`);
+        // holdSse:故意不结束流 —— 服务端完全有权利把连接挂着继续推通知,
+        // 客户端必须在拿到目标帧时就收手,而不是等流结束
+        if (!holdSse) res.end();
+      };
+
+      if (message.method === 'initialize') {
+        reply({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2025-03-26', capabilities: {}, serverInfo: { name: 'fake-http', version: '0' } } });
+      } else if (message.method === 'notifications/initialized') {
+        res.writeHead(202);
+        res.end();
+      } else if (message.method === 'tools/list') {
+        reply({ jsonrpc: '2.0', id: message.id, result: { tools: [
+          { name: 'echo', description: '回显输入', inputSchema: { type: 'object', properties: { text: { type: 'string' } } } },
+          { name: 'boom', description: '永远失败', inputSchema: { type: 'object' } },
+        ] } });
+      } else if (message.method === 'tools/call') {
+        if (message.params.name === 'boom') {
+          reply({ jsonrpc: '2.0', id: message.id, result: { isError: true, content: [{ type: 'text', text: '炸了' }] } });
+        } else {
+          reply({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: 'echo:' + (message.params.arguments?.text ?? '') }] } });
+        }
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+  });
+  return new Promise(resolve => {
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        server,
+        state,
+        url: `http://127.0.0.1:${server.address().port}/mcp`,
+        stop: () => new Promise(done => {
+          server.closeAllConnections?.();
+          server.close(() => done());
+        }),
+      });
+    });
+  });
+}
+
+test('McpManager(http): 握手后挂成 mcp__<server>__<tool>,调用结果与 stdio 版同口径', async () => {
+  const fake = await startFakeHttpMcp();
+  const manager = await McpManager.create({
+    cwd: sandboxProject,
+    servers: { remote: { type: 'http', url: fake.url } },
+    onWarn: () => {},
+  });
+  try {
+    const status = manager.status();
+    assert.equal(status[0].error, null, `应连接成功,实际: ${status[0].error}`);
+    assert.equal(status[0].transport, 'http');
+    assert.equal(status[0].command, fake.url, '诊断里应回落到 url,而不是留个空 command');
+    assert.equal(manager.toolCount, 2);
+
+    const names = manager.toolDefinitions.map(tool => tool.function.name);
+    assert.ok(names.includes('mcp__remote__echo'), names.join(','));
+    assert.ok(names.includes('mcp__remote__boom'), names.join(','));
+
+    assert.equal(await manager.call('mcp__remote__echo', { text: '你好' }), 'echo:你好');
+    assert.match(await manager.call('mcp__remote__boom', {}), /^错误: 炸了/);
+    assert.equal(await manager.call('mcp__remote__nope', {}), null, '未知工具应回落到内置工具表');
+  } finally {
+    await manager.close();
+    await fake.stop();
+  }
+});
+
+test('McpManager(http): 自定义头透传、session 头回传、关闭时 DELETE 结束会话', async () => {
+  const fake = await startFakeHttpMcp();
+  const manager = await McpManager.create({
+    cwd: sandboxProject,
+    servers: { remote: { type: 'http', url: fake.url, headers: { Authorization: 'Bearer t0ken' } } },
+    onWarn: () => {},
+  });
+  try {
+    const init = fake.state.requests.find(item => item.method === 'initialize');
+    assert.equal(init.headers.authorization, 'Bearer t0ken', '配置里的 headers 必须原样发出去');
+    assert.match(init.headers.accept, /text\/event-stream/, 'Accept 必须同时声明 json 与 event-stream,否则会被判 406');
+
+    const list = fake.state.requests.find(item => item.method === 'tools/list');
+    assert.equal(list.headers['mcp-session-id'], 'sess-abc', 'initialize 给的 session 头要在后续请求回传');
+
+    await manager.call('mcp__remote__echo', { text: 'x' });
+    const call = fake.state.requests.find(item => item.method === 'tools/call');
+    assert.equal(call.headers['mcp-session-id'], 'sess-abc');
+
+    await manager.close();
+    const del = fake.state.requests.find(item => item.method === 'DELETE');
+    assert.ok(del, '关闭时应尽力 DELETE 结束会话');
+    assert.equal(del.headers['mcp-session-id'], 'sess-abc');
+  } finally {
+    await fake.stop();
+  }
+});
+
+test('McpManager(http): SSE 响应能取到结果,且服务端不关流也不会拖到超时', async () => {
+  const fake = await startFakeHttpMcp({ sse: true, holdSse: true });
+  const started = Date.now();
+  const manager = await McpManager.create({
+    cwd: sandboxProject,
+    servers: { remote: { type: 'http', url: fake.url } },
+    onWarn: () => {},
+  });
+  try {
+    assert.equal(manager.toolCount, 2, 'SSE 响应里的 tools/list 也要能解析出来');
+    assert.equal(await manager.call('mcp__remote__echo', { text: 'sse' }), 'echo:sse');
+    assert.ok(Date.now() - started < 5000, `拿到目标帧就该收手,不该等流结束,实际耗时 ${Date.now() - started}ms`);
+  } finally {
+    await manager.close();
+    await fake.stop();
+  }
+});
+
+test('McpManager(http): 远程连不上只记错误,不影响其他 server 与内置工具', async () => {
+  const dead = await startFakeHttpMcp();
+  const deadUrl = dead.url;
+  await dead.stop(); // 端口关掉,模拟服务端不在
+
+  const manager = await McpManager.create({
+    cwd: sandboxProject,
+    servers: {
+      down: { type: 'http', url: deadUrl },
+      other: { args: ['no-command-no-url'] }, // 无效条目,连传输都判不出来
+    },
+    onWarn: () => {},
+  });
+  try {
+    const status = manager.status();
+    const down = status.find(item => item.id === 'down');
+    assert.ok(down.error, '连不上必须有可读错误');
+    assert.match(down.error, /连接 "down" 失败/, `错误应指明是哪个 server,实际: ${down.error}`);
+    assert.match(down.error, /ECONNREFUSED|fetch failed/, `错误应带上底层原因,实际: ${down.error}`);
+    assert.equal(down.tools, 0);
+    assert.equal(manager.toolCount, 0);
+    assert.equal(await manager.call('mcp__down__echo', {}), null);
+  } finally {
+    await manager.close();
+  }
+});