@steerable/agent-shell 0.6.52 → 0.6.55

package/dist/mcp-executor.js

@@ -1,7 +1,10 @@
 import { execFileSync } from 'child_process';
+import { createHash } from 'node:crypto';
 import { createRequire } from 'module';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport, StreamableHTTPError, } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
 // In ESM there is no `__filename` global; use the module URL to seed a local
 // CommonJS require() so we can `require.resolve()` MCP server packages that
 // ship as CJS (npx -y <pkg> targets, e.g. apple-notes-mcp).
@@ -14,6 +17,14 @@ const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
  * timed out"（2026-07-31 用户实测遇到）。放宽到 3 分钟覆盖冷启动下载。
  */
 const MCP_REQUEST_TIMEOUT_MS = 3 * 60 * 1000;
+export const MAX_MCP_SERVER_TOOLS = 64;
+const CONNECT_RETRY_DELAYS_MS = [0, 250, 1_000];
+const DEFAULT_RECONNECTION = {
+    initialReconnectionDelay: 500,
+    maxReconnectionDelay: 30_000,
+    reconnectionDelayGrowFactor: 2,
+    maxRetries: 10,
+};
 /**
  * 给超时类错误追加可操作的排查提示。独立成纯函数便于单测。
  */
@@ -54,6 +65,7 @@ function tryResolveBundled(config) {
     try {
         const entryPath = localRequire.resolve(pkgName);
         return {
+            transport: 'stdio',
             command: process.execPath,
             args: [entryPath, ...extraArgs],
             env: { ...config.env },
@@ -64,8 +76,43 @@ function tryResolveBundled(config) {
         return null;
     }
 }
-function configKey(cfg) {
-    return `${cfg.command}::${(cfg.args ?? []).join(' ')}`;
+export function resolveHttpHeaders(config, env = process.env) {
+    const headers = { ...(config.headers ?? {}) };
+    for (const [header, variable] of Object.entries(config.headersFromEnv ?? {})) {
+        const value = env[variable];
+        if (!value)
+            throw new Error(`MCP header environment variable "${variable}" is not set`);
+        headers[header] = value;
+    }
+    if (config.bearerTokenEnvVar) {
+        const token = env[config.bearerTokenEnvVar];
+        if (!token) {
+            throw new Error(`MCP bearer token environment variable "${config.bearerTokenEnvVar}" is not set`);
+        }
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+}
+export function mcpConfigKey(rawConfig, env = process.env) {
+    const config = normalizeExecutorConfig(rawConfig);
+    const material = config.transport === 'stdio'
+        ? {
+            transport: config.transport,
+            command: config.command,
+            args: config.args ?? [],
+            env: config.env ?? {},
+            cwd: config.cwd ?? '',
+        }
+        : {
+            transport: config.transport,
+            url: config.url,
+            headers: resolveHttpHeaders(config, env),
+            reconnect: config.reconnect ?? {},
+        };
+    return createHash('sha256').update(JSON.stringify(material)).digest('hex');
+}
+function normalizeExecutorConfig(config) {
+    return 'transport' in config ? config : { ...config, transport: 'stdio' };
 }
 /**
  * Pure eviction predicate, split out so it's unit-testable without spinning
@@ -77,6 +124,83 @@ export function shouldEvictMcpConnection(entry, now, idleTimeoutMs) {
         return false;
     return now - entry.lastUsed > idleTimeoutMs;
 }
+function startupError(config, message) {
+    const prefix = config.transport === 'stdio' ? 'MCP server startup failed' : 'MCP HTTP connection failed';
+    return config.transport === 'stdio'
+        ? withMcpTroubleshootHint(`${prefix}: ${message}`)
+        : `${prefix}: ${message}`;
+}
+function parseHttpUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`invalid MCP HTTP URL: ${raw}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error('MCP HTTP URL must use http or https');
+    }
+    if (url.username || url.password) {
+        throw new Error('MCP HTTP URL must not contain credentials');
+    }
+    return url;
+}
+function sameOriginFetch(origin) {
+    return async (input, init) => {
+        let current = new URL(String(input), origin);
+        for (let redirects = 0; redirects <= 5; redirects += 1) {
+            const response = await fetch(current, { ...init, redirect: 'manual' });
+            if (response.status < 300 || response.status >= 400)
+                return response;
+            const location = response.headers.get('location');
+            if (!location)
+                return response;
+            const next = new URL(location, current);
+            if (next.origin !== origin.origin) {
+                throw new Error(`MCP HTTP redirect crossed origin: ${origin.origin} -> ${next.origin}`);
+            }
+            current = next;
+        }
+        throw new Error('MCP HTTP redirect limit exceeded');
+    };
+}
+async function connectWithRetry(create) {
+    let lastError;
+    for (const delayMs of CONNECT_RETRY_DELAYS_MS) {
+        if (delayMs > 0)
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        const generation = create();
+        try {
+            await generation.client.connect(generation.transport, {
+                timeout: MCP_REQUEST_TIMEOUT_MS,
+            });
+            return generation;
+        }
+        catch (error) {
+            lastError = error;
+            try {
+                await generation.transport.close();
+            }
+            catch {
+                // Failed negotiation can leave an already-closed transport.
+            }
+            if (!isRetryableConnectError(error))
+                break;
+        }
+    }
+    throw lastError;
+}
+function isRetryableConnectError(error) {
+    if (error instanceof StreamableHTTPError) {
+        return error.code !== undefined && [408, 429, 500, 502, 503, 504].includes(error.code);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (/401|403|unauthorized|forbidden|invalid|protocol|parse|deserialize/i.test(message)) {
+        return false;
+    }
+    return /408|429|500|502|503|504|fetch failed|ECONN|ENOTFOUND|ETIMEDOUT|closed/i.test(message);
+}
 function coerceArgs(args, schema) {
     if (!schema?.inputSchema?.properties)
         return args;
@@ -100,20 +224,24 @@ function coerceArgs(args, schema) {
     }
     return out;
 }
-class McpExecutor {
+export class McpExecutor {
     pool = new Map();
     cleanupTimer = null;
     constructor() {
         this.cleanupTimer = setInterval(() => this.evictIdle(), 60_000);
     }
-    async executeTool(config, toolName, toolArgs) {
+    async executeTool(rawConfig, toolName, toolArgs) {
+        const config = normalizeExecutorConfig(rawConfig);
         let entry;
         try {
             entry = await this.getOrCreate(config);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            return { success: false, error: withMcpTroubleshootHint(`MCP server startup failed: ${msg}`) };
+            return {
+                success: false,
+                error: startupError(config, msg),
+            };
         }
         entry.inflight += 1;
         try {
@@ -136,7 +264,7 @@ class McpExecutor {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            const key = configKey(config);
+            const key = mcpConfigKey(config);
             await this.closeEntry(key);
             return { success: false, error: withMcpTroubleshootHint(`Tool execution failed: ${msg}`) };
         }
@@ -145,26 +273,31 @@ class McpExecutor {
             entry.lastUsed = Date.now();
         }
     }
-    async listTools(config) {
+    async listTools(rawConfig, onChanged, onUnavailable) {
+        const config = normalizeExecutorConfig(rawConfig);
         let entry;
         try {
             entry = await this.getOrCreate(config);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            return { success: false, error: withMcpTroubleshootHint(`MCP server startup failed: ${msg}`) };
+            return { success: false, error: startupError(config, msg) };
         }
         entry.inflight += 1;
+        if (onChanged)
+            entry.listeners.add(onChanged);
+        if (onUnavailable)
+            entry.unavailableListeners.add(onUnavailable);
         try {
-            const listing = await entry.client.listTools(undefined, { timeout: MCP_REQUEST_TIMEOUT_MS });
+            const tools = await this.refreshEntryTools(entry);
             return {
                 success: true,
-                tools: listing.tools.map(t => ({ name: t.name, description: t.description ?? '', inputSchema: t.inputSchema })),
+                tools,
             };
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            const key = configKey(config);
+            const key = mcpConfigKey(config);
             await this.closeEntry(key);
             return { success: false, error: withMcpTroubleshootHint(`List tools failed: ${msg}`) };
         }
@@ -174,54 +307,128 @@ class McpExecutor {
         }
     }
     async getOrCreate(config) {
-        const key = configKey(config);
+        const key = mcpConfigKey(config);
         const existing = this.pool.get(key);
         if (existing)
             return existing;
-        const resolved = tryResolveBundled(config) ?? config;
-        if (!commandExists(resolved.command)) {
-            const hint = COMMAND_HINTS[config.command] || `请确保 ${config.command} 已安装并在 PATH 中`;
-            throw new Error(`命令 "${config.command}" 不可用。${hint}`);
-        }
-        const transport = new StdioClientTransport({
-            command: resolved.command,
-            args: resolved.args,
-            env: { ...process.env, ...(resolved.env ?? {}) },
-            cwd: resolved.cwd ?? undefined,
-            stderr: 'pipe',
-        });
-        const client = new Client({ name: 'agent-shell', version: '1.0.0' }, { capabilities: {} });
-        await client.connect(transport, { timeout: MCP_REQUEST_TIMEOUT_MS });
-        const toolSchemas = new Map();
-        try {
-            const listing = await client.listTools(undefined, { timeout: MCP_REQUEST_TIMEOUT_MS });
-            for (const t of listing.tools) {
-                toolSchemas.set(t.name, {
-                    name: t.name,
-                    inputSchema: t.inputSchema,
-                });
+        const { client, transport } = await connectWithRetry(() => ({
+            transport: this.createTransport(config),
+            client: new Client({ name: 'agent-shell', version: '1.0.0' }, { capabilities: {} }),
+        }));
+        const entry = {
+            client,
+            transport,
+            httpTransport: transport instanceof StreamableHTTPClientTransport ? transport : undefined,
+            lastUsed: Date.now(),
+            key,
+            toolSchemas: new Map(),
+            inflight: 0,
+            listeners: new Set(),
+            unavailableListeners: new Set(),
+            syncChain: Promise.resolve(),
+        };
+        await this.refreshEntryTools(entry);
+        client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+            try {
+                const tools = await this.refreshEntryTools(entry);
+                for (const listener of entry.listeners)
+                    listener(tools);
             }
-        }
-        catch {
-            // no-op
-        }
-        const entry = { client, transport, lastUsed: Date.now(), key, toolSchemas, inflight: 0 };
+            catch {
+                // Preserve the previous generation; a later notification/manual refresh can recover.
+            }
+        });
         this.pool.set(key, entry);
-        transport.onclose = () => {
+        client.onclose = () => {
+            if (this.pool.get(key) !== entry)
+                return;
             this.pool.delete(key);
+            for (const listener of entry.unavailableListeners) {
+                listener('MCP connection closed after reconnect attempts were exhausted');
+            }
         };
         return entry;
     }
+    createTransport(config) {
+        if (config.transport === 'stdio') {
+            const resolved = tryResolveBundled(config) ?? config;
+            if (!commandExists(resolved.command)) {
+                const hint = COMMAND_HINTS[config.command] || `请确保 ${config.command} 已安装并在 PATH 中`;
+                throw new Error(`命令 "${config.command}" 不可用。${hint}`);
+            }
+            return new StdioClientTransport({
+                command: resolved.command,
+                args: resolved.args,
+                env: { ...process.env, ...(resolved.env ?? {}) },
+                cwd: resolved.cwd ?? undefined,
+                stderr: 'pipe',
+            });
+        }
+        const url = parseHttpUrl(config.url);
+        const headers = resolveHttpHeaders(config);
+        return new StreamableHTTPClientTransport(url, {
+            requestInit: { headers },
+            fetch: sameOriginFetch(url),
+            reconnectionOptions: {
+                ...DEFAULT_RECONNECTION,
+                ...(config.reconnect ?? {}),
+            },
+        });
+    }
+    async refreshEntryTools(entry) {
+        let result;
+        const run = entry.syncChain.then(async () => {
+            result = await this.fetchEntryTools(entry);
+        });
+        entry.syncChain = run.catch(() => { });
+        await run;
+        return result ?? [];
+    }
+    async fetchEntryTools(entry) {
+        const tools = [];
+        let cursor;
+        do {
+            const listing = await entry.client.listTools(cursor ? { cursor } : undefined, { timeout: MCP_REQUEST_TIMEOUT_MS });
+            for (const tool of listing.tools) {
+                tools.push({
+                    name: tool.name,
+                    description: tool.description ?? '',
+                    inputSchema: tool.inputSchema,
+                });
+                if (tools.length > MAX_MCP_SERVER_TOOLS) {
+                    throw new Error(`MCP server advertises more than the per-server cap of ${MAX_MCP_SERVER_TOOLS} tools`);
+                }
+            }
+            cursor = listing.nextCursor;
+        } while (cursor);
+        const nextSchemas = new Map();
+        for (const tool of tools) {
+            nextSchemas.set(tool.name, {
+                name: tool.name,
+                inputSchema: tool.inputSchema,
+            });
+        }
+        entry.toolSchemas = nextSchemas;
+        return tools;
+    }
     async closeEntry(key) {
         const entry = this.pool.get(key);
         if (!entry)
             return;
         this.pool.delete(key);
+        try {
+            if (entry.httpTransport?.sessionId) {
+                await entry.httpTransport.terminateSession();
+            }
+        }
+        catch {
+            // Session DELETE is advisory; transport closure still must happen.
+        }
         try {
             await entry.client.close();
         }
         catch {
-            // ignore
+            // An already-closed transport needs no further cleanup.
         }
     }
     /** 关闭连接池中的所有连接（应用退出 / 测试收尾时调用）。 */

package/dist/mcp-server-registry.d.ts

@@ -5,31 +5,76 @@
  * 持久化在 userData/agent-mcp-servers.json。已启用服务的工具会经
  * ToolRouter 以 `mcp__<serverKey>__<toolName>` 一等工具身份暴露给模型。
  *
- * 存储通过 {@link McpServerKvStore} 接口注入：main.ts 用 electron-store
- * 实现，单测用内存实现——本模块不 import electron，保持纯 Node 可测。
+ * 存储通过 {@link McpServerKvStore} 接口注入：宿主用 json-store 实现，
+ * 单测用内存实现。
  */
-import { type McpServerConfig } from './mcp-executor.js';
-export interface McpServerEntry {
+import { type McpExecutorLike, type McpServerConfig } from './mcp-executor.js';
+interface McpServerCommon {
     id: string;
     /** 用户可见名称，也用于生成工具前缀（如 "filesystem"）。 */
     name: string;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface StdioMcpServerEntry extends McpServerCommon {
+    transport: 'stdio';
     command: string;
     args: string[];
     env: Record<string, string>;
     cwd?: string;
-    enabled: boolean;
-    createdAt: string;
-    updatedAt: string;
 }
-export interface CreateMcpServerInput {
+export interface StreamableHttpMcpServerEntry extends McpServerCommon {
+    transport: 'streamable-http';
+    url: string;
+    headers: Record<string, string>;
+    headersFromEnv: Record<string, string>;
+    bearerTokenEnvVar?: string;
+    reconnect?: {
+        initialReconnectionDelay?: number;
+        maxReconnectionDelay?: number;
+        reconnectionDelayGrowFactor?: number;
+        maxRetries?: number;
+    };
+}
+export type McpServerEntry = StdioMcpServerEntry | StreamableHttpMcpServerEntry;
+interface CreateMcpServerCommon {
     name: string;
+    enabled?: boolean;
+}
+export interface CreateStdioMcpServerInput extends CreateMcpServerCommon {
+    /** Omitted remains compatible with existing callers and stored product configs. */
+    transport?: 'stdio';
     command: string;
     args?: string[];
     env?: Record<string, string>;
     cwd?: string;
+}
+export interface CreateStreamableHttpMcpServerInput extends CreateMcpServerCommon {
+    transport: 'streamable-http';
+    url: string;
+    headers?: Record<string, string>;
+    headersFromEnv?: Record<string, string>;
+    bearerTokenEnvVar?: string;
+    reconnect?: StreamableHttpMcpServerEntry['reconnect'];
+    command?: never;
+}
+export type CreateMcpServerInput = CreateStdioMcpServerInput | CreateStreamableHttpMcpServerInput;
+export interface UpdateMcpServerInput {
+    name?: string;
+    transport?: 'stdio' | 'streamable-http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    headersFromEnv?: Record<string, string>;
+    bearerTokenEnvVar?: string;
+    reconnect?: StreamableHttpMcpServerEntry['reconnect'];
     enabled?: boolean;
 }
-/** 最小 KV 存储接口，避免本模块直接依赖 electron-store。 */
+/** 最小 KV 存储接口，避免本模块直接依赖具体存储实现。 */
 export interface McpServerKvStore {
     get(key: 'mcpServers'): McpServerEntry[] | undefined;
     set(key: 'mcpServers', value: McpServerEntry[]): void;
@@ -65,15 +110,16 @@ export interface McpToolEntry {
 export declare function sanitizeServerKey(name: string, id: string): string;
 export declare class McpServerRegistry {
     private readonly store;
+    private readonly executor;
     /** serverId → 最近一次 listTools 的结果（内存缓存，重启后由后台刷新重建）。 */
     private readonly toolCache;
-    constructor(store: McpServerKvStore);
+    constructor(store: McpServerKvStore, executor?: McpExecutorLike);
     list(): McpServerEntry[];
     get(idOrName: string): McpServerEntry | null;
     /** 产品预置 MCP：缺省不引入；已有同名服务不覆盖。 */
     seedProductServers(specs: CreateMcpServerInput[] | undefined): void;
     create(input: CreateMcpServerInput): McpServerEntry;
-    update(id: string, updates: Partial<CreateMcpServerInput>): McpServerEntry;
+    update(id: string, updates: UpdateMcpServerInput): McpServerEntry;
     delete(id: string): boolean;
     /**
      * 解析 Claude Desktop 风格的配置并批量导入：
@@ -88,6 +134,7 @@ export declare class McpServerRegistry {
     /** 工具名前缀（同一名称多实例撞名时追加 id 后缀保证唯一）。 */
     serverKey(entry: McpServerEntry): string;
     toExecutorConfig(entry: McpServerEntry): McpServerConfig;
+    toPublicEntry(entry: McpServerEntry): Record<string, unknown>;
     getCachedTools(serverId: string): CachedToolList | null;
     /**
      * 所有「已启用 + 工具缓存非空」服务的工具扁平清单（"/" 选择器数据源）。
@@ -104,3 +151,4 @@ export declare class McpServerRegistry {
     /** 后台刷新所有已启用服务的工具列表（启动时调用，不阻塞、不抛错）。 */
     refreshAllEnabled(): Promise<void>;
 }
+export {};