@winstonsayno/mcp-gateway 0.0.0-stage → 0.3.0

package/dist/gateway/supervisor.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Server supervisor — keeps every enabled MCP server connected.
+ *
+ * - Connects servers and publishes their tools and health to the registry.
+ * - When a server fails to connect, crashes or disconnects (`proxy` emits
+ *   `disconnected`), it schedules a reconnect with exponential backoff and
+ *   jitter, re-running the full MCP handshake on a fresh channel.
+ * - Reconnect state (attempt, next attempt time, last error, reconnect count)
+ *   is mirrored into the registry so `/servers`, `/health`, the dashboard and
+ *   Prometheus can show it.
+ *
+ * Each server carries a generation number; a hot reload or removal bumps it so
+ * an in-flight attempt that finishes late can never resurrect stale state.
+ *
+ * @module gateway/supervisor
+ */
+import type { McpServerConfig, ReconnectConfig, ReconnectState } from '../utils/types.js';
+import type { McpProxy } from '../proxy/index.js';
+import type { ServerRegistry } from '../registry/index.js';
+export declare const DEFAULT_RECONNECT: ReconnectConfig;
+export declare function resolveReconnect(gateway?: Partial<ReconnectConfig>, server?: Partial<ReconnectConfig>): ReconnectConfig;
+/**
+ * Delay before reconnect attempt `attempt` (1-based):
+ * `min(maxDelay, initialDelay * multiplier^(attempt-1))`, then ±jitter.
+ */
+export declare function computeBackoff(attempt: number, cfg: ReconnectConfig, random?: () => number): number;
+export interface SupervisorOptions {
+    /** Gateway-wide reconnect defaults (merged with each server's `reconnect`). */
+    reconnect?: Partial<ReconnectConfig>;
+    random?: () => number;
+}
+export declare class ServerSupervisor {
+    private readonly proxy;
+    private readonly registry;
+    private readonly entries;
+    private reconnectDefaults?;
+    private readonly random;
+    private stopped;
+    private readonly onDisconnected;
+    private readonly onToolsChanged;
+    constructor(proxy: McpProxy, registry: ServerRegistry, options?: SupervisorOptions);
+    /** Update gateway-wide reconnect defaults (hot reload). Applies to future attempts. */
+    setReconnectDefaults(reconnect?: Partial<ReconnectConfig>): void;
+    /** Connect (or reconnect with a new config) now. Resolves true on success. */
+    connect(config: McpServerConfig): Promise<boolean>;
+    /** Stop managing a server (cancel pending reconnects). Does not disconnect it. */
+    forget(serverId: string): void;
+    /** Is a reconnect scheduled or in progress for this server? */
+    isRecovering(serverId: string): boolean;
+    getState(serverId: string): ReconnectState | undefined;
+    stop(): void;
+    private current;
+    private attempt;
+    private handleDisconnect;
+    private scheduleRetry;
+    private publish;
+}
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/gateway/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/gateway/supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAY,MAAM,mBAAmB,CAAC;AACpG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,eAAO,MAAM,iBAAiB,EAAE,eAO/B,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EAClC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAChC,eAAe,CAMjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,GAAE,MAAM,MAAoB,GAAG,MAAM,CAMhH;AAUD,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED,qBAAa,gBAAgB;IAazB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAb3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,iBAAiB,CAAC,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0E;IACzG,OAAO,CAAC,QAAQ,CAAC,cAAc,CAI7B;gBAGiB,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,cAAc,EACzC,OAAO,GAAE,iBAAsB;IAQjC,uFAAuF;IACvF,oBAAoB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IAKhE,8EAA8E;IACxE,OAAO,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAexD,kFAAkF;IAClF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAO9B,+DAA+D;IAC/D,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAKtD,IAAI,IAAI,IAAI;IAUZ,OAAO,CAAC,OAAO;YAID,OAAO;IAgCrB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,OAAO;CAUhB"}

package/dist/gateway/supervisor.js

@@ -0,0 +1,205 @@
+/**
+ * Server supervisor — keeps every enabled MCP server connected.
+ *
+ * - Connects servers and publishes their tools and health to the registry.
+ * - When a server fails to connect, crashes or disconnects (`proxy` emits
+ *   `disconnected`), it schedules a reconnect with exponential backoff and
+ *   jitter, re-running the full MCP handshake on a fresh channel.
+ * - Reconnect state (attempt, next attempt time, last error, reconnect count)
+ *   is mirrored into the registry so `/servers`, `/health`, the dashboard and
+ *   Prometheus can show it.
+ *
+ * Each server carries a generation number; a hot reload or removal bumps it so
+ * an in-flight attempt that finishes late can never resurrect stale state.
+ *
+ * @module gateway/supervisor
+ */
+import { logger } from '../utils/logger.js';
+export const DEFAULT_RECONNECT = {
+    enabled: true,
+    initialDelayMs: 1_000,
+    maxDelayMs: 60_000,
+    multiplier: 2,
+    jitter: 0.2,
+    maxAttempts: 0,
+};
+export function resolveReconnect(gateway, server) {
+    const strip = (o) => Object.fromEntries(Object.entries(o ?? {}).filter(([, v]) => v !== undefined));
+    const merged = { ...DEFAULT_RECONNECT, ...strip(gateway), ...strip(server) };
+    merged.maxDelayMs = Math.max(merged.maxDelayMs, merged.initialDelayMs);
+    return merged;
+}
+/**
+ * Delay before reconnect attempt `attempt` (1-based):
+ * `min(maxDelay, initialDelay * multiplier^(attempt-1))`, then ±jitter.
+ */
+export function computeBackoff(attempt, cfg, random = Math.random) {
+    const exp = cfg.initialDelayMs * Math.pow(cfg.multiplier, Math.max(0, attempt - 1));
+    const base = Math.min(cfg.maxDelayMs, exp);
+    const spread = base * cfg.jitter;
+    const jittered = base - spread + random() * 2 * spread;
+    return Math.max(0, Math.round(Math.min(cfg.maxDelayMs, jittered)));
+}
+export class ServerSupervisor {
+    proxy;
+    registry;
+    entries = new Map();
+    reconnectDefaults;
+    random;
+    stopped = false;
+    onDisconnected = (serverId, err) => this.handleDisconnect(serverId, err);
+    onToolsChanged = (serverId, tools) => {
+        if (!this.entries.has(serverId))
+            return;
+        this.registry.setTools(serverId, tools);
+        logger.info(`Server "${serverId}" updated its tool list (${tools.length} tools)`);
+    };
+    constructor(proxy, registry, options = {}) {
+        this.proxy = proxy;
+        this.registry = registry;
+        this.reconnectDefaults = options.reconnect;
+        this.random = options.random ?? Math.random;
+        proxy.on('disconnected', this.onDisconnected);
+        proxy.on('tools-changed', this.onToolsChanged);
+    }
+    /** Update gateway-wide reconnect defaults (hot reload). Applies to future attempts. */
+    setReconnectDefaults(reconnect) {
+        this.reconnectDefaults = reconnect;
+        for (const e of this.entries.values())
+            e.policy = resolveReconnect(reconnect, e.config.reconnect);
+    }
+    /** Connect (or reconnect with a new config) now. Resolves true on success. */
+    async connect(config) {
+        if (this.stopped)
+            return false;
+        const prev = this.entries.get(config.id);
+        if (prev?.timer)
+            clearTimeout(prev.timer);
+        const entry = {
+            config,
+            policy: resolveReconnect(this.reconnectDefaults, config.reconnect),
+            gen: (prev?.gen ?? 0) + 1,
+            state: { state: 'connecting', attempt: 0, reconnects: prev?.state.reconnects ?? 0 },
+        };
+        this.entries.set(config.id, entry);
+        this.publish(entry);
+        return this.attempt(entry, entry.gen, false);
+    }
+    /** Stop managing a server (cancel pending reconnects). Does not disconnect it. */
+    forget(serverId) {
+        const e = this.entries.get(serverId);
+        if (!e)
+            return;
+        if (e.timer)
+            clearTimeout(e.timer);
+        this.entries.delete(serverId);
+    }
+    /** Is a reconnect scheduled or in progress for this server? */
+    isRecovering(serverId) {
+        const s = this.entries.get(serverId)?.state.state;
+        return s === 'scheduled' || s === 'connecting';
+    }
+    getState(serverId) {
+        const e = this.entries.get(serverId);
+        return e ? { ...e.state } : undefined;
+    }
+    stop() {
+        this.stopped = true;
+        for (const e of this.entries.values())
+            if (e.timer)
+                clearTimeout(e.timer);
+        this.entries.clear();
+        this.proxy.off('disconnected', this.onDisconnected);
+        this.proxy.off('tools-changed', this.onToolsChanged);
+    }
+    // ─── Internal ───────────────────────────────────────────────────────────────
+    current(entry, gen) {
+        return !this.stopped && this.entries.get(entry.config.id) === entry && entry.gen === gen;
+    }
+    async attempt(entry, gen, isReconnect) {
+        const { config } = entry;
+        entry.state.state = 'connecting';
+        entry.state.nextAttemptAt = undefined;
+        this.publish(entry);
+        try {
+            const tools = await this.proxy.connect(config);
+            if (!this.current(entry, gen))
+                return false; // superseded by reload/removal
+            entry.state = {
+                state: 'idle',
+                attempt: 0,
+                reconnects: entry.state.reconnects + (isReconnect ? 1 : 0),
+                lastDisconnectAt: entry.state.lastDisconnectAt,
+            };
+            this.registry.setTools(config.id, tools);
+            this.registry.updateHealth(config.id, 'online', undefined, undefined, {
+                connectedSince: new Date(),
+                reconnect: { ...entry.state },
+            });
+            logger.info(`✓ ${config.name} — ${tools.length} tools available${isReconnect ? ' (reconnected)' : ''}`);
+            return true;
+        }
+        catch (err) {
+            if (!this.current(entry, gen))
+                return false;
+            const msg = err instanceof Error ? err.message : String(err);
+            entry.state.lastError = msg;
+            if (!isReconnect)
+                this.registry.setTools(config.id, []);
+            logger.warn(`✗ ${config.name} — failed to connect: ${msg}`);
+            this.scheduleRetry(entry, gen);
+            return false;
+        }
+    }
+    handleDisconnect(serverId, err) {
+        const entry = this.entries.get(serverId);
+        if (!entry || this.stopped)
+            return;
+        entry.state.lastError = err.message;
+        entry.state.lastDisconnectAt = new Date();
+        entry.state.attempt = 0;
+        // Tools stay listed (marked unavailable via health) so clients see what will come back.
+        logger.warn(`Server "${serverId}" disconnected: ${err.message}`);
+        this.scheduleRetry(entry, entry.gen);
+    }
+    scheduleRetry(entry, gen) {
+        const { policy } = entry;
+        if (!policy.enabled) {
+            entry.state.state = 'disabled';
+            this.publish(entry, 'offline');
+            return;
+        }
+        if (policy.maxAttempts > 0 && entry.state.attempt >= policy.maxAttempts) {
+            entry.state.state = 'gave-up';
+            logger.error(`Server "${entry.config.id}": giving up after ${entry.state.attempt} reconnect attempts`);
+            this.publish(entry, 'offline');
+            return;
+        }
+        entry.state.attempt++;
+        const delay = computeBackoff(entry.state.attempt, policy, this.random);
+        entry.state.state = 'scheduled';
+        entry.state.nextAttemptAt = new Date(Date.now() + delay);
+        logger.info(`Reconnecting "${entry.config.id}" in ${delay}ms (attempt ${entry.state.attempt})`);
+        this.publish(entry, 'reconnecting');
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = setTimeout(() => {
+            entry.timer = undefined;
+            if (this.current(entry, gen))
+                void this.attempt(entry, gen, true);
+        }, delay);
+        entry.timer.unref();
+    }
+    publish(entry, status) {
+        const id = entry.config.id;
+        if (!this.registry.getServer(id))
+            return;
+        const prev = this.registry.getHealth(id);
+        const next = status ?? prev?.status ?? 'unknown';
+        this.registry.updateHealth(id, next, undefined, entry.state.lastError, {
+            reconnect: { ...entry.state },
+            connectedSince: status ? undefined : prev?.connectedSince,
+        });
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/gateway/supervisor.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * mcp-gateway public API
+ * Use this when embedding the gateway as a library
+ */
+export { Gateway } from './gateway/index.js';
+export { ServerRegistry } from './registry/index.js';
+export { McpProxy, defaultChannelFactory, MCP_PROTOCOL_VERSION } from './proxy/index.js';
+export type { ProxyOptions, SessionInfo } from './proxy/index.js';
+export { ServerSupervisor, computeBackoff, DEFAULT_RECONNECT } from './gateway/supervisor.js';
+export type { UpstreamChannel, ChannelFactory, ChannelOptions, JsonRpcMessage } from './transport/channel.js';
+export { MetricsCollector } from './monitor/index.js';
+export { loadConfig, generateDefaultConfig } from './config/loader.js';
+export { logger } from './utils/logger.js';
+export type { GatewayConfig, McpServerConfig, ServerHealth, ServerStatus, ServerTransport, ToolInfo, RequestMetric, AggregatedMetrics, AuthConfig, RateLimitConfig, MonitorConfig, ReconnectConfig, ReconnectState, } from './utils/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzF,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC9F,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC9G,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,YAAY,EACV,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * mcp-gateway public API
+ * Use this when embedding the gateway as a library
+ */
+export { Gateway } from './gateway/index.js';
+export { ServerRegistry } from './registry/index.js';
+export { McpProxy, defaultChannelFactory, MCP_PROTOCOL_VERSION } from './proxy/index.js';
+export { ServerSupervisor, computeBackoff, DEFAULT_RECONNECT } from './gateway/supervisor.js';
+export { MetricsCollector } from './monitor/index.js';
+export { loadConfig, generateDefaultConfig } from './config/loader.js';
+export { logger } from './utils/logger.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAEzF,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/middleware/cors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CORS Middleware
+ *
+ * Configurable Cross-Origin Resource Sharing headers.
+ * Supports wildcard, specific origins list, and regex patterns.
+ *
+ * @module middleware/cors
+ */
+import { Request, Response, NextFunction } from 'express';
+export interface CORSOptions {
+    origins: string[];
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+export declare function corsMiddleware(options: CORSOptions): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=cors.d.ts.map

package/dist/middleware/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAUD,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,IA0BzC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CA+B/D"}

package/dist/middleware/cors.js

@@ -0,0 +1,65 @@
+/**
+ * CORS Middleware
+ *
+ * Configurable Cross-Origin Resource Sharing headers.
+ * Supports wildcard, specific origins list, and regex patterns.
+ *
+ * @module middleware/cors
+ */
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+const DEFAULT_HEADERS = [
+    'Content-Type',
+    'Authorization',
+    'X-API-Key',
+    'X-Request-Id',
+];
+export function corsMiddleware(options) {
+    const { origins, methods = DEFAULT_METHODS, allowedHeaders = DEFAULT_HEADERS, exposedHeaders = ['X-Request-Id', 'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reset'], credentials = false, maxAge = 86400, } = options;
+    const isAllowed = (origin) => {
+        for (const o of origins) {
+            if (o === '*')
+                return true;
+            if (o === origin)
+                return true;
+            // Support regex patterns wrapped in /…/
+            if (o.startsWith('/') && o.endsWith('/')) {
+                try {
+                    if (new RegExp(o.slice(1, -1)).test(origin))
+                        return true;
+                }
+                catch {
+                    // invalid regex — skip
+                }
+            }
+        }
+        return false;
+    };
+    return (req, res, next) => {
+        const origin = req.headers.origin ?? '';
+        const wildcard = origins.includes('*');
+        if (wildcard && !credentials) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+        }
+        else {
+            // Response depends on Origin: tell caches so (even when disallowed).
+            res.vary('Origin');
+            // Browsers reject "*" together with credentials, so reflect the origin.
+            if (origin && isAllowed(origin)) {
+                res.setHeader('Access-Control-Allow-Origin', origin);
+            }
+        }
+        if (credentials) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        res.setHeader('Access-Control-Expose-Headers', exposedHeaders.join(', '));
+        if (req.method === 'OPTIONS') {
+            res.setHeader('Access-Control-Allow-Methods', methods.join(', '));
+            res.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+            res.setHeader('Access-Control-Max-Age', String(maxAge));
+            res.status(204).end();
+            return;
+        }
+        next();
+    };
+}
+//# sourceMappingURL=cors.js.map

package/dist/middleware/cors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.js","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC7E,MAAM,eAAe,GAAG;IACtB,cAAc;IACd,eAAe;IACf,WAAW;IACX,cAAc;CACf,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,OAAoB;IACjD,MAAM,EACJ,OAAO,EACP,OAAO,GAAG,eAAe,EACzB,cAAc,GAAG,eAAe,EAChC,cAAc,GAAG,CAAC,cAAc,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,mBAAmB,CAAC,EACpG,WAAW,GAAG,KAAK,EACnB,MAAM,GAAG,KAAK,GACf,GAAG,OAAO,CAAC;IAEZ,MAAM,SAAS,GAAG,CAAC,MAAc,EAAW,EAAE;QAC5C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,GAAG;gBAAE,OAAO,IAAI,CAAC;YAC3B,IAAI,CAAC,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC;YAC9B,wCAAwC;YACxC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzC,IAAI,CAAC;oBACH,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;wBAAE,OAAO,IAAI,CAAC;gBAC3D,CAAC;gBAAC,MAAM,CAAC;oBACP,uBAAuB;gBACzB,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAC/D,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;QAExC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,IAAI,CAAC,WAAW,EAAE,CAAC;YAC7B,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,qEAAqE;YACrE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACnB,wEAAwE;YACxE,IAAI,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBAChC,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,MAAM,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;QAED,IAAI,WAAW,EAAE,CAAC;YAChB,GAAG,CAAC,SAAS,CAAC,kCAAkC,EAAE,MAAM,CAAC,CAAC;QAC5D,CAAC;QAED,GAAG,CAAC,SAAS,CAAC,+BAA+B,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAE1E,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC7B,GAAG,CAAC,SAAS,CAAC,8BAA8B,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YAClE,GAAG,CAAC,SAAS,CAAC,8BAA8B,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YACzE,GAAG,CAAC,SAAS,CAAC,wBAAwB,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YACxD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Centralized Error Handler Middleware
+ *
+ * Bug fix (v0.1.0): unhandled errors leaked raw stack traces and returned
+ * inconsistent response shapes. This middleware normalises all errors into
+ * a single JSON envelope and never exposes internal stack traces in production.
+ *
+ * @module middleware/error-handler
+ */
+import { Request, Response, NextFunction } from 'express';
+export interface ErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        requestId?: string;
+        details?: unknown;
+    };
+}
+export declare class GatewayError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(statusCode: number, code: string, message: string, details?: unknown | undefined);
+}
+export declare const ErrorCodes: {
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
+    readonly SERVER_NOT_FOUND: "SERVER_NOT_FOUND";
+    readonly SERVER_UNAVAILABLE: "SERVER_UNAVAILABLE";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+};
+export declare function errorHandler(err: unknown, req: Request, res: Response, _next: NextFunction): void;
+export declare function notFoundHandler(req: Request, res: Response): void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/middleware/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,qBAAa,YAAa,SAAQ,KAAK;aAEnB,UAAU,EAAE,MAAM;aAClB,IAAI,EAAE,MAAM;aAEZ,OAAO,CAAC,EAAE,OAAO;gBAHjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAGD,eAAO,MAAM,UAAU;;;;;;;;;;;;CAYb,CAAC;AAEX,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,YAAY,GAClB,IAAI,CAmDN;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CASjE"}

package/dist/middleware/error-handler.js

@@ -0,0 +1,98 @@
+/**
+ * Centralized Error Handler Middleware
+ *
+ * Bug fix (v0.1.0): unhandled errors leaked raw stack traces and returned
+ * inconsistent response shapes. This middleware normalises all errors into
+ * a single JSON envelope and never exposes internal stack traces in production.
+ *
+ * @module middleware/error-handler
+ */
+export class GatewayError extends Error {
+    statusCode;
+    code;
+    details;
+    constructor(statusCode, code, message, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.details = details;
+        this.name = 'GatewayError';
+    }
+}
+// Well-known error codes
+export const ErrorCodes = {
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    FORBIDDEN: 'FORBIDDEN',
+    NOT_FOUND: 'NOT_FOUND',
+    TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
+    SERVER_NOT_FOUND: 'SERVER_NOT_FOUND',
+    SERVER_UNAVAILABLE: 'SERVER_UNAVAILABLE',
+    RATE_LIMITED: 'RATE_LIMITED',
+    TIMEOUT: 'TIMEOUT',
+    BAD_REQUEST: 'BAD_REQUEST',
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+};
+export function errorHandler(err, req, res, _next) {
+    const isDev = process.env.NODE_ENV !== 'production';
+    // Headers already flushed (e.g. a late timeout): let Express close the socket.
+    if (res.headersSent) {
+        _next(err);
+        return;
+    }
+    if (err instanceof GatewayError) {
+        const body = {
+            error: {
+                code: err.code,
+                message: err.message,
+                requestId: req.requestId,
+                ...(isDev && err.details ? { details: err.details } : {}),
+            },
+        };
+        res.status(err.statusCode).json(body);
+        return;
+    }
+    // Client errors raised by Express / body-parser (malformed JSON, payload too
+    // large, …) carry a 4xx status and must not be reported as 500s.
+    const status = getHttpStatus(err);
+    if (status !== undefined && status >= 400 && status < 500) {
+        const body = {
+            error: {
+                code: status === 413 ? 'PAYLOAD_TOO_LARGE' : ErrorCodes.BAD_REQUEST,
+                message: err instanceof Error ? err.message : 'Bad request',
+                requestId: req.requestId,
+            },
+        };
+        res.status(status).json(body);
+        return;
+    }
+    // Unknown / unexpected errors
+    const message = isDev && err instanceof Error ? err.message : 'Internal server error';
+    const body = {
+        error: {
+            code: ErrorCodes.INTERNAL_ERROR,
+            message,
+            requestId: req.requestId,
+            ...(isDev && err instanceof Error ? { details: err.stack } : {}),
+        },
+    };
+    res.status(500).json(body);
+}
+export function notFoundHandler(req, res) {
+    const body = {
+        error: {
+            code: ErrorCodes.NOT_FOUND,
+            message: `Route ${req.method} ${req.path} not found`,
+            requestId: req.requestId,
+        },
+    };
+    res.status(404).json(body);
+}
+function getHttpStatus(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    const s = typeof e.status === 'number' ? e.status : typeof e.statusCode === 'number' ? e.statusCode : undefined;
+    return s !== undefined && Number.isInteger(s) ? s : undefined;
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAEnB;IACA;IAEA;IAJlB,YACkB,UAAkB,EAClB,IAAY,EAC5B,OAAe,EACC,OAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QALC,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;QAEZ,YAAO,GAAP,OAAO,CAAU;QAGjC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,yBAAyB;AACzB,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IACtB,SAAS,EAAE,WAAW;IACtB,cAAc,EAAE,gBAAgB;IAChC,gBAAgB,EAAE,kBAAkB;IACpC,kBAAkB,EAAE,oBAAoB;IACxC,YAAY,EAAE,cAAc;IAC5B,OAAO,EAAE,SAAS;IAClB,WAAW,EAAE,aAAa;IAC1B,cAAc,EAAE,gBAAgB;IAChC,gBAAgB,EAAE,kBAAkB;CAC5B,CAAC;AAEX,MAAM,UAAU,YAAY,CAC1B,GAAY,EACZ,GAAY,EACZ,GAAa,EACb,KAAmB;IAEnB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;IAEpD,+EAA+E;IAC/E,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACpB,KAAK,CAAC,GAAG,CAAC,CAAC;QACX,OAAO;IACT,CAAC;IAED,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,GAAkB;YAC1B,KAAK,EAAE;gBACL,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,SAAS,EAAG,GAAW,CAAC,SAAS;gBACjC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1D;SACF,CAAC;QACF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO;IACT,CAAC;IAED,6EAA6E;IAC7E,iEAAiE;IACjE,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAkB;YAC1B,KAAK,EAAE;gBACL,IAAI,EAAE,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW;gBACnE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa;gBAC3D,SAAS,EAAG,GAAW,CAAC,SAAS;aAClC;SACF,CAAC;QACF,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IAED,8BAA8B;IAC9B,MAAM,OAAO,GACX,KAAK,IAAI,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAExE,MAAM,IAAI,GAAkB;QAC1B,KAAK,EAAE;YACL,IAAI,EAAE,UAAU,CAAC,cAAc;YAC/B,OAAO;YACP,SAAS,EAAG,GAAW,CAAC,SAAS;YACjC,GAAG,CAAC,KAAK,IAAI,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE;KACF,CAAC;IAEF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,GAAa;IACzD,MAAM,IAAI,GAAkB;QAC1B,KAAK,EAAE;YACL,IAAI,EAAE,UAAU,CAAC,SAAS;YAC1B,OAAO,EAAE,SAAS,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,YAAY;YACpD,SAAS,EAAG,GAAW,CAAC,SAAS;SAClC;KACF,CAAC;IACF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,aAAa,CAAC,GAAY;IACjC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACtD,MAAM,CAAC,GAAG,GAAiD,CAAC;IAC5D,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAChH,OAAO,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChE,CAAC"}

package/dist/middleware/request-id.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Request ID Middleware
+ *
+ * Attaches a unique `X-Request-Id` header to every request and response,
+ * enabling end-to-end tracing across logs and downstream systems.
+ *
+ * Priority order:
+ *   1. Honour an existing `X-Request-Id` header sent by the client
+ *   2. Honour `X-Correlation-Id` (common in enterprise proxies)
+ *   3. Generate a new UUID v4
+ *
+ * @module middleware/request-id
+ */
+import { Request, Response, NextFunction } from 'express';
+declare global {
+    namespace Express {
+        interface Request {
+            requestId: string;
+        }
+    }
+}
+export declare function requestIdMiddleware(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/middleware/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../../src/middleware/request-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,SAAS,EAAE,MAAM,CAAC;SACnB;KACF;CACF;AAWD,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,IAAI,CASN"}

package/dist/middleware/request-id.js

@@ -0,0 +1,30 @@
+/**
+ * Request ID Middleware
+ *
+ * Attaches a unique `X-Request-Id` header to every request and response,
+ * enabling end-to-end tracing across logs and downstream systems.
+ *
+ * Priority order:
+ *   1. Honour an existing `X-Request-Id` header sent by the client
+ *   2. Honour `X-Correlation-Id` (common in enterprise proxies)
+ *   3. Generate a new UUID v4
+ *
+ * @module middleware/request-id
+ */
+import { randomUUID } from 'crypto';
+// Client-supplied ids are echoed into headers and logs: accept only a safe,
+// bounded charset to prevent log forging / oversized headers.
+const SAFE_ID = /^[A-Za-z0-9._:\-]{1,128}$/;
+function pick(value) {
+    const v = Array.isArray(value) ? value[0] : value;
+    return v && SAFE_ID.test(v) ? v : undefined;
+}
+export function requestIdMiddleware(req, res, next) {
+    const id = pick(req.headers['x-request-id']) ||
+        pick(req.headers['x-correlation-id']) ||
+        randomUUID();
+    req.requestId = id;
+    res.setHeader('X-Request-Id', id);
+    next();
+}
+//# sourceMappingURL=request-id.js.map

package/dist/middleware/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.js","sourceRoot":"","sources":["../../src/middleware/request-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAWpC,4EAA4E;AAC5E,8DAA8D;AAC9D,MAAM,OAAO,GAAG,2BAA2B,CAAC;AAE5C,SAAS,IAAI,CAAC,KAAoC;IAChD,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAClD,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAAY,EACZ,GAAa,EACb,IAAkB;IAElB,MAAM,EAAE,GACN,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACrC,UAAU,EAAE,CAAC;IAEf,GAAG,CAAC,SAAS,GAAG,EAAE,CAAC;IACnB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC;AACT,CAAC"}

package/dist/middleware/timeout.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Request Timeout Middleware
+ *
+ * Bug fix (v0.1.0): tool-call requests to slow or unresponsive MCP servers
+ * could hang indefinitely, exhausting the Node.js event loop.
+ * This middleware enforces a per-request deadline and returns a 504 response.
+ *
+ * @module middleware/timeout
+ */
+import { Request, Response, NextFunction } from 'express';
+export declare function timeoutMiddleware(timeoutMs: number): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=timeout.d.ts.map