ppxans-harness 2.4.0 → 3.2.0

package/src/mcp/http.js

@@ -0,0 +1,203 @@
+// src/mcp/http.js - MCP Streamable HTTP 传输层 (零依赖)
+// 2026-07-28 语义:
+//   - 单端点只收 POST; 每个 JSON-RPC 请求/通知一次 POST
+//   - 必带头: MCP-Protocol-Version (现代 era, 与 body _meta 校验一致)
+//   - 响应: application/json 单对象 或 text/event-stream (SSE 流, 请求级)
+//   - 通知 (无 id) -> 202 Accepted 无 body
+//   - 取消 = 关闭 SSE 流 (无需 notifications/cancelled)
+//   - Origin 校验防 DNS rebinding; 本地默认只绑 127.0.0.1
+import { McpServer, McpError, MCP_ERROR, MODERN_PROTOCOL_VERSION, SERVER_INFO_META_KEY } from "./server.js";
+import { readBody, sendJson, SSE_HEADERS } from "../utils/http.js";
+import { debug } from "../utils/logger.js";
+
+const MAX_BODY = 1024 * 1024; // 1MB
+
+// ---- SSE 序列化 ----
+function sseMessage(obj) {
+  return `event: message\ndata: ${JSON.stringify(obj)}\n\n`;
+}
+
+// (readBody 收敛到 utils/http.js: 超限返回 null, 由下方改为抛 McpError 保持原语义)
+
+// ---- 传输错误 -> HTTP 状态码映射 (2026-07-28) ----
+function statusFor(err) {
+  switch (err.code) {
+    case MCP_ERROR.UNSUPPORTED_PROTOCOL_VERSION: return 400; // Bad Request
+    case MCP_ERROR.HEADER_MISMATCH: return 400;
+    case MCP_ERROR.MISSING_REQUIRED_CLIENT_CAPABILITY: return 400;
+    case MCP_ERROR.METHOD_NOT_FOUND: return 404;             // 未知方法
+    case MCP_ERROR.INVALID_PARAMS: return 400;
+    case MCP_ERROR.INVALID_REQUEST: return 400;
+    case MCP_ERROR.PARSE_ERROR: return 400;
+    default: return 500;
+  }
+}
+
+/**
+ * 创建 MCP Streamable HTTP 请求处理器。
+ * @param {McpServer} server
+ * @param {object} [opts]
+ * @param {(req:any)=>boolean} [opts.authenticated] 鉴权钩子: 返回 false 则 401 (可选, 未提供则放行)
+ * @param {(req:any, res:any)=>boolean} [opts.rateLimit] 限流钩子: 返回 false 则已响应 429 (可选)
+ * @param {string[]} [opts.allowedOrigins] CORS/Origin 白名单; 空 = 仅无 Origin 或本地回环
+ * @param {boolean} [opts.skipOriginCheck] 宿主已统一处理 CORS/Origin 时跳过 (避免双重标准)
+ * @returns {(req:any,res:any)=>Promise<void>}
+ */
+export function createMcpHttpHandler(server, opts = {}) {
+  return async (req, res) => {
+    try {
+      // 1. 方法限制: 只收 POST
+      if (req.method !== "POST") {
+        sendJson(res, 405, { error: "method not allowed" }, { headers: { "Allow": "POST" } });
+        return;
+      }
+
+      // 2. Origin 校验 (防 DNS rebinding; 宿主已统一处理时可跳过)
+      const origin = req.headers.origin;
+      if (origin && !opts.skipOriginCheck) {
+        const allowed = opts.allowedOrigins && opts.allowedOrigins.length
+          ? opts.allowedOrigins.includes(origin)
+          : /^https?:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/.test(origin);
+        if (!allowed) {
+          sendJson(res, 403, { jsonrpc: "2.0", error: { code: -32600, message: "origin not allowed" } });
+          return;
+        }
+      }
+
+      // 3. 可选鉴权 / 限流 (由宿主通道注入)
+      if (opts.authenticated && !opts.authenticated(req, res)) return;
+      if (opts.rateLimit && !opts.rateLimit(req, res)) return;
+
+      // 4. 读 body + 解析
+      let msg;
+      try {
+        const body = await readBody(req, { maxBytes: MAX_BODY });
+        if (body === null) throw new McpError(MCP_ERROR.INVALID_REQUEST, "request too large");
+        msg = body ? JSON.parse(body) : {};
+      } catch (e) {
+        sendJson(res, 400, {
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: MCP_ERROR.PARSE_ERROR, message: `Parse error: ${e.message}` },
+        });
+        return;
+      }
+
+      // 5. 版本头校验 (现代 era): MCP-Protocol-Version 必须与 body _meta 一致
+      const headerVersion = req.headers["mcp-protocol-version"];
+      const bodyVersion = msg && msg.params && msg.params._meta && msg.params._meta["io.modelcontextprotocol/protocolVersion"];
+      if (bodyVersion && headerVersion && headerVersion !== bodyVersion) {
+        sendJson(res, 400, {
+          jsonrpc: "2.0",
+          id: msg.id ?? null,
+          error: { code: MCP_ERROR.HEADER_MISMATCH, message: "Header MCP-Protocol-Version does not match body _meta", data: { header: headerVersion, body: bodyVersion } },
+        });
+        return;
+      }
+      // 现代请求 (有 bodyVersion) 但缺 header: 允许 (兼容未带头的老客户端), 记录即可
+      if (bodyVersion && !headerVersion) {
+        // 2026-07-28 规范要求必带; 宽松兼容: 直接按 body 版本处理
+      }
+
+      // 6. 通知 (无 id) -> 202
+      if (msg && (msg.id === undefined || msg.id === null)) {
+        // 通知: 只处理 notifications/* 或 ping 通知语义; 直接受理
+        await server.handle(msg, {}).catch((e) => {
+          // 通知失败仅记日志, 不影响 202 语义
+          if (opts.onError) opts.onError(e);
+        });
+        sendJson(res, 202);
+        return;
+      }
+
+      // 7. 请求: 是否 SSE (客户端 Accept 两者之一; 流式工具请求开 SSE 流)
+      const accept = String(req.headers.accept || "");
+      const isStreamTool = msg && msg.method === "tools/call" && /stream/i.test(String(msg.params && msg.params.name || ""));
+      const wantsSSE = accept.includes("text/event-stream") && isStreamTool;
+
+      if (wantsSSE) {
+        // SSE 响应流: 进度通知 + 最终响应, 关闭流 = 取消
+        res.writeHead(200, SSE_HEADERS);
+        res.write(": keep-alive\n\n");
+        const progressToken = msg.params && msg.params._meta && msg.params._meta.progressToken;
+        const streamCtx = {
+          stream: {
+            onDelta: (delta, extra = {}) => {
+              if (res.writableEnded) return;
+              const notif = { jsonrpc: "2.0", method: "notifications/progress", params: { progress: extra.progress, total: extra.total, message: String(delta).slice(0, 4000) } };
+              if (progressToken !== undefined) notif.params.progressToken = progressToken;
+              res.write(sseMessage(notif));
+            },
+            onMessage: (text) => {
+              if (res.writableEnded) return;
+              res.write(sseMessage({ jsonrpc: "2.0", method: "notifications/message", params: { level: "info", data: String(text).slice(0, 4000) } }));
+            },
+            // v2.6.0: 结构化工具事件透传 (web 前端渲染工具卡片): notifications/message 带 type=tool
+            onTool: (ev) => {
+              if (res.writableEnded || !ev) return;
+              res.write(sseMessage({ jsonrpc: "2.0", method: "notifications/message", params: { level: "info", data: { type: "tool", tool: ev.tool, status: ev.type || ev.status, ok: ev.ok, durationMs: ev.durationMs } } }));
+            },
+            // 推理轮次事件
+            onStep: (ev) => {
+              if (res.writableEnded || !ev) return;
+              res.write(sseMessage({ jsonrpc: "2.0", method: "notifications/message", params: { level: "info", data: { type: "step", round: ev.round, maxRounds: ev.maxRounds } } }));
+            },
+          },
+        };
+        try {
+          const { result } = await server.handle(msg, streamCtx);
+          // 流式工具: 结果即最终 delta (chat.stream 已通过 onDelta 推送过; 这里补发完整结果)
+          res.write(sseMessage({ jsonrpc: "2.0", id: msg.id, result: result ?? {} }));
+        } catch (e) {
+          const err = e instanceof McpError ? e : new McpError(MCP_ERROR.INTERNAL_ERROR, e.message || "internal error");
+          res.write(sseMessage({ jsonrpc: "2.0", id: msg.id, error: { code: err.code, message: err.message, ...(err.data ? { data: err.data } : {}) } }));
+        } finally {
+          try { res.end(); } catch (e) { debug(`[mcp/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+        }
+        return;
+      }
+
+      // 8. 普通 JSON 响应
+      try {
+        const { result } = await server.handle(msg, {});
+        sendJson(res, 200, { jsonrpc: "2.0", id: msg.id, result: result ?? {} });
+      } catch (e) {
+        const err = e instanceof McpError ? e : new McpError(MCP_ERROR.INTERNAL_ERROR, e.message || "internal error");
+        sendJson(res, statusFor(err), {
+          jsonrpc: "2.0",
+          id: msg.id ?? null,
+          error: { code: err.code, message: err.message, ...(err.data ? { data: err.data } : {}) },
+        });
+      }
+    } catch (e) {
+      // 外层兜底 (不应发生)
+      try {
+        sendJson(res, 500, { jsonrpc: "2.0", error: { code: -32603, message: e.message || "internal error" } });
+      } catch (e) { debug(`[mcp/http] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    }
+  };
+}
+
+// ---- 便捷工厂: 从 agent 构建标准 McpServer + HTTP handler ----
+export function createMcpEndpoint(agent, opts = {}) {
+  const server = new McpServer(agent, {
+    name: opts.name,
+    version: opts.version,
+    supportedVersions: opts.supportedVersions,
+    extraTools: opts.extraTools,
+    prompts: opts.prompts,
+  });
+  const handler = createMcpHttpHandler(server, {
+    authenticated: opts.authenticated,
+    rateLimit: opts.rateLimit,
+    allowedOrigins: opts.allowedOrigins,
+    // 2026-10-03 修复 (P2): 原工厂吞掉 skipOriginCheck —— channels/http.js 显式传
+    // skipOriginCheck: true (宿主 CORS 白名单已统一处理 Origin), 但工厂不转发 →
+    // handler 内部仍用默认回环正则二次校验, 契约失真 (宿主白名单形同虚设)。
+    skipOriginCheck: opts.skipOriginCheck,
+    onError: opts.onError,
+  });
+  return { server, handler };
+}
+
+export { McpServer, McpError, MCP_ERROR, MODERN_PROTOCOL_VERSION, SERVER_INFO_META_KEY };

package/src/mcp/index.js

@@ -1,116 +1,116 @@
-// src/mcp/index.js - MCP 工具注册 (接入 MCP 工具生态)
-// 把 MCP 服务器的工具转换为皮皮虾 ToolCatalog 工具, 与内置工具同权。
-// servers: [
-//   { command, args, env, prefix }                         // stdio (本机)
-//   { url, headers, prefix, timeout }                      // HTTP Streamable (远程)
-// ]
-import { McpClient, extractToolResult, extractResourceText } from "./client.js";
-import { TOOL_ERROR_PREFIX } from "../tools/catalog.js";
-import { warn, info } from "../utils/logger.js";
-
-// v1.0.8: MCP 工具名清洗 (只留 \w.-, 截断) — 防恶意服务器注册非法工具名/注入
-export function sanitizeMcpName(name) {
-  return String(name || "").replace(/[^\w.-]/g, "_").slice(0, 64);
-}
-
-// P1⑦ (2026-09-15): MCP 命名空间隔离 —— 防工具名碰撞 (Hermes 生产数据: 51 工具服务器上
-//   幻觉工具名命中真实工具; cron job 本想调 kanban_list 结果执行了 list_goals)。
-//   强制 serverName__toolName 前缀 + 精确匹配短路。
-export function serverLabel(s) {
-  // 取服务器可读标识: 配置 name > 包名 (args 里 @scope/pkg 或 *.py) > command 首段 > url host
-  if (s && s.name) return sanitizeMcpName(s.name);
-  const fromArgs = (s && s.args || []).find((a) => /(?:^|\/)[@\w.-]+(?:@[\w.]+)?$/.test(a) && !a.startsWith("-"));
-  if (fromArgs) return sanitizeMcpName(fromArgs.split("/").pop());
-  if (s && s.command) return sanitizeMcpName(String(s.command).split(/[\\/\s]/).filter(Boolean).pop() || "mcp");
-  if (s && s.url) {
-    try {
-      const host = new URL(s.url).hostname.split(".").filter(Boolean);
-      // 取二级域: mcp.example.com → example; www.google.com → google
-      return sanitizeMcpName(host.length >= 2 ? host[host.length - 2] : host[0] || "mcp");
-    } catch {}
-  }
-  return "mcp";
-}
-
-export function namespacedMcpName(label, raw) {
-  const clean = sanitizeMcpName(raw);
-  return clean ? `${label}__${clean}` : label;
-}
-
-// v1.0.8: MCP 工具描述清洗 (单行化 + 截断) — 服务器描述直接进 LLM prompt, 防换行/长文本注入指令
-// P1⑦: 额外剔除危险 flag (--system/--dangerously 等命令行注入惯用手法)
-export function sanitizeMcpDescription(desc, name) {
-  let s = String(desc || "").replace(/\s+/g, " ").trim();
-  // 危险 flag 清洗: 描述里出现命令行注入惯用 flag 视为可疑, 剔除该片段
-  s = s.replace(/--(?:system|dangerously[-\w]*|yes|force|no[-\w]+|y)\b/g, "[flag]");
-  return s.slice(0, 200) || `MCP 工具: ${name}`;
-}
-
-// 连接所有 MCP 服务器, 列出工具并注册到 catalog。
-// 除 tools 外, 服务器声明 resources/prompts 能力时, 额外注册对应读写工具 (P2⑥)。
-// 返回 { count, clients, close } — close() 关闭全部连接 (调用方负责生命周期)
-export async function registerMcpTools(catalog, servers = []) {
-  const clients = [];
-  let count = 0;
-  for (const s of servers) {
-    if (!s) { warn("[mcp] 跳过无效服务器配置"); continue; }
-    if (!s.command && !s.url) { warn("[mcp] 跳过无效服务器配置 (缺 command/url)"); continue; }
-    const client = new McpClient(s);
-    try {
-      await client.connect();
-      const tools = await client.listTools();
-      // P1⑦: 命名空间强制前缀 (serverLabel) —— 默认开启, 可显式 prefix 覆盖/关闭
-      const label = serverLabel(s);
-      const ns = s.prefix != null ? s.prefix : `${label}__`;
-      for (const t of tools) {
-        if (!t || !t.name) continue;
-        const name = ns + sanitizeMcpName(t.name);
-        // P1⑦: 精确匹配短路 —— 注册时登记原始名 (供幻觉工具名防御: 无前缀名永不执行)
-        catalog.register({
-          name,
-          description: sanitizeMcpDescription(t.description, t.name),
-          parameters: t.inputSchema || { type: "object", properties: {} },
-          category: "mcp",
-          // isError 时加错误前缀, 让皮皮虾的自愈重试语义对 MCP 工具同样生效
-          execute: async (args) => {
-            const raw = await client.callToolRaw(t.name, args || {});
-            const { text, isError } = extractToolResult(raw);
-            return isError ? `${TOOL_ERROR_PREFIX} MCP 工具 ${t.name}: ${text}` : text;
-          },
-        });
-        count += 1;
-      }
-      count += registerResourceTools(catalog, client, s, ns);
-      clients.push(client);
-    } catch (e) {
-      warn(`[mcp] 服务器 ${s.command || s.url} 连接失败: ${e.message}`);
-      client.close();
-    }
-  }
-  if (count) info(`[mcp] 已注册 ${count} 个 MCP 工具`);
-  return { count, clients, close: () => clients.forEach((c) => c.close()) };
-}
-
-// 服务器声明 resources 能力时, 注册 list_resources / read_resource 两个工具 (让 LLM 可读远程资源)
-function registerResourceTools(catalog, client, s, ns = "") {
-  if (!client.capabilities?.resources) return 0;
-  const label = s.command || s.url || "MCP";
-  catalog.register({
-    name: ns + "list_resources",
-    description: `列出 MCP 服务器 ${label} 提供的资源 (URI 列表)`,
-    parameters: { type: "object", properties: {}, required: [] },
-    category: "mcp",
-    execute: async () => {
-      const res = await client.listResources();
-      return res.map((r) => `${r.uri || "?"}${r.name ? ` — ${r.name}` : ""}`).join("\n") || "(无资源)";
-    },
-  });
-  catalog.register({
-    name: ns + "read_resource",
-    description: `读取 MCP 服务器 ${label} 的资源内容 (按 uri)`,
-    parameters: { type: "object", properties: { uri: { type: "string", description: "资源 URI" } }, required: ["uri"] },
-    category: "mcp",
-    execute: async (args) => extractResourceText(await client.readResource((args || {}).uri)),
-  });
-  return 2;
-}
+// src/mcp/index.js - MCP 工具注册 (接入 MCP 工具生态)
+// 把 MCP 服务器的工具转换为皮皮虾 ToolCatalog 工具, 与内置工具同权。
+// servers: [
+//   { command, args, env, prefix }                         // stdio (本机)
+//   { url, headers, prefix, timeout }                      // HTTP Streamable (远程)
+// ]
+import { McpClient, extractToolResult, extractResourceText } from "./client.js";
+import { TOOL_ERROR_PREFIX } from "../tools/catalog.js";
+import { warn, info, debug } from "../utils/logger.js";
+
+// v1.0.8: MCP 工具名清洗 (只留 \w.-, 截断) — 防恶意服务器注册非法工具名/注入
+export function sanitizeMcpName(name) {
+  return String(name || "").replace(/[^\w.-]/g, "_").slice(0, 64);
+}
+
+// P1⑦ (2026-09-15): MCP 命名空间隔离 —— 防工具名碰撞 (Hermes 生产数据: 51 工具服务器上
+//   幻觉工具名命中真实工具; cron job 本想调 kanban_list 结果执行了 list_goals)。
+//   强制 serverName__toolName 前缀 + 精确匹配短路。
+export function serverLabel(s) {
+  // 取服务器可读标识: 配置 name > 包名 (args 里 @scope/pkg 或 *.py) > command 首段 > url host
+  if (s && s.name) return sanitizeMcpName(s.name);
+  const fromArgs = (s && s.args || []).find((a) => /(?:^|\/)[@\w.-]+(?:@[\w.]+)?$/.test(a) && !a.startsWith("-"));
+  if (fromArgs) return sanitizeMcpName(fromArgs.split("/").pop());
+  if (s && s.command) return sanitizeMcpName(String(s.command).split(/[\\/\s]/).filter(Boolean).pop() || "mcp");
+  if (s && s.url) {
+    try {
+      const host = new URL(s.url).hostname.split(".").filter(Boolean);
+      // 取二级域: mcp.example.com → example; www.google.com → google
+      return sanitizeMcpName(host.length >= 2 ? host[host.length - 2] : host[0] || "mcp");
+    } catch (e) { debug(`[mcp/index] 已忽略异常: ${e && e.message ? e.message : e}`); }
+  }
+  return "mcp";
+}
+
+export function namespacedMcpName(label, raw) {
+  const clean = sanitizeMcpName(raw);
+  return clean ? `${label}__${clean}` : label;
+}
+
+// v1.0.8: MCP 工具描述清洗 (单行化 + 截断) — 服务器描述直接进 LLM prompt, 防换行/长文本注入指令
+// P1⑦: 额外剔除危险 flag (--system/--dangerously 等命令行注入惯用手法)
+export function sanitizeMcpDescription(desc, name) {
+  let s = String(desc || "").replace(/\s+/g, " ").trim();
+  // 危险 flag 清洗: 描述里出现命令行注入惯用 flag 视为可疑, 剔除该片段
+  s = s.replace(/--(?:system|dangerously[-\w]*|yes|force|no[-\w]+|y)\b/g, "[flag]");
+  return s.slice(0, 200) || `MCP 工具: ${name}`;
+}
+
+// 连接所有 MCP 服务器, 列出工具并注册到 catalog。
+// 除 tools 外, 服务器声明 resources/prompts 能力时, 额外注册对应读写工具 (P2⑥)。
+// 返回 { count, clients, close } — close() 关闭全部连接 (调用方负责生命周期)
+export async function registerMcpTools(catalog, servers = []) {
+  const clients = [];
+  let count = 0;
+  for (const s of servers) {
+    if (!s) { warn("[mcp] 跳过无效服务器配置"); continue; }
+    if (!s.command && !s.url) { warn("[mcp] 跳过无效服务器配置 (缺 command/url)"); continue; }
+    const client = new McpClient(s);
+    try {
+      await client.connect();
+      const tools = await client.listTools();
+      // P1⑦: 命名空间强制前缀 (serverLabel) —— 默认开启, 可显式 prefix 覆盖/关闭
+      const label = serverLabel(s);
+      const ns = s.prefix != null ? s.prefix : `${label}__`;
+      for (const t of tools) {
+        if (!t || !t.name) continue;
+        const name = ns + sanitizeMcpName(t.name);
+        // P1⑦: 精确匹配短路 —— 注册时登记原始名 (供幻觉工具名防御: 无前缀名永不执行)
+        catalog.register({
+          name,
+          description: sanitizeMcpDescription(t.description, t.name),
+          parameters: t.inputSchema || { type: "object", properties: {} },
+          category: "mcp",
+          // isError 时加错误前缀, 让皮皮虾的自愈重试语义对 MCP 工具同样生效
+          execute: async (args) => {
+            const raw = await client.callToolRaw(t.name, args || {});
+            const { text, isError } = extractToolResult(raw);
+            return isError ? `${TOOL_ERROR_PREFIX} MCP 工具 ${t.name}: ${text}` : text;
+          },
+        });
+        count += 1;
+      }
+      count += registerResourceTools(catalog, client, s, ns);
+      clients.push(client);
+    } catch (e) {
+      warn(`[mcp] 服务器 ${s.command || s.url} 连接失败: ${e.message}`);
+      client.close();
+    }
+  }
+  if (count) info(`[mcp] 已注册 ${count} 个 MCP 工具`);
+  return { count, clients, close: () => clients.forEach((c) => c.close()) };
+}
+
+// 服务器声明 resources 能力时, 注册 list_resources / read_resource 两个工具 (让 LLM 可读远程资源)
+function registerResourceTools(catalog, client, s, ns = "") {
+  if (!client.capabilities?.resources) return 0;
+  const label = s.command || s.url || "MCP";
+  catalog.register({
+    name: ns + "list_resources",
+    description: `列出 MCP 服务器 ${label} 提供的资源 (URI 列表)`,
+    parameters: { type: "object", properties: {}, required: [] },
+    category: "mcp",
+    execute: async () => {
+      const res = await client.listResources();
+      return res.map((r) => `${r.uri || "?"}${r.name ? ` — ${r.name}` : ""}`).join("\n") || "(无资源)";
+    },
+  });
+  catalog.register({
+    name: ns + "read_resource",
+    description: `读取 MCP 服务器 ${label} 的资源内容 (按 uri)`,
+    parameters: { type: "object", properties: { uri: { type: "string", description: "资源 URI" } }, required: ["uri"] },
+    category: "mcp",
+    execute: async (args) => extractResourceText(await client.readResource((args || {}).uri)),
+  });
+  return 2;
+}