@wrongstack/mcp 1.0.33 → 1.0.35

package/dist/protocol.d.ts

@@ -98,4 +98,45 @@ export declare function parseGetPromptResult(value: unknown): MCPGetPromptResult
  * a notification has no reply, so a bad one is ignored, not answered.
  */
 export declare function resourceUpdatedUri(params: unknown): string | undefined;
+/** Parsed `notifications/progress` payload (2024-11-05 progress utility). */
+export interface MCPProgressNotification {
+    /** Echo of the `params._meta.progressToken` the originating request sent. */
+    progressToken: string | number;
+    /** Monotonically increasing progress value for the token's request. */
+    progress: number;
+    /** Expected final `progress` value, when the server sent one. */
+    total?: number | undefined;
+    /** Human-readable progress text (a later revision's optional field). */
+    message?: string | undefined;
+}
+/** Log levels `notifications/message` may carry (MCP `LoggingLevel`, RFC 5424 severities). */
+export type MCPLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+/** Parsed `notifications/message` (logging) payload. */
+export interface MCPLogMessageNotification {
+    level: MCPLogLevel;
+    /** Name of the emitting subsystem, when the server sent one. */
+    logger?: string | undefined;
+    /** Log content serialized to bounded, control-free text. */
+    data?: string | undefined;
+}
+/**
+ * Parse a `notifications/progress` payload (2024-11-05 progress utility).
+ *
+ * A server sends progress only while a request whose `params._meta` carried
+ * a `progressToken` is in flight, so the token in the result is the only
+ * correlation between a notification and the call that asked for it. Returns
+ * `undefined` for a malformed payload rather than throwing — a notification
+ * has no reply, so a bad one is ignored, not answered (same contract as
+ * {@link resourceUpdatedUri}). Optional fields (`total`, `message`) are
+ * dropped when invalid instead of failing the whole notification.
+ */
+export declare function progressNotification(params: unknown): MCPProgressNotification | undefined;
+/**
+ * Parse a `notifications/message` (logging) payload (2024-11-05 logging
+ * utility). The log `data` is serialized to text and clamped — it is
+ * attacker-controllable server output — and an out-of-enum `level` makes the
+ * notification malformed. Returns `undefined` rather than throwing; a
+ * notification has no reply.
+ */
+export declare function logMessageNotification(params: unknown): MCPLogMessageNotification | undefined;
 //# sourceMappingURL=protocol.d.ts.map

package/dist/registry-authorization.d.ts

@@ -1,15 +1,17 @@
 import type { MCPServerConfig } from '@wrongstack/core/types';
 import type { MCPAuthorizationLoginHandle, MCPAuthorizationLoginInput, MCPAuthorizationManager, MCPAuthorizationStartResult, MCPAuthorizationStatus } from './authorization-manager.js';
 import type { ServerSlot } from './registry-slots.js';
-export declare function requireAuthorizationManager(manager: MCPAuthorizationManager | undefined): MCPAuthorizationManager;
-export declare function requireHttpServerConfig(servers: Map<string, ServerSlot>, disabledServers: Map<string, MCPServerConfig>, name: string): MCPServerConfig;
-export declare function loginRegistryAuthorization(manager: MCPAuthorizationManager | undefined, cfg: MCPServerConfig, name: string, input: Omit<MCPAuthorizationLoginInput, 'serverName' | 'resource'>): Promise<MCPAuthorizationLoginHandle>;
-export declare function beginRegistryAuthorization(manager: MCPAuthorizationManager | undefined, cfg: MCPServerConfig, name: string, input: {
+/** Caller-supplied part of `MCPRegistry.beginAuthorization()`; the registry adds server + resource. */
+export interface MCPRegistryAuthorizationBeginInput {
     clientId?: string | undefined;
     redirectUri: string;
     scopes?: readonly string[] | undefined;
     challengeHeader?: string | null | undefined;
     signal?: AbortSignal | undefined;
-}): Promise<MCPAuthorizationStartResult>;
+}
+export declare function requireAuthorizationManager(manager: MCPAuthorizationManager | undefined): MCPAuthorizationManager;
+export declare function requireHttpServerConfig(servers: Map<string, ServerSlot>, disabledServers: Map<string, MCPServerConfig>, name: string): MCPServerConfig;
+export declare function loginRegistryAuthorization(manager: MCPAuthorizationManager | undefined, cfg: MCPServerConfig, name: string, input: Omit<MCPAuthorizationLoginInput, 'serverName' | 'resource'>): Promise<MCPAuthorizationLoginHandle>;
+export declare function beginRegistryAuthorization(manager: MCPAuthorizationManager | undefined, cfg: MCPServerConfig, name: string, input: MCPRegistryAuthorizationBeginInput): Promise<MCPAuthorizationStartResult>;
 export declare function completeRegistryAuthorization(manager: MCPAuthorizationManager | undefined, cfg: MCPServerConfig, name: string, callbackUrl: string, signal?: AbortSignal | undefined): Promise<MCPAuthorizationStatus>;
 //# sourceMappingURL=registry-authorization.d.ts.map

package/dist/registry-catalog-operations.d.ts

@@ -26,4 +26,11 @@ export declare function listPrompts(this: RegistryCatalogOperationsHost, name: s
 }): Promise<MCPPrompt[]>;
 export declare function getPrompt(this: RegistryCatalogOperationsHost, serverName: string, promptName: string, args?: Record<string, string> | undefined): Promise<MCPGetPromptResult>;
 export declare function selectPromptForInsertion(this: RegistryCatalogOperationsHost, serverName: string, promptName: string, args?: Record<string, string> | undefined, policy?: MCPInsertionPolicy | undefined): Promise<MCPPromptInsertion>;
+/**
+ * Body of `MCPRegistry.withConnectedClient()`: keep all remote requests awake
+ * and reject results from superseded clients.
+ */
+export declare function runWithConnectedClient<T>(self: Pick<RegistryCatalogOperationsHost, 'servers' | 'requireSlot'> & {
+    ensureConnected(name: string): Promise<import('./client.js').MCPClient>;
+}, name: string, run: (client: import('./client.js').MCPClient, assertCurrent: () => void) => Promise<T>): Promise<T>;
 //# sourceMappingURL=registry-catalog-operations.d.ts.map

package/dist/registry-contexts.d.ts

@@ -0,0 +1,11 @@
+import type { RegistryConnectContext } from './registry-connect-loop.js';
+import type { RegistryIdleContext } from './registry-idle.js';
+import type { MCPRegistryInternals } from './registry-internals.js';
+/**
+ * The context objects `MCPRegistry` hands to the connect loop and the idle
+ * sweep. Every callback dispatches through the registry instance, so a
+ * replaced/spied member is honored exactly as when the class built them.
+ */
+export declare function buildRegistryConnectContext(self: MCPRegistryInternals): RegistryConnectContext;
+export declare function buildRegistryIdleContext(self: MCPRegistryInternals): RegistryIdleContext;
+//# sourceMappingURL=registry-contexts.d.ts.map

package/dist/registry-describe.d.ts

@@ -0,0 +1,39 @@
+import type { MCPServerConfig } from '@wrongstack/core/types';
+import type { ConnectionState, MCPToolAnnotations } from './contracts.js';
+import type { ServerSlot } from './registry-slots.js';
+/** Snapshot shapes `MCPRegistry` reports for its servers (list/describe/health/describeTools). */
+/** One server's tool, as `MCPRegistry.describeTools()` reports it. */
+export interface MCPDescribedTool {
+    name: string;
+    description?: string | undefined;
+    inputSchema: Record<string, unknown>;
+    annotations?: MCPToolAnnotations | undefined;
+}
+/**
+ * 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).
+ */
+export declare function toolNamesForSlot(s: ServerSlot): string[];
+/** Body of `MCPRegistry.describeTools()` for a registered slot (honors `allowedTools`). */
+export declare function describeSlotTools(slot: ServerSlot): MCPDescribedTool[];
+export declare function listServers(servers: Map<string, ServerSlot>): {
+    name: string;
+    state: ConnectionState;
+    toolCount: number;
+    tools: string[];
+}[];
+/** Body of `MCPRegistry.describe()` — active slots followed by configured-off servers. */
+export declare function describeServers(servers: Map<string, ServerSlot>, disabledServers: Map<string, MCPServerConfig>): {
+    name: string;
+    state: ConnectionState;
+    toolCount: number;
+    enabled: boolean;
+    tools: string[];
+}[];
+export declare function serverHealth(servers: Map<string, ServerSlot>): {
+    name: string;
+    alive: boolean;
+    latencyMs?: number | undefined;
+}[];
+//# sourceMappingURL=registry-describe.d.ts.map

package/dist/registry-internals.d.ts

@@ -0,0 +1,57 @@
+import type { EventBus } from '@wrongstack/core/kernel';
+import type { ToolRegistry } from '@wrongstack/core/registry';
+import type { Logger, MCPServerConfig } from '@wrongstack/core/types';
+import type { MCPClient } from './client.js';
+import type { MCPTool } from './contracts.js';
+import type { MCPFailureKind, MCPOperationKind, MCPOperationListener } from './operations.js';
+import type { MCPLogMessageNotification, MCPProgressNotification } from './protocol.js';
+import type { RegistryCatalogOperationsHost } from './registry-catalog-operations.js';
+import type { RegistryServerLifecycleHost } from './registry-server-lifecycle.js';
+import type { ServerSlot } from './registry-slots.js';
+import type { MCPRegistryOptions } from './registry-types.js';
+/**
+ * The private state and private members of `MCPRegistry`, as seen by the
+ * free functions its method bodies were extracted into (registry-slot-events,
+ * registry-contexts, registry-describe). The class hands itself to those
+ * functions through this structural view; consumers still see the members
+ * as private.
+ */
+export interface MCPRegistryInternals extends RegistryServerLifecycleHost, RegistryCatalogOperationsHost {
+    readonly servers: Map<string, ServerSlot>;
+    readonly disabledServers: Map<string, MCPServerConfig>;
+    readonly toolRegistry: ToolRegistry;
+    readonly events: EventBus;
+    readonly log: Logger;
+    readonly lazyMode: boolean;
+    readonly cacheDir: string | undefined;
+    readonly cwd: string | undefined;
+    readonly idleTimeoutMs: number;
+    readonly authorizationProviderFactory: MCPRegistryOptions['authorizationProviderFactory'];
+    readonly elicitationHandler: MCPRegistryOptions['elicitationHandler'];
+    readonly operationListeners: Set<MCPOperationListener>;
+    readonly onToolsChanged: (name: string, _tools: {
+        name: string;
+    }[]) => void;
+    readonly onResourcesChanged: (name: string) => void;
+    readonly onResourceUpdated: (name: string, uri: string) => void;
+    readonly onProgress: (name: string, progress: MCPProgressNotification) => void;
+    readonly onLogMessage: (name: string, log: MCPLogMessageNotification) => void;
+    readonly onPromptsChanged: (name: string) => void;
+    readonly onChildExit: (name: string, code: number | null, _signal: string | null) => void;
+    readonly onTransportDisconnect: (name: string) => void;
+    ensureConnected(name: string): Promise<MCPClient>;
+    requireSlot(name: string): ServerSlot;
+    singleFlightConnect(slot: ServerSlot): Promise<MCPClient | undefined>;
+    applyTools(slot: ServerSlot, tools: MCPTool[], client?: MCPClient | undefined): void;
+    persistCapabilityManifest(slot: ServerSlot): Promise<void>;
+    toolNamesForSlot(s: ServerSlot): string[];
+    addCatalogListeners(client: MCPClient): void;
+    removeCatalogListeners(client: MCPClient): void;
+    ensureIdleSweep(): void;
+    scheduleReconnect(slot: ServerSlot): void;
+    attemptReconnect(slot: ServerSlot): Promise<void>;
+    recordSuccess(slot: ServerSlot, resetFailures?: boolean): void;
+    recordFailure(slot: ServerSlot, failureKind: MCPFailureKind, reason: string, durationMs?: number | undefined): void;
+    recordOperation(slot: ServerSlot, kind: MCPOperationKind, reason?: string | undefined, failureKind?: MCPFailureKind | undefined, durationMs?: number | undefined, retain?: boolean): void;
+}
+//# sourceMappingURL=registry-internals.d.ts.map

package/dist/registry-runtime.d.ts

@@ -0,0 +1,101 @@
+import type { EventBus } from '@wrongstack/core/kernel';
+import type { ToolRegistry } from '@wrongstack/core/registry';
+import type { Logger, MCPServerConfig } from '@wrongstack/core/types';
+import type { MCPAuthorizationManager } from './authorization-manager.js';
+import type { MCPClient } from './client.js';
+import type { MCPTool } from './contracts.js';
+import type { MCPFailureKind, MCPOperationKind, MCPOperationListener } from './operations.js';
+import type { MCPLogMessageNotification, MCPProgressNotification } from './protocol.js';
+import { type RegistryIdleContext } from './registry-idle.js';
+import type { MCPRegistryInternals } from './registry-internals.js';
+import type { ServerSlot } from './registry-slots.js';
+import type { MCPRegistryOptions } from './registry-types.js';
+/**
+ * State and connection machinery behind `MCPRegistry`: the slot table,
+ * single-flight connects, idle sweep, the listeners a connected client
+ * notifies (catalog changes, exit/disconnect + reconnect) and operational
+ * bookkeeping. `MCPRegistry` (registry.ts) extends this with the public
+ * lifecycle, catalog and authorization API. The members it needs from that
+ * subclass are declared abstract here.
+ */
+export declare abstract class MCPRegistryRuntime {
+    protected readonly servers: Map<string, ServerSlot>;
+    /** Configured-off servers are tracked without creating a transport/client. */
+    protected readonly disabledServers: Map<string, MCPServerConfig>;
+    protected readonly toolRegistry: ToolRegistry;
+    protected readonly events: EventBus;
+    protected readonly log: Logger;
+    protected readonly lazyMode: boolean;
+    protected readonly cacheDir?: string | undefined;
+    protected readonly cwd?: string | undefined;
+    protected readonly idleTimeoutMs: number;
+    protected readonly authorizationProviderFactory?: MCPRegistryOptions['authorizationProviderFactory'];
+    protected readonly authorizationManager?: MCPAuthorizationManager | undefined;
+    protected readonly elicitationHandler?: MCPRegistryOptions['elicitationHandler'];
+    protected readonly operationListeners: Set<MCPOperationListener>;
+    /** Starts still in flight, for {@link whenStarted}. */
+    protected readonly startups: Set<Promise<void>>;
+    /** Single shared idle sweep timer (started lazily; unref'd; cleared on stopAll). */
+    protected idleTimer?: ReturnType<typeof setInterval> | undefined;
+    constructor(opts: MCPRegistryOptions);
+    protected requireSlot(name: string): ServerSlot;
+    /**
+     * 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.
+     */
+    protected startLazy(slot: ServerSlot): Promise<void>;
+    protected singleFlightConnect(slot: ServerSlot): Promise<MCPClient | undefined>;
+    /** Keep all remote requests awake and reject results from superseded clients. */
+    protected withConnectedClient<T>(name: string, run: (client: MCPClient, assertCurrent: () => void) => Promise<T>): Promise<T>;
+    /**
+     * 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).
+     */
+    protected toolNamesForSlot(s: ServerSlot): string[];
+    /**
+     * This registry as the structural view its extracted method bodies take
+     * (see registry-internals.ts); the abstract members are supplied by
+     * `MCPRegistry`.
+     */
+    protected internals(): MCPRegistryInternals;
+    protected connectContext(): import("./registry-connect-loop.js").RegistryConnectContext;
+    protected idleContext(): RegistryIdleContext;
+    protected applyTools(slot: ServerSlot, tools: MCPTool[], client?: MCPClient | undefined): void;
+    protected persistCapabilityManifest(slot: ServerSlot): Promise<void>;
+    /** Start the shared idle sweep timer once (unref'd so it never holds the process). */
+    protected ensureIdleSweep(): void;
+    protected sweepIdle(): Promise<void>;
+    /**
+     * L2-C: handle `notifications/tools/list_changed` from the server.
+     * Unregister the previous wrapper set, then re-register the fresh
+     * tool list. The client has already refreshed its cache before
+     * dispatching — we just need to re-wrap and re-register.
+     * In lazy mode, only update the internal cache without registering.
+     */
+    protected readonly onToolsChanged: (name: string, _tools: {
+        name: string;
+    }[]) => void;
+    protected readonly onResourcesChanged: (name: string) => void;
+    protected readonly onResourceUpdated: (name: string, uri: string) => void;
+    protected readonly onProgress: (name: string, progress: MCPProgressNotification) => void;
+    protected readonly onLogMessage: (name: string, log: MCPLogMessageNotification) => void;
+    protected readonly onPromptsChanged: (name: string) => void;
+    protected addCatalogListeners(client: MCPClient): void;
+    protected removeCatalogListeners(client: MCPClient): void;
+    protected readonly onChildExit: (name: string, code: number | null, _signal: string | null) => void;
+    /** Handles SSE / streamable-http disconnect — same recovery as stdio child exit. */
+    protected readonly onTransportDisconnect: (name: string) => void;
+    protected scheduleReconnect(slot: ServerSlot): void;
+    protected attemptReconnect(slot: ServerSlot): Promise<void>;
+    protected recordSuccess(slot: ServerSlot, resetFailures?: boolean): void;
+    protected recordFailure(slot: ServerSlot, failureKind: MCPFailureKind, reason: string, durationMs?: number | undefined): void;
+    protected recordOperation(slot: ServerSlot, kind: MCPOperationKind, reason?: string | undefined, failureKind?: MCPFailureKind | undefined, durationMs?: number | undefined, retain?: boolean): void;
+    protected attemptConnect(slot: ServerSlot): Promise<void>;
+    abstract ensureConnected(name: string): Promise<MCPClient>;
+    abstract stop(name: string): Promise<void>;
+    abstract markDisabled(cfg: MCPServerConfig): void;
+}
+//# sourceMappingURL=registry-runtime.d.ts.map

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

@@ -0,0 +1,42 @@
+import type { EventBus } from '@wrongstack/core/kernel';
+import type { ToolRegistry } from '@wrongstack/core/registry';
+import type { Logger, MCPServerConfig } from '@wrongstack/core/types';
+import type { MCPClient } from './client.js';
+import type { MCPTool } from './contracts.js';
+import { type MCPFailureKind, type MCPOperationKind } from './operations.js';
+import { type RegistryIdleContext } from './registry-idle.js';
+import type { ServerSlot } from './registry-slots.js';
+export interface RegistryServerLifecycleHost {
+    servers: Map<string, ServerSlot>;
+    stop(name: string): Promise<void>;
+    markDisabled(cfg: MCPServerConfig): void;
+    disabledServers: Map<string, MCPServerConfig>;
+    cacheDir: string | undefined;
+    startLazy(slot: ServerSlot): Promise<void>;
+    singleFlightConnect(slot: ServerSlot): Promise<MCPClient | undefined>;
+    startups: Set<Promise<void>>;
+    applyTools(slot: ServerSlot, tools: MCPTool[], client?: MCPClient | undefined): void;
+    ensureIdleSweep(): void;
+    log: Logger;
+    attemptConnect(slot: ServerSlot): Promise<void>;
+    recordOperation(slot: ServerSlot, kind: MCPOperationKind, reason?: string | undefined, failureKind?: MCPFailureKind | undefined, durationMs?: number | undefined, retain?: boolean): void;
+    toolRegistry: ToolRegistry;
+    onChildExit: (name: string, code: number | null, _signal: string | null) => void;
+    onToolsChanged: (name: string, _tools: {
+        name: string;
+    }[]) => void;
+    removeCatalogListeners(client: MCPClient): void;
+    events: EventBus;
+    requireSlot(name: string): ServerSlot;
+    idleContext(): RegistryIdleContext;
+}
+export declare function start(host: RegistryServerLifecycleHost, cfg: MCPServerConfig): Promise<void>;
+export declare function startLazy(host: RegistryServerLifecycleHost, slot: ServerSlot): Promise<void>;
+export declare function singleFlightConnect(host: RegistryServerLifecycleHost, slot: ServerSlot): Promise<MCPClient | undefined>;
+export declare function ensureConnected(host: RegistryServerLifecycleHost, name: string): Promise<MCPClient>;
+export declare function activateServer(host: RegistryServerLifecycleHost, name: string): void;
+export declare function deactivateServer(host: RegistryServerLifecycleHost, name: string): number;
+export declare function stop(host: RegistryServerLifecycleHost, name: string): Promise<void>;
+export declare function sleep(host: RegistryServerLifecycleHost, name: string): Promise<void>;
+export declare function restart(host: RegistryServerLifecycleHost, name: string, nextCfg?: MCPServerConfig | undefined): Promise<void>;
+//# sourceMappingURL=registry-server-lifecycle.d.ts.map

package/dist/registry-slot-events.d.ts

@@ -0,0 +1,32 @@
+import type { MCPClient } from './client.js';
+import type { MCPLogMessageNotification, MCPProgressNotification } from './protocol.js';
+import type { MCPRegistryInternals } from './registry-internals.js';
+import type { ServerSlot } from './registry-slots.js';
+/**
+ * Bodies of the `MCPRegistry` listeners a connected client notifies:
+ * catalog/list-changed signals, live resource updates, progress/log
+ * telemetry, child exit and transport disconnect (plus the reconnect they
+ * schedule). The class keeps the stable arrow-function identities it
+ * registers and delegates to these.
+ */
+/**
+ * L2-C: handle `notifications/tools/list_changed` from the server.
+ * Unregister the previous wrapper set, then re-register the fresh
+ * tool list. The client has already refreshed its cache before
+ * dispatching — we just need to re-wrap and re-register.
+ * In lazy mode, only update the internal cache without registering.
+ */
+export declare function handleToolsChanged(self: MCPRegistryInternals, name: string): void;
+export declare function handleResourcesChanged(self: MCPRegistryInternals, name: string): void;
+export declare function handleResourceUpdated(self: MCPRegistryInternals, name: string, uri: string): void;
+export declare function handleProgress(self: MCPRegistryInternals, name: string, progress: MCPProgressNotification): void;
+export declare function handleLogMessage(self: MCPRegistryInternals, name: string, log: MCPLogMessageNotification): void;
+export declare function handlePromptsChanged(self: MCPRegistryInternals, name: string): void;
+export declare function attachCatalogListeners(self: MCPRegistryInternals, client: MCPClient): void;
+export declare function detachCatalogListeners(self: MCPRegistryInternals, client: MCPClient): void;
+export declare function handleChildExit(self: MCPRegistryInternals, name: string, code: number | null): void;
+/** Handles SSE / streamable-http disconnect — same recovery as stdio child exit. */
+export declare function handleTransportDisconnect(self: MCPRegistryInternals, name: string): void;
+export declare function scheduleSlotReconnect(self: MCPRegistryInternals, slot: ServerSlot): void;
+export declare function attemptSlotReconnect(self: MCPRegistryInternals, slot: ServerSlot): Promise<void>;
+//# sourceMappingURL=registry-slot-events.d.ts.map

package/dist/registry-slots.d.ts

@@ -1,5 +1,6 @@
 import type { MCPServerConfig, Tool } from '@wrongstack/core/types';
 import type { MCPClient } from './client.js';
+import type { MCPUnsupportedProtocolVersionError } from './constants.js';
 import type { ConnectionState, MCPTool } from './contracts.js';
 import type { ElicitationRequester } from './elicitation.js';
 import type { MCPServerOperationState } from './operations.js';
@@ -31,6 +32,15 @@ export interface ServerSlot {
     /** Serializes replacements so rapid list-change notifications cannot restore stale data. */
     manifestWrite?: Promise<void> | undefined;
     attempts: number;
+    /**
+     * The protocol-version refusal that ended the last connect attempt, if any.
+     *
+     * `attemptConnectSlot` swallows connect failures (a bad server must not
+     * reject `start()`), so without this the demand-wake path could only report
+     * a generic "failed to connect" and the refused revision — the one detail the
+     * operator can act on — would be lost. Cleared when an attempt begins.
+     */
+    protocolVersionRefusal?: MCPUnsupportedProtocolVersionError | undefined;
     /** Set when a reconnect cycle is already running for this slot. */
     reconnectPending: boolean;
     reconnectTimer?: NodeJS.Timeout | undefined;

package/dist/registry.d.ts

@@ -1,41 +1,18 @@
 import type { MCPServerConfig } from '@wrongstack/core/types';
-import type { MCPAuthorizationStartResult, MCPAuthorizationStatus } from './authorization-manager.js';
+import type { MCPAuthorizationLoginHandle, MCPAuthorizationLoginInput, MCPAuthorizationStartResult, MCPAuthorizationStatus } from './authorization-manager.js';
 import type { MCPClient } from './client.js';
 import type { MCPInsertionPolicy, MCPPromptInsertion, MCPResourceInsertion } from './content-selection.js';
-import type { ConnectionState } from './contracts.js';
-import { type MCPOperationListener, type MCPServerOperationalHealth } from './operations.js';
+import type { MCPOperationListener, MCPServerOperationalHealth } from './operations.js';
 import type { MCPGetPromptResult, MCPPrompt, MCPReadResourceResult, MCPResource, MCPResourceTemplate } from './protocol.js';
-import type { MCPRegistryCatalog, MCPRegistryOptions } from './registry-types.js';
+import { type MCPRegistryAuthorizationBeginInput } from './registry-authorization.js';
+import { describeServers, listServers, type MCPDescribedTool, serverHealth } from './registry-describe.js';
+import { MCPRegistryRuntime } from './registry-runtime.js';
+import type { MCPRegistryCatalog } from './registry-types.js';
+export type { MCPDescribedTool } from './registry-describe.js';
 export type { MCPRegistryCatalog, MCPRegistryOptions } from './registry-types.js';
-export declare class MCPRegistry {
-    private readonly servers;
-    /** Configured-off servers are tracked without creating a transport/client. */
-    private readonly disabledServers;
-    private readonly toolRegistry;
-    private readonly events;
-    private readonly log;
-    private readonly lazyMode;
-    private readonly cacheDir?;
-    private readonly cwd?;
-    private readonly idleTimeoutMs;
-    private readonly authorizationProviderFactory?;
-    private readonly authorizationManager?;
-    private readonly elicitationHandler?;
-    private readonly operationListeners;
-    /** Starts still in flight, for {@link whenStarted}. */
-    private readonly startups;
-    /** Single shared idle sweep timer (started lazily; unref'd; cleared on stopAll). */
-    private idleTimer?;
-    constructor(opts: MCPRegistryOptions);
-    private requireSlot;
-    loginAuthorization(name: string, input: Omit<import('./authorization-manager.js').MCPAuthorizationLoginInput, 'serverName' | 'resource'>): Promise<import('./authorization-manager.js').MCPAuthorizationLoginHandle>;
-    beginAuthorization(name: string, input: {
-        clientId?: string | undefined;
-        redirectUri: string;
-        scopes?: readonly string[] | undefined;
-        challengeHeader?: string | null | undefined;
-        signal?: AbortSignal | undefined;
-    }): Promise<MCPAuthorizationStartResult>;
+export declare class MCPRegistry extends MCPRegistryRuntime {
+    loginAuthorization(name: string, input: Omit<MCPAuthorizationLoginInput, 'serverName' | 'resource'>): Promise<MCPAuthorizationLoginHandle>;
+    beginAuthorization(name: string, input: MCPRegistryAuthorizationBeginInput): Promise<MCPAuthorizationStartResult>;
     completeAuthorization(name: string, callbackUrl: string, signal?: AbortSignal | undefined): Promise<MCPAuthorizationStatus>;
     authorizationStatus(name: string): Promise<MCPAuthorizationStatus>;
     disconnectAuthorization(name: string): Promise<boolean>;
@@ -51,14 +28,6 @@ export declare class MCPRegistry {
     markDisabled(cfg: MCPServerConfig): void;
     /** Remove residual operational/configuration state after a management delete. */
     forget(name: string): 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;
-    private singleFlightConnect;
     /**
      * Ensure a lazy server is connected, spawning it on demand. Single-flight:
      * concurrent first-calls share one connect. Resolver wrappers call this.
@@ -84,11 +53,7 @@ export declare class MCPRegistry {
      * of guessing and reading the error. Honors `allowedTools`. Returns
      * `undefined` for an unknown server, `[]` when nothing was discovered yet.
      */
-    describeTools(name: string): {
-        name: string;
-        description?: string | undefined;
-        inputSchema: Record<string, unknown>;
-    }[] | undefined;
+    describeTools(name: string): MCPDescribedTool[] | undefined;
     /**
      * Check whether a server's tools are currently registered.
      */
@@ -111,12 +76,7 @@ export declare class MCPRegistry {
      */
     sleep(name: string): Promise<void>;
     restart(name: string, nextCfg?: MCPServerConfig | undefined): Promise<void>;
-    list(): {
-        name: string;
-        state: ConnectionState;
-        toolCount: number;
-        tools: string[];
-    }[];
+    list(): ReturnType<typeof listServers>;
     /**
      * Subscribe to payload-free operational signals. Callers must still avoid
      * using `serverName` as an unbounded metric label.
@@ -139,70 +99,19 @@ export declare class MCPRegistry {
         refresh?: boolean;
     }): Promise<MCPPrompt[]>;
     getPrompt(serverName: string, promptName: string, args?: Record<string, string> | undefined): Promise<MCPGetPromptResult>;
-    /** Keep all remote requests awake and reject results from superseded clients. */
-    private withConnectedClient;
     selectPromptForInsertion(serverName: string, promptName: string, args?: Record<string, string> | undefined, policy?: MCPInsertionPolicy | undefined): Promise<MCPPromptInsertion>;
-    /**
-     * 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;
-    private connectContext;
-    private idleContext;
-    private applyTools;
-    private persistCapabilityManifest;
-    /** Start the shared idle sweep timer once (unref'd so it never holds the process). */
-    private ensureIdleSweep;
-    private sweepIdle;
     /**
      * Catalog of every server ever registered with this registry — includes
      * servers that are stopped, failed, or not yet started.
      * Useful for the `mcp_control` tool to show all known servers without
      * triggering connections.
      */
-    describe(): {
-        name: string;
-        state: ConnectionState;
-        toolCount: number;
-        enabled: boolean;
-        tools: string[];
-    }[];
+    describe(): ReturnType<typeof describeServers>;
     stopAll(): Promise<void>;
     /**
      * Health check — returns 'ok' for connected servers, the current state otherwise.
      * For HTTP-based transports this could also ping the server.
      */
-    health(): {
-        name: string;
-        alive: boolean;
-        latencyMs?: number | undefined;
-    }[];
-    /**
-     * L2-C: handle `notifications/tools/list_changed` from the server.
-     * Unregister the previous wrapper set, then re-register the fresh
-     * tool list. The client has already refreshed its cache before
-     * dispatching — we just need to re-wrap and re-register.
-     * In lazy mode, only update the internal cache without registering.
-     */
-    private readonly onToolsChanged;
-    private readonly onResourcesChanged;
-    private readonly onResourceUpdated;
-    private readonly onPromptsChanged;
-    private addCatalogListeners;
-    private removeCatalogListeners;
-    private readonly onChildExit;
-    /** Handles SSE / streamable-http disconnect — same recovery as stdio child exit. */
-    private readonly onTransportDisconnect;
-    private static readonly MAX_RECONNECT_CYCLES;
-    private static readonly BASE_RECONNECT_DELAY_MS;
-    private static readonly MAX_RECONNECT_DELAY_MS;
-    private scheduleReconnect;
-    private attemptReconnect;
-    private recordSuccess;
-    private recordFailure;
-    private recordOperation;
-    private attemptConnect;
-    private registryCatalogOperationsHost;
+    health(): ReturnType<typeof serverHealth>;
 }
 //# sourceMappingURL=registry.d.ts.map

package/dist/server-dispatch.d.ts

@@ -1,3 +1,4 @@
+import type { MCPToolAnnotations } from './contracts.js';
 import type { MCPPromptArgument, MCPPromptMessage, MCPResourceContents } from './protocol.js';
 /**
  * Server-side MCP. The mirror image of `MCPClient`: instead of consuming a
@@ -15,6 +16,14 @@ export interface MCPServerTool {
     name: string;
     description?: string | undefined;
     inputSchema: Record<string, unknown>;
+    /**
+     * `ToolAnnotations` (spec 2025-03-26) — this server's own claim about its
+     * behaviour, published verbatim by `tools/list`. A client MUST treat it as
+     * untrusted, so publishing it never relaxes anything on our side: the
+     * permission tier of a proxied tool comes from WrongStack policy, not from a
+     * hint in this object.
+     */
+    annotations?: MCPToolAnnotations | undefined;
 }
 /** The result of a `tools/call`, as the host produces it. */
 export interface MCPServerCallResult {
@@ -133,13 +142,38 @@ export declare class MCPServer {
 /** Cap on how many schema violations are echoed back in one error message. */
 export declare const MAX_REPORTED_SCHEMA_ERRORS = 5;
 /**
- * Marks a `tools/call` rejected by {@link MCPServer.assertArgumentsMatchSchema}
- * so `handleMessage` can answer with JSON-RPC `-32602 Invalid params` rather
- * than the generic internal-error code every other throw maps to.
+ * Marks a `tools/call` rejected by {@link MCPServer.assertArgumentsMatchSchema}.
+ * SEP-1303: `handleMessage` answers these in-band — `{ content, isError: true }`
+ * — so the model sees the refusal and can retry with corrected arguments,
+ * instead of a JSON-RPC error that stays inside the transport.
  */
 export declare class InvalidToolArgumentsError extends Error {
     readonly name = "InvalidToolArgumentsError";
 }
+/**
+ * Base for every failure that is the *caller's* request error, mapped to
+ * JSON-RPC `-32602 Invalid params`. Current MCP assigns no dedicated code to these:
+ * `prompts.md` prescribes `-32602` for an invalid prompt name AND for missing
+ * required arguments, and `resources.md` retired the old `-32002` in favour of
+ * the same code. Use this (or a subclass) instead of a bare `throw`, which
+ * `handleMessage` would otherwise report as `-32603 Internal error` — a code
+ * clients legitimately retry.
+ */
+export declare class InvalidParamsError extends Error {
+    readonly name: string;
+}
+/**
+ * Marks a lookup for a resource or prompt that does not exist.
+ *
+ * JSON-RPC has no "not found" code, and MCP retired its own `-32002` in favour
+ * of plain Invalid params, so this maps to `-32602` rather than the
+ * `-32603 Internal error` a bare `throw` would produce. A caller asking for one
+ * URI out of a known-good catalog made a request error, not a server failure —
+ * and callers key retry policy off that difference.
+ */
+export declare class InvalidLookupError extends InvalidParamsError {
+    readonly name = "InvalidLookupError";
+}
 export declare const SERVER_PAGE_SIZE = 100;
 export declare function paginate<T>(items: T[], params: unknown): {
     items: T[];

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 export type { MCPServerCallResult, MCPServerLogger, MCPServerOptions, MCPServerPrompt, MCPServerResource, MCPServerTool, MCPServerToolHost, } from './server-dispatch.js';
-export { InvalidToolArgumentsError, MCPServer, toContentBlocks } from './server-dispatch.js';
+export { InvalidLookupError, InvalidParamsError, InvalidToolArgumentsError, MCPServer, toContentBlocks, } from './server-dispatch.js';
 export type { ServeHttpHandle, ServeHttpOptions } from './server-http.js';
 export { handleHttpRequest, serveHttp } from './server-http.js';
 export type { ServeStdioHandle, ServeStdioOptions } from './server-stdio.js';