u1s1-cli 1.7.1 → 1.8.0

package/dist/agent-setup.d.ts

@@ -49,6 +49,13 @@ export declare function writeErrorHumanizeExtension(): void;
  * print/json 一次性模式不起轮询;import 失败静默跳过(同 error-humanize)。
  */
 export declare function writeAnnouncementsExtension(): void;
+/**
+ * 生成「自定义 MCP 服务」扩展到 <agentDir>/extensions/u1s1-mcp.js。
+ * 读 ~/.u1s1/mcp.json,把每个服务的工具注册成 mcp_<服务>_<工具>;逻辑在 mcp/extension.ts,
+ * 这里只负责投影(Desktop App 共享)。没配置任何服务时扩展直接返回,零开销。
+ * 子会话(spawn_subagent)里不挂 MCP 工具:避免每个子进程都拉起一份服务。
+ */
+export declare function writeMcpExtension(): void;
 /**
  * 生成「OpenRouter 应用归因」扩展到 <agentDir>/extensions/u1s1-attribution.js。
  * 用户自己配 OPENROUTER_API_KEY 直连时，pi 内置的归因头归到 pi.dev 名下（且受遥测

package/dist/agent-setup.js

@@ -332,6 +332,35 @@ export function writeAnnouncementsExtension() {
         `  });\n` +
         `}\n`);
 }
+/**
+ * 生成「自定义 MCP 服务」扩展到 <agentDir>/extensions/u1s1-mcp.js。
+ * 读 ~/.u1s1/mcp.json,把每个服务的工具注册成 mcp_<服务>_<工具>;逻辑在 mcp/extension.ts,
+ * 这里只负责投影(Desktop App 共享)。没配置任何服务时扩展直接返回,零开销。
+ * 子会话(spawn_subagent)里不挂 MCP 工具:避免每个子进程都拉起一份服务。
+ */
+export function writeMcpExtension() {
+    const dir = join(agentDir, "extensions");
+    mkdirSync(dir, { recursive: true });
+    const url = new URL("./mcp/extension.js", import.meta.url).href;
+    writeFileSync(join(dir, "u1s1-mcp.js"), `// 由 u1s1 每次启动自动生成,请勿手改\n` +
+        `export default async function (pi) {\n` +
+        `  if (process.env.U1S1_IN_SUBAGENT === "1") return;\n` +
+        `  let registerMcpServers;\n` +
+        `  try {\n` +
+        `    registerMcpServers = (await import(${JSON.stringify(url)})).registerMcpServers;\n` +
+        `  } catch {\n` +
+        `    return;\n` +
+        `  }\n` +
+        `  try {\n` +
+        `    await registerMcpServers(pi);\n` +
+        `  } catch (err) {\n` +
+        `    const msg = err instanceof Error ? err.message : String(err);\n` +
+        `    pi.on("session_start", (_event, ctx) => {\n` +
+        `      if (ctx.hasUI) ctx.ui.notify("MCP 服务加载失败:" + msg, "warning");\n` +
+        `    });\n` +
+        `  }\n` +
+        `}\n`);
+}
 /**
  * 生成「OpenRouter 应用归因」扩展到 <agentDir>/extensions/u1s1-attribution.js。
  * 用户自己配 OPENROUTER_API_KEY 直连时，pi 内置的归因头归到 pi.dev 名下（且受遥测

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execSync, spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
-import { cleanupBrandThemes, endpointKeyEnv, endpointProviderEntry, ensureBrandPrompt, ensureDefaultSettings, ensureProviderModels, ensureWorkflowPromptTemplate, scrubForeignProviderEnv, toProviderModels, writeAnnouncementsExtension, writeAttributionExtension, writeCompactUiExtension, writeErrorHumanizeExtension, writeWebToolsExtension, } from "./agent-setup.js";
+import { cleanupBrandThemes, endpointKeyEnv, endpointProviderEntry, ensureBrandPrompt, ensureDefaultSettings, ensureProviderModels, ensureWorkflowPromptTemplate, scrubForeignProviderEnv, toProviderModels, writeAnnouncementsExtension, writeAttributionExtension, writeMcpExtension, writeCompactUiExtension, writeErrorHumanizeExtension, writeWebToolsExtension, } from "./agent-setup.js";
 import { Text } from "@earendil-works/pi-tui";
 import { printConsoleBanner } from "./brand.js";
 import { agentDir, apiModelToDef, CUSTOM_ENDPOINTS, isPortableInstall, loadConfig, MODELS, persistPreferredModel, PROVIDER_ID, readSettings, refValid, resolvePreferredModel, setModelsFromApi, VERSION, } from "./config.js";
@@ -255,6 +255,8 @@ async function runAgent(cfg, args) {
     writeAnnouncementsExtension();
     // OpenRouter 应用归因：直连流量计入 u1s1 的公开排行
     writeAttributionExtension();
+    // 自定义 MCP 服务的工具(~/.u1s1/mcp.json,同样投影,Desktop 共享)
+    writeMcpExtension();
     ensureTmuxKeyboardProtocol();
     // must be set before pi reads them (getAgentDir() reads at call time);
     // 常量部分已在 runAgent 开头、发起 import 之前设好
@@ -537,6 +539,7 @@ async function run() {
         console.log("   u1s1 deploy remove     删除已发布的站点");
         console.log("   u1s1 feedback \"一句话\"  反馈问题或建议(自动建工单,--bug/--question…)");
         console.log("   u1s1 import            导入历史会话(import skills 导入技能)");
+        console.log("   u1s1 mcp               配置第三方 MCP 服务(add/list/test/remove/import)");
         console.log("   u1s1 bench             模型编码能力评测");
         console.log("   u1s1 --version         查看版本");
         console.log("");
@@ -583,6 +586,11 @@ async function run() {
         await feedbackCommand(args.slice(1));
         return;
     }
+    if (cmd === "mcp") {
+        const { mcpCommand } = await import("./mcp/command.js");
+        await mcpCommand(args.slice(1));
+        return;
+    }
     if (cmd === "model") {
         const { modelCommand } = await import("./model.js");
         await modelCommand(args[1]);
@@ -656,7 +664,7 @@ async function run() {
     // autoUpdate 开着且启动时发现了新版:现在装(TUI 已退出,原地重铺安全)
     installPendingUpdate();
 }
-const KNOWN_COMMANDS = ["deploy", "login", "logout", "usage", "model", "update", "import", "bench", "feedback", "help"];
+const KNOWN_COMMANDS = ["deploy", "login", "logout", "usage", "model", "update", "import", "mcp", "bench", "feedback", "help"];
 /** 没有自己 --help 处理的简单子命令:问用法时只打印说明,不执行任何动作。 */
 const SIMPLE_COMMAND_HELP = {
     login: [

package/dist/mcp/client.d.ts

@@ -0,0 +1,53 @@
+import type { McpServerConfig, McpToolInfo } from "./config.js";
+/**
+ * 极简 MCP 客户端:只做 initialize / tools/list / tools/call 三件事,
+ * 支持 stdio(本机进程,按行 JSON-RPC)和 Streamable HTTP(POST JSON,
+ * 响应可能是 JSON 也可能是 SSE)两种传输。不引 SDK:pi 本身没有 MCP client,
+ * 我们只需要把远端工具挂成 pi 工具,协议面很窄,自己写反而少一坨依赖。
+ */
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 20000;
+export declare const DEFAULT_CALL_TIMEOUT_MS = 120000;
+export interface McpClientOptions {
+    connectTimeoutMs?: number;
+    callTimeoutMs?: number;
+    /** 服务端 stderr / 传输层告警;默认丢弃 */
+    onLog?: (line: string) => void;
+}
+export interface McpServerInfo {
+    serverName?: string;
+    serverVersion?: string;
+    protocolVersion: string;
+}
+export interface McpCallResult {
+    text: string;
+    isError: boolean;
+}
+export declare class McpError extends Error {
+    readonly code?: number | undefined;
+    constructor(message: string, code?: number | undefined);
+}
+/** 解析 SSE 正文,返回每个 event 的 data 拼接结果 */
+export declare function parseSseData(body: string): string[];
+/** 把 tools/call 返回的 content 数组压成模型可读的文本 */
+export declare function contentToText(result: unknown): McpCallResult;
+export declare function normalizeToolInfo(raw: unknown): McpToolInfo | undefined;
+export declare class McpClient {
+    readonly name: string;
+    private readonly config;
+    private readonly opts;
+    private transport;
+    private nextId;
+    private readonly connectTimeoutMs;
+    private readonly callTimeoutMs;
+    private connected;
+    info: McpServerInfo | undefined;
+    constructor(name: string, config: McpServerConfig, opts?: McpClientOptions);
+    /** 建连并完成 initialize 握手;重复调用返回同一个 promise,失败后可重试 */
+    connect(): Promise<McpServerInfo>;
+    private doConnect;
+    private rpc;
+    listTools(): Promise<McpToolInfo[]>;
+    callTool(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<McpCallResult>;
+    close(): Promise<void>;
+}

package/dist/mcp/client.js

@@ -0,0 +1,452 @@
+import { spawn } from "node:child_process";
+import { VERSION } from "../config.js";
+/**
+ * 极简 MCP 客户端:只做 initialize / tools/list / tools/call 三件事,
+ * 支持 stdio(本机进程,按行 JSON-RPC)和 Streamable HTTP(POST JSON,
+ * 响应可能是 JSON 也可能是 SSE)两种传输。不引 SDK:pi 本身没有 MCP client,
+ * 我们只需要把远端工具挂成 pi 工具,协议面很窄,自己写反而少一坨依赖。
+ */
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+export const DEFAULT_CONNECT_TIMEOUT_MS = 20_000;
+export const DEFAULT_CALL_TIMEOUT_MS = 120_000;
+export class McpError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "McpError";
+    }
+}
+/** 谁先到算谁的:结果、超时、取消三者任一落定就清掉定时器与监听,别让悬着的定时器吊住进程 */
+function withTimeout(promise, timeoutMs, signal, what) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            fn(v);
+        };
+        const onAbort = () => finish(reject)(new McpError(`${what} 已取消`));
+        const timer = setTimeout(() => finish(reject)(new McpError(`${what} 超过 ${Math.round(timeoutMs / 1000)}s 未响应`)), timeoutMs);
+        promise.then(finish(resolve), finish(reject));
+        if (signal?.aborted)
+            onAbort();
+        else
+            signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+// ---------------- stdio ----------------
+class StdioTransport {
+    command;
+    args;
+    env;
+    onLog;
+    child;
+    buffer = "";
+    pending = new Map();
+    exited;
+    stderrTail = [];
+    constructor(command, args, env, onLog) {
+        this.command = command;
+        this.args = args;
+        this.env = env;
+        this.onLog = onLog;
+    }
+    start() {
+        const child = spawn(this.command, this.args, {
+            env: { ...process.env, ...this.env },
+            stdio: ["pipe", "pipe", "pipe"],
+            // Windows 上 npx / *.cmd 只能经 shell 启动
+            shell: process.platform === "win32",
+            windowsHide: true,
+        });
+        this.child = child;
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => this.onData(chunk));
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            for (const line of chunk.split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                this.stderrTail.push(line);
+                if (this.stderrTail.length > 20)
+                    this.stderrTail.shift();
+                this.onLog?.(line);
+            }
+        });
+        // CLI 自己退出时把服务进程一起带走,别留孤儿
+        const onParentExit = () => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch { }
+        };
+        process.once("exit", onParentExit);
+        child.on("error", (err) => {
+            // spawn 失败(ENOENT 等)不会再有 exit 事件
+            if (child.pid === undefined)
+                process.removeListener("exit", onParentExit);
+            this.fail(new McpError(`启动 ${this.command} 失败:${err.message}`));
+        });
+        child.on("exit", (code, sig) => {
+            process.removeListener("exit", onParentExit);
+            const tail = this.stderrTail.slice(-5).join("\n");
+            this.fail(new McpError(`MCP 服务进程已退出(${sig ?? `code ${code ?? 0}`})${tail ? `\n${tail}` : ""}`));
+        });
+    }
+    fail(err) {
+        if (this.exited)
+            return;
+        this.exited = err;
+        for (const p of this.pending.values())
+            p.reject(err);
+        this.pending.clear();
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let idx = this.buffer.indexOf("\n");
+        while (idx >= 0) {
+            const line = this.buffer.slice(0, idx).trim();
+            this.buffer = this.buffer.slice(idx + 1);
+            if (line)
+                this.onLine(line);
+            idx = this.buffer.indexOf("\n");
+        }
+    }
+    onLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            this.onLog?.(line);
+            return;
+        }
+        if (msg.id !== undefined && msg.method === undefined) {
+            const p = this.pending.get(msg.id);
+            if (p) {
+                this.pending.delete(msg.id);
+                p.resolve(msg);
+            }
+            return;
+        }
+        if (msg.id !== undefined && msg.method) {
+            // 服务端反向请求(sampling / roots 等)不支持,回一个 method not found 免得它挂着
+            this.write({ jsonrpc: "2.0", id: msg.id, error: { code: -32601, message: `Method not supported by u1s1: ${msg.method}` } });
+        }
+    }
+    write(msg) {
+        if (this.exited)
+            throw this.exited;
+        const stdin = this.child?.stdin;
+        if (!stdin || stdin.destroyed)
+            throw new McpError("MCP 服务进程 stdin 已关闭");
+        stdin.write(`${JSON.stringify(msg)}\n`);
+    }
+    request(msg, timeoutMs, signal) {
+        const id = msg.id;
+        const promise = new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            try {
+                this.write(msg);
+            }
+            catch (err) {
+                this.pending.delete(id);
+                reject(err);
+            }
+        });
+        return withTimeout(promise, timeoutMs, signal, msg.method ?? "请求").finally(() => this.pending.delete(id));
+    }
+    async notify(msg) {
+        this.write(msg);
+    }
+    async close() {
+        const child = this.child;
+        if (!child)
+            return;
+        this.fail(new McpError("MCP 连接已关闭"));
+        try {
+            child.stdin?.end();
+        }
+        catch { }
+        // 没 pid = 根本没启动起来(spawn error),不会有 exit 事件,别等
+        if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+            await new Promise((resolve) => {
+                const done = () => {
+                    clearTimeout(soft);
+                    clearTimeout(hard);
+                    resolve();
+                };
+                child.once("exit", done);
+                child.kill();
+                const soft = setTimeout(() => child.kill("SIGKILL"), 2_000);
+                const hard = setTimeout(done, 3_000);
+            });
+        }
+    }
+}
+// ---------------- Streamable HTTP ----------------
+/** 解析 SSE 正文,返回每个 event 的 data 拼接结果 */
+export function parseSseData(body) {
+    const out = [];
+    let data = [];
+    for (const rawLine of body.split(/\r?\n/)) {
+        if (rawLine === "") {
+            if (data.length)
+                out.push(data.join("\n"));
+            data = [];
+            continue;
+        }
+        if (rawLine.startsWith(":"))
+            continue;
+        const idx = rawLine.indexOf(":");
+        const field = idx === -1 ? rawLine : rawLine.slice(0, idx);
+        if (field !== "data")
+            continue;
+        let value = idx === -1 ? "" : rawLine.slice(idx + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        data.push(value);
+    }
+    if (data.length)
+        out.push(data.join("\n"));
+    return out;
+}
+class HttpTransport {
+    url;
+    headers;
+    sessionId;
+    protocolVersion;
+    constructor(url, headers) {
+        this.url = url;
+        this.headers = headers;
+    }
+    setProtocolVersion(v) {
+        this.protocolVersion = v;
+    }
+    buildHeaders() {
+        const h = {
+            "content-type": "application/json",
+            accept: "application/json, text/event-stream",
+            ...this.headers,
+        };
+        if (this.sessionId)
+            h["mcp-session-id"] = this.sessionId;
+        if (this.protocolVersion)
+            h["mcp-protocol-version"] = this.protocolVersion;
+        return h;
+    }
+    async post(msg, timeoutMs, signal) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+        const onAbort = () => ctrl.abort();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            return await fetch(this.url, { method: "POST", headers: this.buildHeaders(), body: JSON.stringify(msg), signal: ctrl.signal });
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw new McpError(`${msg.method ?? "请求"} 已取消`);
+            if (ctrl.signal.aborted)
+                throw new McpError(`${msg.method ?? "请求"} 超过 ${Math.round(timeoutMs / 1000)}s 未响应`);
+            throw new McpError(`连接 ${this.url} 失败:${err.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    async request(msg, timeoutMs, signal) {
+        const resp = await this.post(msg, timeoutMs, signal);
+        const sid = resp.headers.get("mcp-session-id");
+        if (sid)
+            this.sessionId = sid;
+        if (!resp.ok) {
+            const text = (await resp.text().catch(() => "")).slice(0, 300);
+            if (resp.status === 401 || resp.status === 403) {
+                throw new McpError(`服务拒绝访问(HTTP ${resp.status}),请检查 headers 里的鉴权信息${text ? `:${text}` : ""}`, resp.status);
+            }
+            throw new McpError(`HTTP ${resp.status}${text ? `:${text}` : ""}`, resp.status);
+        }
+        const ctype = (resp.headers.get("content-type") ?? "").toLowerCase();
+        const body = await resp.text();
+        const candidates = ctype.includes("text/event-stream") ? parseSseData(body) : [body];
+        for (const raw of candidates) {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            const list = Array.isArray(parsed) ? parsed : [parsed];
+            for (const item of list) {
+                const m = item;
+                if (m && m.id === msg.id && m.method === undefined)
+                    return m;
+            }
+        }
+        throw new McpError(`服务没有返回 ${msg.method ?? "请求"} 的结果(content-type ${ctype || "unknown"})`);
+    }
+    async notify(msg) {
+        const resp = await this.post(msg, 10_000);
+        // 规范要求 202;有些实现回 200/204,都当成功。鉴权失败要冒出来
+        if (resp.status === 401 || resp.status === 403)
+            throw new McpError(`服务拒绝访问(HTTP ${resp.status})`, resp.status);
+        await resp.body?.cancel().catch(() => { });
+    }
+    async close() {
+        if (!this.sessionId)
+            return;
+        try {
+            await fetch(this.url, { method: "DELETE", headers: this.buildHeaders(), signal: AbortSignal.timeout(3_000) });
+        }
+        catch { }
+        this.sessionId = undefined;
+    }
+}
+// ---------------- client ----------------
+/** 把 tools/call 返回的 content 数组压成模型可读的文本 */
+export function contentToText(result) {
+    const rec = asRecord(result) ?? {};
+    const parts = [];
+    const content = Array.isArray(rec["content"]) ? rec["content"] : [];
+    for (const raw of content) {
+        const item = asRecord(raw);
+        if (!item)
+            continue;
+        const type = item["type"];
+        if (type === "text" && typeof item["text"] === "string") {
+            parts.push(item["text"]);
+        }
+        else if (type === "image" || type === "audio") {
+            const data = typeof item["data"] === "string" ? item["data"] : "";
+            parts.push(`[${type} ${String(item["mimeType"] ?? "")} ${Buffer.from(data, "base64").length} bytes, omitted]`);
+        }
+        else if (type === "resource") {
+            const res = asRecord(item["resource"]);
+            if (res && typeof res["text"] === "string")
+                parts.push(res["text"]);
+            else
+                parts.push(`[resource ${String(res?.["uri"] ?? "")} (binary, omitted)]`);
+        }
+        else if (type === "resource_link") {
+            parts.push(`[link] ${String(item["uri"] ?? "")}${item["name"] ? ` ${String(item["name"])}` : ""}`);
+        }
+    }
+    if (parts.length === 0 && rec["structuredContent"] !== undefined) {
+        parts.push(JSON.stringify(rec["structuredContent"], null, 2));
+    }
+    return { text: parts.join("\n").trim(), isError: rec["isError"] === true };
+}
+export function normalizeToolInfo(raw) {
+    const rec = asRecord(raw);
+    if (!rec || typeof rec["name"] !== "string" || !rec["name"])
+        return undefined;
+    const schema = asRecord(rec["inputSchema"]) ?? { type: "object", properties: {} };
+    return {
+        name: rec["name"],
+        description: typeof rec["description"] === "string" ? rec["description"] : "",
+        inputSchema: { ...schema, type: "object" },
+    };
+}
+export class McpClient {
+    name;
+    config;
+    opts;
+    transport;
+    nextId = 1;
+    connectTimeoutMs;
+    callTimeoutMs;
+    connected;
+    info;
+    constructor(name, config, opts = {}) {
+        this.name = name;
+        this.config = config;
+        this.opts = opts;
+        this.connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+        this.callTimeoutMs = opts.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+    }
+    /** 建连并完成 initialize 握手;重复调用返回同一个 promise,失败后可重试 */
+    connect() {
+        if (!this.connected) {
+            this.connected = this.doConnect().catch(async (err) => {
+                this.connected = undefined;
+                await this.close().catch(() => { });
+                throw err;
+            });
+        }
+        return this.connected;
+    }
+    async doConnect() {
+        const transport = this.config.type === "stdio"
+            ? new StdioTransport(this.config.command, this.config.args, this.config.env, this.opts.onLog)
+            : new HttpTransport(this.config.url, this.config.headers);
+        if (transport instanceof StdioTransport)
+            transport.start();
+        this.transport = transport;
+        const result = await this.rpc("initialize", {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "u1s1", version: VERSION },
+        }, this.connectTimeoutMs);
+        const rec = asRecord(result) ?? {};
+        const serverInfo = asRecord(rec["serverInfo"]);
+        const protocolVersion = typeof rec["protocolVersion"] === "string" ? rec["protocolVersion"] : MCP_PROTOCOL_VERSION;
+        if (transport instanceof HttpTransport)
+            transport.setProtocolVersion(protocolVersion);
+        await transport.notify({ jsonrpc: "2.0", method: "notifications/initialized" });
+        this.info = {
+            serverName: typeof serverInfo?.["name"] === "string" ? serverInfo["name"] : undefined,
+            serverVersion: typeof serverInfo?.["version"] === "string" ? serverInfo["version"] : undefined,
+            protocolVersion,
+        };
+        return this.info;
+    }
+    async rpc(method, params, timeoutMs, signal) {
+        const transport = this.transport;
+        if (!transport)
+            throw new McpError("尚未连接");
+        const id = this.nextId++;
+        const resp = await transport.request({ jsonrpc: "2.0", id, method, params }, timeoutMs, signal);
+        if (resp.error) {
+            throw new McpError(`${resp.error.message}${resp.error.data !== undefined ? ` ${JSON.stringify(resp.error.data).slice(0, 300)}` : ""}`, resp.error.code);
+        }
+        return resp.result;
+    }
+    async listTools() {
+        await this.connect();
+        const tools = [];
+        let cursor;
+        for (let page = 0; page < 50; page++) {
+            const result = asRecord(await this.rpc("tools/list", cursor ? { cursor } : {}, this.connectTimeoutMs)) ?? {};
+            for (const raw of Array.isArray(result["tools"]) ? result["tools"] : []) {
+                const tool = normalizeToolInfo(raw);
+                if (tool)
+                    tools.push(tool);
+            }
+            cursor = typeof result["nextCursor"] === "string" && result["nextCursor"] ? result["nextCursor"] : undefined;
+            if (!cursor)
+                break;
+        }
+        return tools;
+    }
+    async callTool(name, args, signal) {
+        await this.connect();
+        const result = await this.rpc("tools/call", { name, arguments: args }, this.callTimeoutMs, signal);
+        return contentToText(result);
+    }
+    async close() {
+        const t = this.transport;
+        this.transport = undefined;
+        this.connected = undefined;
+        if (t)
+            await t.close();
+    }
+}

package/dist/mcp/command.d.ts

@@ -0,0 +1,25 @@
+import { type McpServerConfig } from "./config.js";
+/**
+ * `u1s1 mcp` 子命令:管理自定义 MCP 服务。
+ * add 时先连一次拉工具清单再落盘,坏配置不会拖慢每次启动。
+ */
+export declare function printMcpHelp(): void;
+export declare class McpUsageError extends Error {
+}
+export interface ParsedAdd {
+    name: string;
+    server: McpServerConfig;
+    force: boolean;
+}
+export declare function parseAddArgs(args: string[]): ParsedAdd;
+export interface ImportCandidate {
+    name: string;
+    server: McpServerConfig;
+    source: string;
+}
+/** Claude Code 的 MCP 配置:~/.claude.json(用户级 + 各项目)与项目 .mcp.json */
+export declare function collectClaudeMcpServers(home?: string, cwd?: string): {
+    candidates: ImportCandidate[];
+    unsupported: string[];
+};
+export declare function mcpCommand(args: string[]): Promise<void>;

package/dist/mcp/command.js

@@ -0,0 +1,349 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { formatHomePath } from "../brand.js";
+import { McpClient } from "./client.js";
+import { loadMcpConfig, loadMcpToolCache, maskSecret, MCP_SERVER_NAME_RE, mcpConfigPath, normalizeServerConfig, parseKeyValue, saveMcpConfig, saveMcpToolCache, } from "./config.js";
+import { mcpToolName } from "./tools.js";
+/**
+ * `u1s1 mcp` 子命令:管理自定义 MCP 服务。
+ * add 时先连一次拉工具清单再落盘,坏配置不会拖慢每次启动。
+ */
+export function printMcpHelp() {
+    console.log("");
+    console.log("  配置第三方 MCP 服务,让它提供的工具(搜索、数据库、浏览器…)在对话里直接可用");
+    console.log("");
+    console.log("  用法:");
+    console.log("    u1s1 mcp add 名称 命令 [参数...]        本机命令型服务(stdio),例:");
+    console.log("        u1s1 mcp add tavily --env TAVILY_API_KEY=tvly-xxx npx -y tavily-mcp");
+    console.log("    u1s1 mcp add 名称 --url 地址            HTTP 型服务(Streamable HTTP),例:");
+    console.log("        u1s1 mcp add exa --url https://mcp.exa.ai/mcp --header \"Authorization: Bearer xxx\"");
+    console.log("        --env K=V / --header \"K: V\" 可重复;--force 连接失败也保存");
+    console.log("    u1s1 mcp list                          看已配置的服务和工具");
+    console.log("    u1s1 mcp test 名称                     连一次,列出它提供的工具");
+    console.log("    u1s1 mcp remove 名称                   删除");
+    console.log("    u1s1 mcp import [--dry-run]            从 Claude Code 的配置(~/.claude.json、项目 .mcp.json)导入");
+    console.log("");
+    console.log(`  配置存在 ${formatHomePath(mcpConfigPath())}(与 Claude Code 的 mcpServers 同格式,可手改),`);
+    console.log("  只在本机,不会上传。下次进对话工具即生效,名字形如 mcp_名称_工具。");
+    console.log("  命令型服务会以你的权限在本机运行,只添加可信来源。");
+    console.log("");
+}
+export class McpUsageError extends Error {
+}
+function fail(message) {
+    throw new McpUsageError(message);
+}
+function describeServer(server) {
+    if (server.type === "stdio") {
+        const env = Object.entries(server.env).map(([k, v]) => `${k}=${maskSecret(v)}`);
+        return `${[server.command, ...server.args].join(" ")}${env.length ? `  (env: ${env.join(" ")})` : ""}`;
+    }
+    const headers = Object.keys(server.headers);
+    return `${server.url}${headers.length ? `  (headers: ${headers.join(", ")})` : ""}`;
+}
+async function probe(name, server) {
+    const client = new McpClient(name, server, { onLog: (line) => console.error(`  [${name}] ${line}`) });
+    try {
+        const info = await client.connect();
+        const tools = await client.listTools();
+        return { tools, serverName: info.serverName };
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+function printTools(name, tools) {
+    if (tools.length === 0) {
+        console.log("  (该服务没有提供任何工具)");
+        return;
+    }
+    for (const t of tools) {
+        const desc = t.description.replace(/\s+/g, " ").trim();
+        console.log(`  · ${mcpToolName(name, t.name)}${desc ? `  ${desc.length > 80 ? `${desc.slice(0, 79)}…` : desc}` : ""}`);
+    }
+}
+function cacheTools(name, tools, serverName) {
+    const cache = loadMcpToolCache();
+    cache.servers[name] = { fetchedAt: new Date().toISOString(), serverName, tools };
+    saveMcpToolCache(cache);
+}
+function dropCache(name) {
+    const cache = loadMcpToolCache();
+    if (!cache.servers[name])
+        return;
+    delete cache.servers[name];
+    saveMcpToolCache(cache);
+}
+export function parseAddArgs(args) {
+    const name = args[0];
+    if (!name || name.startsWith("-"))
+        fail("请给服务起个名字,例:u1s1 mcp add tavily npx -y tavily-mcp");
+    if (!MCP_SERVER_NAME_RE.test(name))
+        fail(`服务名只能用小写字母、数字、- 和 _,且以字母或数字开头(最长 32 位):${name}`);
+    let url;
+    const env = {};
+    const headers = {};
+    let force = false;
+    let command;
+    const commandArgs = [];
+    for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (command !== undefined) {
+            commandArgs.push(a);
+            continue;
+        }
+        if (a === "--") {
+            command = args[i + 1];
+            commandArgs.push(...args.slice(i + 2));
+            if (command === undefined)
+                fail("-- 后面要跟命令");
+            break;
+        }
+        if (a === "--force" || a === "-f") {
+            force = true;
+        }
+        else if (a === "--url" || a.startsWith("--url=")) {
+            url = a.includes("=") ? a.slice(6) : args[++i];
+            if (!url)
+                fail("--url 后面要跟地址");
+        }
+        else if (a === "--env" || a === "-e" || a.startsWith("--env=")) {
+            const raw = a.includes("=") && a.startsWith("--env=") ? a.slice(6) : args[++i];
+            const kv = raw ? parseKeyValue(raw, "=") : undefined;
+            if (!kv)
+                fail(`--env 要写成 KEY=VALUE:${raw ?? ""}`);
+            env[kv[0]] = kv[1];
+        }
+        else if (a === "--header" || a === "-H" || a.startsWith("--header=")) {
+            const raw = a.startsWith("--header=") ? a.slice(9) : args[++i];
+            const kv = raw ? parseKeyValue(raw, ":") : undefined;
+            if (!kv)
+                fail(`--header 要写成 "Name: value":${raw ?? ""}`);
+            headers[kv[0]] = kv[1];
+        }
+        else if (a.startsWith("-") && a.length > 1) {
+            fail(`不认识的选项 ${a}(命令自己的参数请放在命令后面,或用 -- 隔开)`);
+        }
+        else {
+            command = a;
+        }
+    }
+    if (url && command)
+        fail("--url 和命令只能二选一");
+    if (url) {
+        if (!/^https?:\/\//i.test(url))
+            fail(`--url 必须是 http(s) 地址:${url}`);
+        if (Object.keys(env).length)
+            fail("HTTP 型服务不支持 --env,鉴权请用 --header");
+        return { name, server: { type: "http", url, headers }, force };
+    }
+    if (!command)
+        fail("请给出启动命令(如 npx -y some-mcp-server)或 --url 地址");
+    if (Object.keys(headers).length)
+        fail("命令型服务不支持 --header,请用 --env 传密钥");
+    return { name, server: { type: "stdio", command, args: commandArgs, env }, force };
+}
+async function addCommand(args) {
+    const { name, server, force } = parseAddArgs(args);
+    const config = loadMcpConfig();
+    const existed = Boolean(config.mcpServers[name]);
+    console.log(`${existed ? "更新" : "添加"} MCP 服务 ${name}:${describeServer(server)}`);
+    console.log("连接中…");
+    let tools = [];
+    let serverName;
+    let probed = false;
+    try {
+        ({ tools, serverName } = await probe(name, server));
+        probed = true;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!force)
+            fail(`连接失败,未保存:${message}\n  确认命令/地址和密钥无误后重试;想先保存加 --force`);
+        console.error(`⚠ 连接失败:${message}\n  已按 --force 保存,进对话前请用 u1s1 mcp test ${name} 确认可用`);
+    }
+    config.mcpServers[name] = server;
+    saveMcpConfig(config);
+    if (probed) {
+        cacheTools(name, tools, serverName);
+        console.log(`✓ 已连接${serverName ? ` ${serverName}` : ""},提供 ${tools.length} 个工具:`);
+        printTools(name, tools);
+    }
+    else {
+        dropCache(name);
+    }
+    console.log(`✓ 已保存到 ${formatHomePath(mcpConfigPath())},下次进入对话即可使用`);
+    if (server.type === "stdio")
+        console.log("  提示:命令型服务会以你的权限在本机运行,只添加可信来源。");
+}
+function listCommand() {
+    const config = loadMcpConfig();
+    const names = Object.keys(config.mcpServers);
+    if (names.length === 0) {
+        console.log("还没有配置 MCP 服务。用 u1s1 mcp add 添加,或 u1s1 mcp import 从 Claude Code 导入。");
+        return;
+    }
+    const cache = loadMcpToolCache();
+    console.log(`已配置 ${names.length} 个 MCP 服务(${formatHomePath(mcpConfigPath())}):`);
+    for (const name of names) {
+        const server = config.mcpServers[name];
+        const cached = cache.servers[name];
+        console.log("");
+        console.log(`${name}  [${server.type}]  ${describeServer(server)}`);
+        if (!cached) {
+            console.log("  工具清单尚未获取(进对话时会自动连一次;也可 u1s1 mcp test 看看)");
+            continue;
+        }
+        console.log(`  ${cached.tools.length} 个工具(${cached.fetchedAt.slice(0, 16).replace("T", " ")} 获取):`);
+        printTools(name, cached.tools);
+    }
+}
+async function testCommand(name) {
+    if (!name)
+        fail("用法:u1s1 mcp test 名称");
+    const config = loadMcpConfig();
+    const server = config.mcpServers[name];
+    if (!server)
+        fail(`没有叫 ${name} 的 MCP 服务,u1s1 mcp list 看看已有的`);
+    console.log(`连接 ${name}:${describeServer(server)}`);
+    const started = Date.now();
+    let tools;
+    let serverName;
+    try {
+        ({ tools, serverName } = await probe(name, server));
+    }
+    catch (err) {
+        fail(`连接失败:${err instanceof Error ? err.message : String(err)}`);
+    }
+    cacheTools(name, tools, serverName);
+    console.log(`✓ 连接成功${serverName ? `(${serverName})` : ""},${Date.now() - started} ms,提供 ${tools.length} 个工具:`);
+    printTools(name, tools);
+}
+function removeCommand(name) {
+    if (!name)
+        fail("用法:u1s1 mcp remove 名称");
+    const config = loadMcpConfig();
+    if (!config.mcpServers[name])
+        fail(`没有叫 ${name} 的 MCP 服务`);
+    delete config.mcpServers[name];
+    saveMcpConfig(config);
+    dropCache(name);
+    console.log(`✓ 已删除 ${name}`);
+}
+/** Claude Code 的 MCP 配置:~/.claude.json(用户级 + 各项目)与项目 .mcp.json */
+export function collectClaudeMcpServers(home = homedir(), cwd = process.cwd()) {
+    const candidates = [];
+    const unsupported = [];
+    const seen = new Set();
+    const take = (servers, source) => {
+        if (!servers || typeof servers !== "object")
+            return;
+        for (const [name, raw] of Object.entries(servers)) {
+            const key = name.toLowerCase();
+            if (seen.has(key))
+                continue;
+            const server = normalizeServerConfig(raw);
+            if (!server) {
+                unsupported.push(`${name}(${source})`);
+                continue;
+            }
+            if (!MCP_SERVER_NAME_RE.test(name)) {
+                unsupported.push(`${name}(${source},名字不合规)`);
+                continue;
+            }
+            seen.add(key);
+            candidates.push({ name, server, source });
+        }
+    };
+    const readJson = (path) => {
+        if (!existsSync(path))
+            return undefined;
+        try {
+            const v = JSON.parse(readFileSync(path, "utf8"));
+            return v && typeof v === "object" ? v : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const project = readJson(join(cwd, ".mcp.json"));
+    take(project?.["mcpServers"], formatHomePath(join(cwd, ".mcp.json")));
+    const user = readJson(join(home, ".claude.json"));
+    const projects = user?.["projects"];
+    if (projects && typeof projects === "object") {
+        const entry = projects[resolve(cwd)];
+        if (entry && typeof entry === "object")
+            take(entry["mcpServers"], "~/.claude.json 项目配置");
+    }
+    take(user?.["mcpServers"], "~/.claude.json");
+    return { candidates, unsupported };
+}
+async function importCommand(args) {
+    const dryRun = args.includes("--dry-run");
+    const { candidates, unsupported } = collectClaudeMcpServers();
+    for (const u of unsupported)
+        console.log(`⚠ 跳过 ${u}:只支持命令型(stdio)和 HTTP 型服务`);
+    if (candidates.length === 0) {
+        console.log("没有在 Claude Code 的配置里找到可导入的 MCP 服务。");
+        return;
+    }
+    const config = loadMcpConfig();
+    console.log(`找到 ${candidates.length} 个 MCP 服务:`);
+    for (const c of candidates) {
+        const tag = config.mcpServers[c.name] ? "(已存在,将覆盖)" : "";
+        console.log(`  ${c.name}  ${describeServer(c.server)}  ← ${c.source} ${tag}`);
+    }
+    if (dryRun) {
+        console.log("--dry-run:未写盘");
+        return;
+    }
+    for (const c of candidates)
+        config.mcpServers[c.name] = c.server;
+    saveMcpConfig(config);
+    console.log(`✓ 已保存到 ${formatHomePath(mcpConfigPath())}`);
+    let failed = 0;
+    for (const c of candidates) {
+        process.stdout.write(`连接 ${c.name}… `);
+        try {
+            const { tools, serverName } = await probe(c.name, c.server);
+            cacheTools(c.name, tools, serverName);
+            console.log(`✓ ${tools.length} 个工具`);
+        }
+        catch (err) {
+            failed += 1;
+            dropCache(c.name);
+            console.log(`✗ ${(err instanceof Error ? err.message : String(err)).split("\n")[0]}`);
+        }
+    }
+    if (failed)
+        console.log(`${failed} 个服务连接失败,进对话前请用 u1s1 mcp test 名称 排查(失败的服务不会影响其他工具)`);
+}
+export async function mcpCommand(args) {
+    const sub = args[0];
+    try {
+        if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
+            printMcpHelp();
+            return;
+        }
+        if (sub === "add")
+            return await addCommand(args.slice(1));
+        if (sub === "list" || sub === "ls")
+            return listCommand();
+        if (sub === "test")
+            return await testCommand(args[1]);
+        if (sub === "remove" || sub === "rm" || sub === "delete")
+            return removeCommand(args[1]);
+        if (sub === "import")
+            return await importCommand(args.slice(1));
+        fail(`不认识的子命令 ${sub},u1s1 mcp --help 看用法`);
+    }
+    catch (err) {
+        if (err instanceof McpUsageError) {
+            console.error(`✗ ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+}

package/dist/mcp/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 自定义 MCP 服务配置:~/.u1s1/mcp.json,形状与 Claude Code 的 mcpServers 一致,
+ * 方便手改或从别的工具照抄。里面可能有 API Key(env / headers),所以走
+ * writePrivateFile(0600),并且永远不上传、不进遥测。
+ */
+export interface McpStdioServer {
+    type: "stdio";
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+}
+export interface McpHttpServer {
+    type: "http";
+    url: string;
+    headers: Record<string, string>;
+}
+export type McpServerConfig = McpStdioServer | McpHttpServer;
+export interface McpConfig {
+    mcpServers: Record<string, McpServerConfig>;
+}
+export interface McpToolInfo {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface McpCachedServer {
+    fetchedAt: string;
+    serverName?: string;
+    tools: McpToolInfo[];
+}
+export interface McpToolCache {
+    version: 1;
+    servers: Record<string, McpCachedServer>;
+}
+/** 服务名同时用作工具名前缀,限成模型 API 都接受的字符。 */
+export declare const MCP_SERVER_NAME_RE: RegExp;
+export declare function mcpConfigPath(): string;
+export declare function mcpCachePath(): string;
+/**
+ * 把一条 mcpServers 记录规整成内部形状。兼容 Claude Code 的写法:
+ * `{command,args,env}`(stdio)、`{type:"http",url,headers}`;`type:"sse"`(旧版
+ * SSE 传输)不支持,返回 undefined 让调用方提示。
+ */
+export declare function normalizeServerConfig(raw: unknown): McpServerConfig | undefined;
+export declare function parseMcpConfig(raw: unknown): {
+    config: McpConfig;
+    invalid: string[];
+};
+export declare function loadMcpConfig(path?: string): McpConfig;
+/** 写盘时保留用户手写的其他顶层字段,只换 mcpServers。 */
+export declare function saveMcpConfig(config: McpConfig, path?: string): void;
+export declare function loadMcpToolCache(path?: string): McpToolCache;
+export declare function saveMcpToolCache(cache: McpToolCache, path?: string): void;
+/** 工具列表是否变化(名称 + 参数结构),用来决定要不要提示重启。 */
+export declare function sameToolList(a: McpToolInfo[], b: McpToolInfo[]): boolean;
+/** `K=V` → [K, V];没有 = 或 K 为空返回 undefined。 */
+export declare function parseKeyValue(raw: string, sep: "=" | ":"): [string, string] | undefined;
+/** 展示用:把 env / headers 里像密钥的值打码,列表和日志都不能露 Key。 */
+export declare function maskSecret(value: string): string;

package/dist/mcp/extension.d.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+interface RegisterResult {
+    registered: Array<{
+        server: string;
+        tools: number;
+        fromCache: boolean;
+    }>;
+    failed: Array<{
+        server: string;
+        error: string;
+    }>;
+}
+export declare function registerMcpServers(pi: ExtensionAPI): Promise<RegisterResult>;
+export {};

package/dist/mcp/extension.js

@@ -0,0 +1,128 @@
+import { loadMcpConfig, loadMcpToolCache, sameToolList, saveMcpToolCache, } from "./config.js";
+import { McpClient } from "./client.js";
+import { createMcpToolSet } from "./tools.js";
+/**
+ * 扩展入口:启动时把 ~/.u1s1/mcp.json 里每个服务的工具注册进 pi。
+ * - 有缓存(上次 add/test/启动拉过清单)的服务直接按缓存注册,零启动开销,首次调用再连;
+ * - 没缓存的服务并行连一次拉清单(限时),失败只提示不阻塞;
+ * - session_start 后后台刷新一遍清单,变了就更新缓存并提示"重启后生效"。
+ */
+const FIRST_LOAD_TIMEOUT_MS = 15_000;
+async function fetchTools(server, config, timeoutMs) {
+    const client = new McpClient(server, config, { connectTimeoutMs: timeoutMs });
+    try {
+        const info = await client.connect();
+        const tools = await client.listTools();
+        return { tools, serverName: info.serverName };
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+export async function registerMcpServers(pi) {
+    const result = { registered: [], failed: [] };
+    const config = loadMcpConfig();
+    const names = Object.keys(config.mcpServers);
+    if (names.length === 0)
+        return result;
+    const cache = loadMcpToolCache();
+    const sets = [];
+    const warnings = [];
+    let ui;
+    const warn = (message) => {
+        if (ui) {
+            try {
+                ui.notify(message, "warning");
+                return;
+            }
+            catch { }
+        }
+        warnings.push(message);
+    };
+    const register = (server, serverConfig, tools, fromCache) => {
+        const set = createMcpToolSet(server, serverConfig, tools);
+        for (const tool of set.tools)
+            pi.registerTool(tool);
+        sets.push(set);
+        result.registered.push({ server, tools: tools.length, fromCache });
+    };
+    let cacheDirty = false;
+    await Promise.all(names.map(async (server) => {
+        const serverConfig = config.mcpServers[server];
+        const cached = cache.servers[server];
+        if (cached) {
+            register(server, serverConfig, cached.tools, true);
+            return;
+        }
+        try {
+            const { tools, serverName } = await fetchTools(server, serverConfig, FIRST_LOAD_TIMEOUT_MS);
+            cache.servers[server] = { fetchedAt: new Date().toISOString(), serverName, tools };
+            cacheDirty = true;
+            register(server, serverConfig, tools, false);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.failed.push({ server, error: message });
+            warnings.push(`MCP 服务 ${server} 连接失败,本次会话不可用:${message.split("\n")[0]}\n  用 u1s1 mcp test ${server} 排查`);
+        }
+    }));
+    if (cacheDirty) {
+        try {
+            saveMcpToolCache(pruneCache(cache, names));
+        }
+        catch { }
+    }
+    let refreshed = false;
+    pi.on("session_start", (_event, ctx) => {
+        if (ctx.hasUI)
+            ui = ctx.ui;
+        for (const w of warnings.splice(0)) {
+            try {
+                ui?.notify(w, "warning");
+            }
+            catch { }
+        }
+        if (refreshed)
+            return;
+        refreshed = true;
+        void refreshCache(config, cache, warn);
+    });
+    pi.on("session_shutdown", async () => {
+        await Promise.all(sets.map((s) => s.close().catch(() => { })));
+    });
+    return result;
+}
+function pruneCache(cache, keep) {
+    const servers = {};
+    for (const name of keep)
+        if (cache.servers[name])
+            servers[name] = cache.servers[name];
+    return { version: 1, servers };
+}
+/** 后台刷新工具清单:只写缓存,变化了提示一句,不动本会话已注册的工具 */
+async function refreshCache(config, cache, warn) {
+    const names = Object.keys(config.mcpServers);
+    let dirty = false;
+    const changed = [];
+    await Promise.all(names.map(async (server) => {
+        try {
+            const { tools, serverName } = await fetchTools(server, config.mcpServers[server], FIRST_LOAD_TIMEOUT_MS);
+            const prev = cache.servers[server];
+            if (prev && !sameToolList(prev.tools, tools))
+                changed.push(server);
+            cache.servers[server] = { fetchedAt: new Date().toISOString(), serverName, tools };
+            dirty = true;
+        }
+        catch {
+            // 后台刷新失败不打扰:真正调用时会报清楚
+        }
+    }));
+    if (dirty) {
+        try {
+            saveMcpToolCache(pruneCache(cache, names));
+        }
+        catch { }
+    }
+    if (changed.length)
+        warn(`MCP 服务 ${changed.join("、")} 的工具列表有变化,重新进入会话后生效`);
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,22 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import { McpClient, type McpClientOptions } from "./client.js";
+import type { McpServerConfig, McpToolInfo } from "./config.js";
+/**
+ * 把 MCP 服务的工具挂成 pi 工具。名字统一 `mcp_<服务>_<工具>`,让模型一眼看出来源;
+ * 连接是惰性的:注册时只用缓存的工具清单,第一次调用才真正拉起服务。
+ * 结果上限放到内置搜索(3 万字)的三倍多——用户抱怨的正是"动不动就截断"。
+ */
+export declare const MCP_MAX_TEXT_CHARS = 100000;
+export declare function mcpToolName(server: string, tool: string): string;
+export declare function truncateMcpText(text: string, max?: number): string;
+/** 模型 API 只认 object 顶层;$schema 之类元字段去掉,缺 properties 补空 */
+export declare function toParameterSchema(inputSchema: Record<string, unknown>): TSchema;
+export type McpToolSetOptions = McpClientOptions;
+export interface McpToolSet {
+    server: string;
+    tools: ToolDefinition[];
+    client: McpClient;
+    close(): Promise<void>;
+}
+export declare function createMcpToolSet(server: string, config: McpServerConfig, tools: McpToolInfo[], opts?: McpToolSetOptions): McpToolSet;

package/dist/mcp/tools.js

@@ -0,0 +1,96 @@
+import { Text } from "@earendil-works/pi-tui";
+import { compactResultRender } from "../tools.js";
+import { McpClient } from "./client.js";
+/**
+ * 把 MCP 服务的工具挂成 pi 工具。名字统一 `mcp_<服务>_<工具>`,让模型一眼看出来源;
+ * 连接是惰性的:注册时只用缓存的工具清单,第一次调用才真正拉起服务。
+ * 结果上限放到内置搜索(3 万字)的三倍多——用户抱怨的正是"动不动就截断"。
+ */
+export const MCP_MAX_TEXT_CHARS = 100_000;
+const MODEL_TOOL_NAME_MAX = 64;
+export function mcpToolName(server, tool) {
+    const clean = tool.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "tool";
+    return `mcp_${server}_${clean}`.slice(0, MODEL_TOOL_NAME_MAX);
+}
+export function truncateMcpText(text, max = MCP_MAX_TEXT_CHARS) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max)}\n\n…（MCP 工具返回内容过长已截断，共 ${text.length} 字符，保留前 ${max} 字符）`;
+}
+/** 模型 API 只认 object 顶层;$schema 之类元字段去掉,缺 properties 补空 */
+export function toParameterSchema(inputSchema) {
+    const { $schema: _drop, ...rest } = inputSchema;
+    const schema = { ...rest, type: "object" };
+    if (!schema["properties"] || typeof schema["properties"] !== "object")
+        schema["properties"] = {};
+    return schema;
+}
+function previewArgs(params) {
+    let s;
+    try {
+        s = JSON.stringify(params) ?? "";
+    }
+    catch {
+        s = "";
+    }
+    s = s.replace(/\s*\n\s*/g, " ");
+    return s.length > 100 ? `${s.slice(0, 99)}…` : s;
+}
+export function createMcpToolSet(server, config, tools, opts = {}) {
+    let client = new McpClient(server, config, opts);
+    const definitions = [];
+    async function call(tool, params, signal) {
+        try {
+            return await client.callTool(tool.name, params, signal);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // 进程退出 / 连接断了:丢掉旧客户端,下次调用重新拉起
+            if (/已退出|已关闭|stdin/.test(message)) {
+                const old = client;
+                client = new McpClient(server, config, opts);
+                old.close().catch(() => { });
+            }
+            throw new Error(`MCP 服务 ${server} 调用 ${tool.name} 失败:${message}`, { cause: err });
+        }
+    }
+    for (const tool of tools) {
+        const name = mcpToolName(server, tool.name);
+        const description = tool.description.trim() || `Tool "${tool.name}" from MCP server "${server}".`;
+        definitions.push({
+            name,
+            label: `MCP ${server}:${tool.name}`,
+            description: description.length > 2_000 ? `${description.slice(0, 2_000)}…` : description,
+            parameters: toParameterSchema(tool.inputSchema),
+            renderShell: "self",
+            renderCall() {
+                return new Text("", 0, 0);
+            },
+            renderResult(result, options, theme, context) {
+                const d = result.details;
+                const args = d?.args ? ` ${d.args}` : "";
+                const n = typeof d?.chars === "number" ? ` · ${d.chars} 字符${d.truncated ? "(已截断)" : ""}` : "";
+                return compactResultRender({ result, options, theme, context, summaryLine: `🔌 ${server}:${tool.name}${args}${n}` });
+            },
+            async execute(_toolCallId, params, signal) {
+                const args = (params && typeof params === "object" ? params : {});
+                const res = await call(tool, args, signal);
+                if (res.isError)
+                    throw new Error(`MCP 服务 ${server} 的 ${tool.name} 返回错误:${res.text || "(无详情)"}`);
+                const text = res.text || "(empty result)";
+                return {
+                    content: [{ type: "text", text: truncateMcpText(text) }],
+                    details: { args: previewArgs(args), chars: text.length, truncated: text.length > MCP_MAX_TEXT_CHARS },
+                };
+            },
+        });
+    }
+    return {
+        server,
+        tools: definitions,
+        get client() {
+            return client;
+        },
+        close: () => client.close(),
+    };
+}

package/dist/web.js

@@ -1,7 +1,7 @@
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { cleanupBrandThemes, endpointKeyEnv, ensureAuthCredential, ensureBrandPrompt, ensureWorkflowPromptTemplate, ensureDefaultSettings, ensureProviderModels, scrubForeignProviderEnv, writeAttributionExtension, writeWebToolsExtension, } from "./agent-setup.js";
+import { cleanupBrandThemes, endpointKeyEnv, ensureAuthCredential, ensureBrandPrompt, ensureWorkflowPromptTemplate, ensureDefaultSettings, ensureProviderModels, scrubForeignProviderEnv, writeAttributionExtension, writeMcpExtension, writeWebToolsExtension, } from "./agent-setup.js";
 import { agentDir, apiModelToDef, MODELS, resolvePreferredModel, setModelsFromApi, u1s1Dir, writeAgentDefaultModel, } from "./config.js";
 import { ensureSearchTools } from "./search-tools.js";
 import { ensureUsableShell } from "./shell-doctor.js";
@@ -98,6 +98,8 @@ export async function prepareWebEnv(cfg) {
     });
     // OpenRouter 应用归因：直连流量计入 u1s1 的公开排行（与 TUI 同源）
     writeAttributionExtension();
+    // 自定义 MCP 服务的工具(与 TUI 同源)
+    writeMcpExtension();
     // Desktop App 新会话从 settings.json 的 defaultModel 取模型(TUI 是每次传 --model),
     // 确保它有值;resolvePreferredModel 优先尊重已有的 in-session 选择,不会回退覆盖。
     const pref = resolvePreferredModel(cfg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u1s1-cli",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "u1s1 — 有一说一,最省心的 AI 编程搭子。终端里用中文说需求,AI 帮你读文件、改代码、跑命令。",
   "type": "module",
   "bin": {