@mcp-rating/gateway 0.2.0

package/dist/config/types.d.ts

@@ -0,0 +1,76 @@
+export interface GatewayConfig {
+    /** MCP-Rating API base URL for registry lookups */
+    registryApiUrl: string;
+    /** Timeout for proxied tool calls in milliseconds */
+    proxyTimeoutMs: number;
+    /** Maximum simultaneous downstream server connections */
+    maxConnections: number;
+    /** Log level (stderr only — stdout is MCP JSON-RPC) */
+    logLevel: "debug" | "info" | "warn" | "error";
+    /** Path to permissions persistence file */
+    permissionsPath: string;
+    /** Path to gateway config file */
+    configPath: string;
+    /** Path to connection profiles file for auto-connect on startup */
+    profilesPath: string;
+    /** TTL for registry API cache entries in milliseconds (default 300_000 = 5 min) */
+    registryCacheTtlMs: number;
+    /** Max reconnect attempts when a downstream server crashes (default 5) */
+    reconnectMaxAttempts: number;
+    /** Base delay in ms for exponential reconnect backoff (default 1000) */
+    reconnectBaseDelayMs: number;
+    /** Interval in ms between health check pings (default 30_000) */
+    healthCheckIntervalMs: number;
+    /** Optional partner API key for ad tracking (ptr_*) */
+    partnerKey?: string;
+    /** Whether to enable ad tracking (default: true if partnerKey set) */
+    enableAdTracking?: boolean;
+    /** Whether to enable auto-install for missing commands (default: true) */
+    enableAutoInstall?: boolean;
+    /** Whether to enable usage analytics tracking (default: true) */
+    enableUsageTracking?: boolean;
+    /** Size of the usage analytics ring buffer (default: 10000) */
+    usageBufferSize?: number;
+    /** Whether to enable auto-recommend based on usage patterns (default: true) */
+    enableAutoRecommend?: boolean;
+    /** Path to server groups file */
+    groupsPath?: string;
+    /**
+     * Optional path for the durable safety audit log (JSONL, append-only). When
+     * set, every sandbox-relevant event (tool calls, blocked tools, blocked/
+     * allowed egress, connects) is appended for forensics / SIEM ingestion.
+     * When unset, the audit trail is in-memory only (queryable via mcp_audit).
+     */
+    auditLogPath?: string;
+    /**
+     * Whether to enable L2 container isolation (Docker/Podman) for untrusted
+     * servers. Default: false (opt-in). When true, community/unknown-tier
+     * servers run inside a constrained container; verified/trusted stay on L1.
+     * Falls back to L1 automatically if no container engine is available.
+     */
+    enableContainerIsolation?: boolean;
+    /** HTTP daemon port. When set, the gateway runs as an HTTP daemon. */
+    httpPort?: number;
+    /** HTTP daemon bind host (default 127.0.0.1). */
+    httpHost?: string;
+    /** Bearer token required for HTTP daemon requests (single-tenant mode). */
+    httpToken?: string;
+    /**
+     * Per-tenant bearer tokens: tenantId → token. Enables a multi-tenant daemon
+     * where each tenant authenticates with its own token and gets an isolated
+     * session pool + sandbox-manifest store. Merged with `httpToken` (which maps
+     * to tenant "default").
+     */
+    httpTokens?: Record<string, string>;
+    /**
+     * Allowed Host header values (DNS-rebinding protection). If unset, a safe
+     * default of localhost variants on the bind port is used. Set explicitly
+     * (e.g. ["gateway.example.com"]) when binding to 0.0.0.0 behind a domain.
+     */
+    httpAllowedHosts?: string[];
+    /**
+     * Allowed Origin header values. Browser requests carrying any other Origin
+     * are rejected. Non-browser clients (no Origin header) are always allowed.
+     */
+    httpAllowedOrigins?: string[];
+}

package/dist/config/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":""}

package/dist/connection/auto-installer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ensure that the required command/package is available before spawning.
+ *
+ * For npx commands: ensures the `-y` flag is present so npx auto-installs.
+ * For other commands: checks if the binary exists on PATH.
+ *
+ * Does NOT actually install packages — we rely on npx -y for on-demand install.
+ * This function logs warnings when commands are not found.
+ */
+export declare function ensureInstalled(command: string, args: string[]): Promise<{
+    command: string;
+    args: string[];
+}>;

package/dist/connection/auto-installer.js

@@ -0,0 +1,61 @@
+import { execSync } from "node:child_process";
+import { log } from "../utils/logger.js";
+const INSTALL_TIMEOUT_MS = 60_000;
+/**
+ * Ensure that the required command/package is available before spawning.
+ *
+ * For npx commands: ensures the `-y` flag is present so npx auto-installs.
+ * For other commands: checks if the binary exists on PATH.
+ *
+ * Does NOT actually install packages — we rely on npx -y for on-demand install.
+ * This function logs warnings when commands are not found.
+ */
+export async function ensureInstalled(command, args) {
+    // For npx: ensure -y flag is present
+    if (command === "npx") {
+        if (!args.includes("-y") && !args.includes("--yes")) {
+            log.debug("Adding -y flag to npx command for auto-install", {
+                args,
+            });
+            return { command, args: ["-y", ...args] };
+        }
+        return { command, args };
+    }
+    // For other commands: check if binary exists
+    if (!isCommandAvailable(command)) {
+        log.warn("Command not found on PATH", { command });
+        // Check if it looks like an npm package name (e.g., @scope/package or package-name)
+        if (looksLikeNpmPackage(command)) {
+            log.info("Command looks like an npm package, trying npx", { command });
+            // Rewrite to npx -y <command> <args>
+            return { command: "npx", args: ["-y", command, ...args] };
+        }
+        // Can't auto-install non-npm commands
+        throw new Error(`Command "${command}" not found. Please install it manually and ensure it's on your PATH.`);
+    }
+    return { command, args };
+}
+/**
+ * Check if a command is available on PATH.
+ */
+function isCommandAvailable(command) {
+    try {
+        const whereCmd = process.platform === "win32" ? "where" : "which";
+        execSync(`${whereCmd} ${command}`, {
+            timeout: 5_000,
+            stdio: "pipe",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Heuristic: does the string look like an npm package name?
+ */
+function looksLikeNpmPackage(name) {
+    // @scope/package or simple-package-name
+    return /^@?[a-z0-9][\w.-]*\/?[\w.-]*$/i.test(name);
+}
+//# sourceMappingURL=auto-installer.js.map

package/dist/connection/auto-installer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-installer.js","sourceRoot":"","sources":["../../src/connection/auto-installer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAEzC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,IAAc;IAEd,qCAAqC;IACrC,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,KAAK,CAAC,gDAAgD,EAAE;gBAC1D,IAAI;aACL,CAAC,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAEnD,oFAAoF;QACpF,IAAI,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;YACjC,GAAG,CAAC,IAAI,CAAC,+CAA+C,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACvE,qCAAqC;YACrC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QAC5D,CAAC;QAED,sCAAsC;QACtC,MAAM,IAAI,KAAK,CACb,YAAY,OAAO,uEAAuE,CAC3F,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,OAAe;IACzC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QAClE,QAAQ,CAAC,GAAG,QAAQ,IAAI,OAAO,EAAE,EAAE;YACjC,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,MAAM;SACd,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAAC,IAAY;IACvC,wCAAwC;IACxC,OAAO,gCAAgC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC"}

package/dist/connection/connection-manager.d.ts

@@ -0,0 +1,106 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { GatewayConfig } from "../config/types.js";
+import type { RegistryClient } from "../registry/registry-client.js";
+import type { PermissionManager } from "../permissions/permission-manager.js";
+import type { ManifestResolver } from "../sandbox/manifest-resolver.js";
+import type { AuditLog } from "../audit/audit-log.js";
+import type { UsageTracker } from "../analytics/usage-tracker.js";
+import type { PluginManager } from "../plugins/plugin-manager.js";
+import type { DownstreamConnection, ConnectParams, ConnectionSummary, ConnectResult } from "./types.js";
+import type { AdTracker } from "../ads/ad-tracker.js";
+/**
+ * Manages the lifecycle of all downstream MCP server connections.
+ *
+ * Responsibilities:
+ * - Connect to downstream servers via stdio, SSE, WebSocket, or Streamable HTTP
+ * - Register/remove proxied tools, resources, and prompts on the gateway
+ * - Handle process crashes with auto-reconnect
+ * - Periodic health monitoring via pings
+ * - Notify the host client when tool/resource/prompt lists change
+ */
+export declare class ConnectionManager {
+    private readonly mcpServer;
+    private readonly registryClient;
+    private readonly permissionManager;
+    private readonly config;
+    private readonly adTracker?;
+    private connections;
+    /** Debounce timers for tool re-sync per slug to prevent notification spam */
+    private resyncTimers;
+    /** Active reconnect timers per slug */
+    private reconnectTimers;
+    /** Health check interval handle */
+    private healthCheckInterval;
+    /** Gateway start time for uptime calculation */
+    readonly startedAt: Date;
+    /** Optional usage tracker for analytics */
+    usageTracker?: UsageTracker;
+    /** Optional plugin manager for middleware hooks */
+    pluginManager?: PluginManager;
+    /** Optional sandbox manifest resolver (L1 capability enforcement) */
+    manifestResolver?: ManifestResolver;
+    /** Optional safety audit trail (forensics log of sandboxed-server actions) */
+    auditLog?: AuditLog;
+    constructor(mcpServer: McpServer, registryClient: RegistryClient, permissionManager: PermissionManager, config: GatewayConfig, adTracker?: (AdTracker | null) | undefined);
+    /**
+     * Connect to a downstream MCP server.
+     *
+     * Resolves the install command (from registry or explicit params),
+     * connects via the appropriate transport, performs MCP handshake,
+     * fetches tools/resources/prompts, and registers proxied capabilities.
+     */
+    /**
+     * Names of declared auth env vars the server needs that aren't available in
+     * the current environment or the explicitly-provided `env`. Used to warn the
+     * user before a server crashes on a missing API key.
+     */
+    private missingAuthEnv;
+    connect(params: ConnectParams): Promise<ConnectResult>;
+    /**
+     * Disconnect from a downstream server.
+     */
+    disconnect(slug: string, options?: {
+        removeProfile?: boolean;
+    }): Promise<void>;
+    /**
+     * Disconnect all downstream servers (for graceful shutdown).
+     */
+    disconnectAll(): Promise<void>;
+    getConnection(slug: string): DownstreamConnection | undefined;
+    listConnections(): ConnectionSummary[];
+    get connectionCount(): number;
+    /**
+     * Load saved connection profiles and auto-connect each one.
+     * Called once during gateway startup.
+     */
+    autoConnectFromProfiles(): Promise<void>;
+    /**
+     * Start periodic health checks on all ready connections.
+     */
+    startHealthChecks(): void;
+    /**
+     * Stop the health check interval.
+     */
+    stopHealthChecks(): void;
+    private runHealthChecks;
+    /**
+     * Handle a downstream process crash.
+     * Removes proxied tools/resources/prompts and attempts auto-reconnect.
+     */
+    private handleProcessCrash;
+    private scheduleReconnect;
+    private attemptReconnect;
+    private cancelReconnect;
+    /**
+     * Handle a downstream server's tool list changing.
+     * Debounced to 500ms to prevent notification spam from chatty servers.
+     */
+    private handleToolsChanged;
+    /**
+     * Re-sync all proxied capabilities (tools, resources, prompts) for a downstream connection.
+     */
+    private doCapabilityResync;
+    private toSummary;
+    /** Derive a slug from a URL */
+    private slugFromUrl;
+}