@wrongstack/mcp 0.264.0 → 0.267.0

package/dist/index.d.ts

@@ -13,7 +13,9 @@ interface MCPClientOptions {
     startupTimeoutMs?: number | undefined;
     requestTimeoutMs?: number | undefined;
 }
-type ConnectionState = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed';
+type ConnectionState = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed'
+/** Lazy server: registered from a cached manifest, process not spawned. */
+ | 'dormant';
 interface MCPTool {
     name: string;
     description?: string | undefined;
@@ -115,12 +117,30 @@ declare class MCPClient {
     removeToolsChangedListener(listener: ToolsChangedListener): void;
 }
 
-declare function wrapMCPTool(serverName: string, mcpTool: MCPTool, client: MCPClient, permission?: Permission): Tool;
+/**
+ * Resolves the live client for a tool call. A plain {@link MCPClient} for eager
+ * servers, or a thunk that connects-on-demand for lazy/dormant servers (the
+ * registry passes `() => this.ensureConnected(name)`).
+ */
+type MCPClientResolver = MCPClient | (() => Promise<MCPClient>);
+declare function wrapMCPTool(serverName: string, mcpTool: MCPTool, client: MCPClientResolver, permission?: Permission): Tool;
 
 interface MCPRegistryOptions {
     toolRegistry: ToolRegistry;
     events: EventBus;
     log: Logger;
+    /**
+     * Directory for the on-disk tool-manifest cache (lazy-connect). Without it,
+     * `lazy` servers cannot register tools cold and fall back to eager connect.
+     * Typically `wpaths.cacheDir` (`~/.wrongstack/cache`).
+     */
+    cacheDir?: string | undefined;
+    /**
+     * Idle window (ms) after which a connected lazy server is auto-stopped and
+     * re-woken on the next tool call. 0 disables idle auto-sleep.
+     * Default: {@link MCP_CONSTANTS.IDLE.DEFAULT_TIMEOUT_MS}.
+     */
+    idleTimeoutMs?: number | undefined;
     /**
      * Lazy mode: when true, MCP server tools are NOT registered into the
      * tool registry on connect. They are cached internally and can be
@@ -138,8 +158,24 @@ declare class MCPRegistry {
     private readonly events;
     private readonly log;
     private readonly lazyMode;
+    private readonly cacheDir?;
+    private readonly idleTimeoutMs;
+    /** Single shared idle sweep timer (started lazily; unref'd; cleared on stopAll). */
+    private idleTimer?;
     constructor(opts: MCPRegistryOptions);
     start(cfg: MCPServerConfig): Promise<void>;
+    /**
+     * Boot a lazy server WITHOUT spawning it. If a tool manifest is cached (from a
+     * prior connect with matching config), register resolver-backed wrappers and
+     * go `dormant` — the process spawns on the first tool call. If there is no
+     * cache yet, do a one-time cold discovery connect to learn + cache the tools.
+     */
+    private startLazy;
+    /**
+     * Ensure a lazy server is connected, spawning it on demand. Single-flight:
+     * concurrent first-calls share one connect. Resolver wrappers call this.
+     */
+    ensureConnected(name: string): Promise<MCPClient>;
     /**
      * Register all cached tools for a given server into the tool registry.
      * No-op if tools are already registered or the server is not connected.
@@ -162,7 +198,32 @@ declare class MCPRegistry {
         name: string;
         state: ConnectionState;
         toolCount: number;
+        tools: string[];
     }[];
+    /**
+     * Resolve the live tool names for a slot — the registered names in normal
+     * mode, or the cached lazy-tool names when running in lazy mode (where
+     * tools are connected but intentionally not registered).
+     */
+    private toolNamesForSlot;
+    /**
+     * Wrap + register (or cache) a server's tools. Lazy servers get resolver-backed
+     * wrappers that spawn the process on first use; eager servers bind the live
+     * client directly. Honours token-saving `lazyMode` (cache, don't register) and
+     * a register-once guard for lazy resolver wrappers (so a wake/reconnect reuses
+     * the existing registrations rather than churning the tool list).
+     */
+    private applyTools;
+    /** Start the shared idle sweep timer once (unref'd so it never holds the process). */
+    private ensureIdleSweep;
+    /** Auto-sleep connected lazy servers that have been idle past the timeout. */
+    private sweepIdle;
+    /**
+     * Soft stop: close the server process but KEEP its resolver wrappers and
+     * cached manifest registered, so the next tool call transparently re-wakes it.
+     * Distinct from {@link stop} (full teardown for disable/remove).
+     */
+    private sleepIdle;
     /**
      * Catalog of every server ever registered with this registry — includes
      * servers that are stopped, failed, or not yet started.
@@ -174,6 +235,7 @@ declare class MCPRegistry {
         state: ConnectionState;
         toolCount: number;
         enabled: boolean;
+        tools: string[];
     }[];
     stopAll(): Promise<void>;
     /**
@@ -212,6 +274,83 @@ declare class MCPRegistry {
     private attemptConnect;
 }
 
+/** Transport values accepted from UI surfaces (UI also offers a bare "http"). */
+type TransportInput = 'stdio' | 'sse' | 'streamable-http' | 'http';
+/** Loosely-typed server input as it arrives from a UI or command surface. */
+interface McpServerInput {
+    name: string;
+    transport?: TransportInput | string | undefined;
+    description?: string | undefined;
+    enabled?: boolean | undefined;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    url?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    allowedTools?: string[] | undefined;
+    permission?: Permission | undefined;
+    /** Lazy connect — spawn the process only on first tool call (see config). */
+    lazy?: boolean | undefined;
+}
+/** Projected view of one server, merging disk config with live registry state. */
+interface McpServerInfo {
+    name: string;
+    transport: MCPServerConfig['transport'];
+    description?: string | undefined;
+    enabled: boolean;
+    /** Raw registry state ('connected' | 'connecting' | … | 'failed'), or 'stopped' when not running. */
+    status: string;
+    /** Real tool names discovered from the live server (empty when not connected). */
+    tools: string[];
+    url?: string | undefined;
+    command?: string | undefined;
+    /** Lazy-connect opt-in (spawn on first tool call). */
+    lazy?: boolean | undefined;
+}
+interface McpOpResult {
+    ok: boolean;
+    message: string;
+    /** The affected server's projected view, when applicable. */
+    server?: McpServerInfo | undefined;
+    /** Raw registry state after a start/restart attempt. */
+    state?: string | undefined;
+    /** Real tool names after a start/restart attempt. */
+    tools?: string[] | undefined;
+    /** Set when a config change persisted but the registry start/stop failed. */
+    registryError?: string | undefined;
+}
+interface McpManageDeps {
+    /** Absolute path to the global config.json that owns `mcpServers`. */
+    configPath: string;
+    /** Live registry for runtime start/stop/restart. */
+    registry: MCPRegistry;
+    /** Built-in presets (from core `allServers()`), used by name-only `add`. */
+    presets?: Record<string, MCPServerConfig> | undefined;
+}
+/** List all configured servers, merged with live registry status + tool names. */
+declare function listMcp(deps: McpManageDeps): Promise<McpServerInfo[]>;
+/**
+ * Add a new server. `input` may be a fully-specified config, or just a `name`
+ * matching a known preset (`deps.presets`). Fails if the server already exists.
+ * When enabled, the server is started immediately via the registry.
+ */
+declare function addMcp(input: McpServerInput, deps: McpManageDeps): Promise<McpOpResult>;
+/** Update an existing server's config, then re-apply it to the live registry. */
+declare function updateMcp(input: McpServerInput, deps: McpManageDeps): Promise<McpOpResult>;
+/** Remove a server from config and stop it if running. */
+declare function removeMcp(name: string, deps: McpManageDeps): Promise<McpOpResult>;
+/** Enable a server in config and start it. */
+declare function enableMcp(name: string, deps: McpManageDeps): Promise<McpOpResult>;
+/** Disable a server in config and stop it. */
+declare function disableMcp(name: string, deps: McpManageDeps): Promise<McpOpResult>;
+/** Restart a running server (or start it from config if registered but stopped). */
+declare function restartMcp(name: string, deps: McpManageDeps): Promise<McpOpResult>;
+/**
+ * Discover a server's tools. Tools are discovered on connect, so this ensures
+ * the server is running and returns its live tool list.
+ */
+declare function discoverMcp(name: string, deps: McpManageDeps): Promise<McpOpResult>;
+
 /**
  * Server-side MCP. The mirror image of `MCPClient`: instead of consuming a
  * remote MCP server, this lets WrongStack *be* an MCP server — exposing its
@@ -357,6 +496,13 @@ declare const MCP_CONSTANTS: Readonly<{
         /** Ms after which the force disconnect is triggered. */
         FORCE_TIMEOUT_MS: 1200;
     }>;
+    /** Lazy-connect idle lifecycle. */
+    readonly IDLE: Readonly<{
+        /** Default ms a lazy server stays connected with no tool calls before auto-sleep. */
+        DEFAULT_TIMEOUT_MS: 300000;
+        /** How often the idle sweep runs (kept well below the timeout). */
+        SWEEP_INTERVAL_MS: 30000;
+    }>;
     /** JSON-RPC response timeout for outstanding requests. */
     readonly RESPONSE_TIMEOUT_MS: 500;
     /** Max buffer size for the SSE reader. */
@@ -365,6 +511,21 @@ declare const MCP_CONSTANTS: Readonly<{
     readonly REQUEST_LOG_CAP: 1024;
 }>;
 
+/** Stable hash of the fields that define how/where we connect to a server. */
+declare function manifestConfigHash(cfg: {
+    transport: string;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    url?: string | undefined;
+}): string;
+/**
+ * Read a server's cached tools. Returns null when there is no cache or when the
+ * stored `configHash` no longer matches (server config changed → stale).
+ */
+declare function readManifest(cacheDir: string, name: string, configHash: string): Promise<MCPTool[] | null>;
+/** Persist a server's discovered tools. Best-effort — IO errors are swallowed. */
+declare function writeManifest(cacheDir: string, name: string, configHash: string, tools: MCPTool[]): Promise<void>;
+
 interface HttpTransportOptions {
     name: string;
     url: string;
@@ -486,4 +647,4 @@ declare class StreamableHTTPTransport extends BaseHTTPTransport {
     close(): Promise<void>;
 }
 
-export { type ConnectionState, type HttpTransportOptions, MCPClient, type MCPClientOptions, MCPRegistry, type MCPRegistryOptions, MCPServer, type MCPServerCallResult, type MCPServerLogger, type MCPServerOptions, type MCPServerTool, type MCPServerToolHost, type MCPTool, MCP_CONSTANTS, SSEReader, SSETransport, type ServeHttpHandle, type ServeHttpOptions, type ServeStdioHandle, type ServeStdioOptions, StreamableHTTPTransport, type ToolCallResult, type Transport, serveHttp, serveStdio, toContentBlocks, wrapMCPTool };
+export { type ConnectionState, type HttpTransportOptions, MCPClient, type MCPClientOptions, MCPRegistry, type MCPRegistryOptions, MCPServer, type MCPServerCallResult, type MCPServerLogger, type MCPServerOptions, type MCPServerTool, type MCPServerToolHost, type MCPTool, MCP_CONSTANTS, type McpManageDeps, type McpOpResult, type McpServerInfo, type McpServerInput, SSEReader, SSETransport, type ServeHttpHandle, type ServeHttpOptions, type ServeStdioHandle, type ServeStdioOptions, StreamableHTTPTransport, type ToolCallResult, type Transport, addMcp, disableMcp, discoverMcp, enableMcp, listMcp, manifestConfigHash, readManifest, removeMcp, restartMcp, serveHttp, serveStdio, toContentBlocks, updateMcp, wrapMCPTool, writeManifest };