@wrongstack/mcp 0.284.1 → 0.285.0

package/dist/client.d.ts

@@ -0,0 +1,134 @@
+export type Transport = 'stdio' | 'sse' | 'streamable-http';
+export interface MCPClientOptions {
+    name: string;
+    transport: Transport;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    url?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    startupTimeoutMs?: number | undefined;
+    requestTimeoutMs?: number | undefined;
+    /**
+     * Allowlist of env var names to forward from the parent process (process.env)
+     * to the child. Values are resolved at spawn time and merged into `env`
+     * via the `extra` path of `buildChildEnv` (unfiltered). This is how built-in
+     * MCP server presets (GitHub, Slack, Brave Search, …) get their API tokens
+     * without storing them in config.json or being scrubbed by the secret filter.
+     */
+    passthroughEnv?: string[] | undefined;
+}
+export type ConnectionState = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed'
+/** Lazy server: registered from a cached manifest, process not spawned. */
+ | 'dormant';
+export interface MCPTool {
+    name: string;
+    description?: string | undefined;
+    inputSchema: Record<string, unknown>;
+}
+export interface ToolCallResult {
+    content: unknown;
+    isError: boolean;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number;
+    result?: unknown | undefined;
+    error?: {
+        code: number | undefined;
+        message: string;
+        data?: unknown | undefined;
+    } | undefined;
+}
+type ExitListener = (name: string, code: number | null, signal: string | null) => void;
+/**
+ * Fired when the server sends `notifications/tools/list_changed`. The
+ * client refreshes its cached tool list before invoking listeners, so
+ * subscribers can call `listTools()` for the fresh set.
+ */
+type ToolsChangedListener = (name: string, tools: MCPTool[]) => void;
+/**
+ * Lightweight MCP client supporting three transport types:
+ * - stdio: spawns a child process and communicates over pipes
+ * - sse: connects to an HTTP SSE endpoint for server events, POST for requests
+ * - streamable-http: session-based HTTP transport with NDJSON responses
+ */
+export declare class MCPClient {
+    readonly opts: MCPClientOptions;
+    private state;
+    private child?;
+    private nextId;
+    /**
+     * In-flight JSON-RPC calls keyed by id. `resolve` settles the call; `reject`
+     * is invoked from {@link failPending} when the underlying transport dies
+     * (stdio child exit, `close()`) so callers don't hang forever.
+     */
+    private readonly pending;
+    private rxBuffer;
+    private _tools;
+    /** Cached tool list — survives reconnects so the registry can re-register without re-discovering. */
+    private _toolsCache?;
+    private _drainPending;
+    private _lastNotifySkipped;
+    private sseTransport?;
+    private httpTransport?;
+    /** Notified when the stdio child process exits so the registry can attempt reconnect. */
+    private readonly exitListeners;
+    /** Notified when the server announces a tools/list_changed notification. */
+    private readonly toolsChangedListeners;
+    /** Notified when an HTTP transport (SSE or streamable-http) disconnects. */
+    private readonly disconnectListeners;
+    constructor(opts: MCPClientOptions);
+    getState(): ConnectionState;
+    listTools(): MCPTool[];
+    /** Returns true if a prior notify() call was skipped due to backpressure. */
+    hadNotifySkipped(): boolean;
+    /**
+     * Register a listener for child-process exit events.
+     * The registry uses this to trigger reconnection.
+     */
+    addExitListener(listener: ExitListener): void;
+    removeExitListener(listener: ExitListener): void;
+    /**
+     * Register a listener for transport disconnect events (SSE / streamable-http).
+     * Used by the registry to trigger reconnection for HTTP-based servers.
+     */
+    addDisconnectListener(listener: () => void): void;
+    removeDisconnectListener(listener: () => void): void;
+    connect(): Promise<void>;
+    private connectStdio;
+    private connectSSE;
+    private connectStreamableHTTP;
+    callTool(name: string, input: unknown, opts?: {
+        signal?: AbortSignal | undefined;
+    }): Promise<ToolCallResult>;
+    close(): Promise<void>;
+    private request;
+    /**
+     * Reject every in-flight {@link request} call. Used when the underlying
+     * transport dies — without this, callers awaiting `tools/call` over a
+     * killed stdio child or a closed transport would hang indefinitely.
+     */
+    private failPending;
+    private notify;
+    private onData;
+    private onLine;
+    /**
+     * L2-C: refresh the cached tool list when the server announces a
+     * `tools/list_changed`. Listeners (the registry) re-wrap and
+     * re-register. Failures are swallowed — a stale cache is preferable
+     * to a hard crash on a transient notification glitch.
+     */
+    private handleToolsListChanged;
+    addToolsChangedListener(listener: ToolsChangedListener): void;
+    removeToolsChangedListener(listener: ToolsChangedListener): void;
+}
+/**
+ * Quote a single argument for `cmd.exe` when spawning with `shell: true` on
+ * Windows. Only args containing whitespace or quotes need wrapping; inside
+ * double quotes cmd.exe escapes a literal `"` as `""`. Backslashes are literal
+ * inside cmd quotes, so paths like `C:\Program Files\x` pass through unharmed.
+ */
+export declare function quoteWindowsArg(arg: string): string;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared constants for the MCP package.
+ *
+ * Centralizing these values means:
+ * - Protocol version and client identity are updated in one place
+ * - Reconnect parameters can be overridden via config in the future
+ * - No scattered magic values across multiple files
+ */
+export declare const MCP_CONSTANTS: Readonly<{
+    /** MCP protocol version advertised during handshake. */
+    readonly PROTOCOL_VERSION: '2024-11-05';
+    /** Identity announced to MCP servers during `initialize`. */
+    readonly CLIENT_INFO: Readonly<{
+        name: "wrongstack";
+        version: "0.1.10";
+    }>;
+    /** Reconnection behaviour when a transport disconnects. */
+    readonly RECONNECT: Readonly<{
+        /** Max full reconnect cycles before the slot is marked `failed`. */
+        MAX_CYCLES: 5;
+        /** Base delay between cycles (exponential backoff applied on top). */
+        BASE_DELAY_MS: 1000;
+        /** Jitter factor applied to the backoff (0 = no jitter, 1 = full). */
+        JITTER_FACTOR: 0.2;
+        /** Max connection attempts within a single cycle. */
+        MAX_ATTEMPTS: 3;
+        /** Base multiplier for the exponential backoff formula (`delay = BASE * multiplier^attempt`). */
+        BACKOFF_MULTIPLIER: 2;
+    }>;
+    /** Timing for graceful / forced disconnect. */
+    readonly DISCONNECT: Readonly<{
+        /** Ms to wait for in-flight requests to complete before force-closing. */
+        GRACEFUL_MS: 800;
+        /** 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. */
+    readonly SSE_READER_MAX_BUFFER: number;
+    /** Max characters logged from a request body. */
+    readonly REQUEST_LOG_CAP: 1024;
+}>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACxB,wDAAwD;+BACtC,YAAY;IAE9B,6DAA6D;;;;;IAM7D,2DAA2D;;QAEzD,oEAAoE;;QAEpE,sEAAsE;;QAEtE,sEAAsE;;QAEtE,qDAAqD;;QAErD,iGAAiG;;;IAInG,+CAA+C;;QAE7C,0EAA0E;;QAE1E,wDAAwD;;;IAI1D,mCAAmC;;QAEjC,qFAAqF;;QAErF,mEAAmE;;;IAIrE,0DAA0D;kCACrC,GAAG;IAExB,0CAA0C;;IAG1C,iDAAiD;8BAChC,IAAI;EACZ,CAAC"}