@winstonsayno/mcp-gateway 0.3.0 → 1.0.0

package/dist/mcp/endpoint.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Downstream MCP endpoint — MCP Streamable HTTP server (spec 2025-06-18,
+ * 2025-03-26 accepted) that aggregates every upstream server behind one URL.
+ *
+ *  - `POST <path>`: JSON-RPC requests / notifications / responses (batches
+ *    accepted for 2025-03-26 clients). Answers with `application/json`.
+ *  - `GET <path>`: server→client SSE stream for notifications
+ *    (`notifications/tools/list_changed`).
+ *  - `DELETE <path>`: ends the session.
+ *
+ * Sessions (`Mcp-Session-Id`) are bound to the authenticated client: a
+ * session id presented with another key is treated as unknown. Auth, rate
+ * limiting (per `tools/call`), `maxConcurrency`, timeouts, metrics and the
+ * request log are shared with the REST API.
+ *
+ * @module mcp/endpoint
+ */
+import express from 'express';
+import type { Request, RequestHandler } from 'express';
+import type { McpEndpointConfig } from '../utils/types.js';
+import type { ServerRegistry } from '../registry/index.js';
+import { type McpProxy } from '../proxy/index.js';
+import type { MetricsCollector } from '../monitor/index.js';
+import type { RateLimitDecision } from '../auth/ratelimit.js';
+import { type AccessScope } from '../auth/scopes.js';
+/** Protocol versions the endpoint speaks, newest first. */
+export declare const DOWNSTREAM_PROTOCOL_VERSIONS: string[];
+export declare const LATEST_PROTOCOL_VERSION: string;
+export declare const JSONRPC_PARSE_ERROR = -32700;
+export declare const JSONRPC_INVALID_REQUEST = -32600;
+export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
+export declare const JSONRPC_INVALID_PARAMS = -32602;
+export declare const JSONRPC_INTERNAL_ERROR = -32603;
+/** Gateway rate limit hit on `tools/call` (`data.retryAfter` in seconds). */
+export declare const ERR_RATE_LIMITED = -32029;
+/** The caller's scopes do not allow this server / tool. */
+export declare const ERR_FORBIDDEN = -32003;
+export declare const DEFAULT_MCP_CONFIG: Required<Omit<McpEndpointConfig, 'allowedOrigins' | 'instructions'>>;
+export interface McpSessionSummary {
+    id: string;
+    clientId?: string;
+    protocolVersion: string;
+    clientInfo?: {
+        name?: string;
+        version?: string;
+    };
+    createdAt: Date;
+    lastSeen: Date;
+    streams: number;
+    inflight: number;
+}
+export interface McpEndpointDeps {
+    registry: ServerRegistry;
+    proxy: McpProxy;
+    metrics: MetricsCollector;
+    /** Auth middleware (sets `clientId`). */
+    authenticate: RequestHandler;
+    /** Count one rate-limited call for the request. */
+    takeRateLimit: (req: Request) => RateLimitDecision | undefined;
+    /** Gateway CORS origins (used when `mcp.allowedOrigins` is unset). */
+    corsOrigins: () => readonly string[] | undefined;
+    /** Whether request logging is on. */
+    requestLog: () => boolean;
+    /**
+     * Current scope of a client id, used to re-evaluate open sessions after an
+     * auth hot reload (`known: false` ends the session). Optional.
+     */
+    resolveClient?: (clientId: string | undefined) => {
+        known: boolean;
+        scope?: AccessScope;
+    } | undefined;
+}
+export declare class McpEndpoint {
+    private readonly deps;
+    private cfg;
+    private readonly sessions;
+    private sweepTimer?;
+    private keepaliveTimer?;
+    private notifyTimer?;
+    private closed;
+    private readonly onRegistryChange;
+    constructor(config: McpEndpointConfig | undefined, deps: McpEndpointDeps);
+    get path(): string;
+    /** Apply hot-reloadable settings (everything except `enabled` and `path`). */
+    update(config: McpEndpointConfig | undefined): void;
+    /** Express router serving POST / GET / DELETE on the configured path. */
+    router(): express.Router;
+    /** Close every stream and session (gateway shutdown). */
+    close(): void;
+    getSessions(): McpSessionSummary[];
+    private checkOrigin;
+    private handlePost;
+    private initialize;
+    /** Validate session + protocol headers; on failure the response is already sent. */
+    private resolveSession;
+    private handleGet;
+    private handleDelete;
+    private handleNotification;
+    private handleRequest;
+    /** Tools visible to a client (server filters + its scope), with exposed names. */
+    private toolIndex;
+    private resources;
+    private templates;
+    private promptIndex;
+    private resourcesFingerprint;
+    private promptsFingerprint;
+    /** Cursor pagination over a list (same scheme as tools/list). */
+    private paginate;
+    /** Forward resources/read or prompts/get with shared rate limit, metrics and error mapping. */
+    private forward;
+    private readResource;
+    private getPrompt;
+    /** Count one call against the client's rate limit; returns an error reply when exceeded. */
+    private applyRateLimit;
+    private fingerprint;
+    private listTools;
+    private callTool;
+    private scheduleListChanged;
+    /** Re-evaluate every session's scope (after an auth hot reload) and notify changes. */
+    refreshClients(): void;
+    private sendListChanged;
+    /** Send a message on the session's most recent stream. */
+    private send;
+    private keepalive;
+    private sweep;
+    /** Evict the least recently used idle session; false if none is idle. */
+    private evictOne;
+    private endSession;
+    /** Test hook: expire idle sessions now. */
+    sweepNow(now?: number): void;
+}
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/mcp/endpoint.d.ts.map

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