@winstonsayno/mcp-gateway 0.4.0 → 1.0.0

package/dist/mcp/endpoint.js

@@ -0,0 +1,714 @@
+/**
+ * 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 { randomUUID, createHash } from 'crypto';
+import { ERR_CANCELLED, ERR_NOT_CONNECTED, ERR_TIMEOUT } from '../proxy/index.js';
+import { setRateLimitHeaders } from '../auth/ratelimit.js';
+import { originAllowed } from '../middleware/cors.js';
+import { filterToolsByScope, isToolInScope } from '../auth/scopes.js';
+import { logger } from '../utils/logger.js';
+import { VERSION } from '../utils/version.js';
+import { buildToolIndex, toMcpTool } from './naming.js';
+import { buildPromptIndex, dedupeResources, routeResource, toMcpPrompt, toMcpResource, toMcpResourceTemplate, } from './catalog.js';
+import { isServerInScope } from '../auth/scopes.js';
+/** Protocol versions the endpoint speaks, newest first. */
+export const DOWNSTREAM_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26'];
+export const LATEST_PROTOCOL_VERSION = DOWNSTREAM_PROTOCOL_VERSIONS[0];
+// JSON-RPC error codes
+export const JSONRPC_PARSE_ERROR = -32700;
+export const JSONRPC_INVALID_REQUEST = -32600;
+export const JSONRPC_METHOD_NOT_FOUND = -32601;
+export const JSONRPC_INVALID_PARAMS = -32602;
+export const JSONRPC_INTERNAL_ERROR = -32603;
+/** Gateway rate limit hit on `tools/call` (`data.retryAfter` in seconds). */
+export const ERR_RATE_LIMITED = -32029;
+/** The caller's scopes do not allow this server / tool. */
+export const ERR_FORBIDDEN = -32003;
+export const DEFAULT_MCP_CONFIG = {
+    enabled: true,
+    path: '/mcp',
+    toolNaming: 'auto',
+    pageSize: 500,
+    sessionIdleTimeoutSeconds: 1800,
+    maxSessions: 1000,
+};
+const identityOf = (req) => ({
+    clientId: req.clientId,
+    scope: req.scope,
+});
+const SSE_KEEPALIVE_MS = 25_000;
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const idKey = (id) => `${typeof id}:${String(id)}`;
+function rpcError(id, error) {
+    return { jsonrpc: '2.0', id: id ?? null, error };
+}
+function encodeCursor(offset) {
+    return Buffer.from(JSON.stringify({ o: offset }), 'utf8').toString('base64url');
+}
+function decodeCursor(cursor) {
+    if (typeof cursor !== 'string')
+        return undefined;
+    try {
+        const v = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        return typeof v.o === 'number' && Number.isSafeInteger(v.o) && v.o >= 0 ? v.o : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function acceptsEventStream(req) {
+    const a = String(req.headers.accept ?? '');
+    return a.includes('text/event-stream') || a.includes('*/*');
+}
+export class McpEndpoint {
+    deps;
+    cfg;
+    sessions = new Map();
+    sweepTimer;
+    keepaliveTimer;
+    notifyTimer;
+    closed = false;
+    onRegistryChange = () => this.scheduleListChanged();
+    constructor(config, deps) {
+        this.deps = deps;
+        this.cfg = { ...DEFAULT_MCP_CONFIG, ...stripUndefined(config ?? {}) };
+        deps.registry.on('tools-updated', this.onRegistryChange);
+        deps.registry.on('unregistered', this.onRegistryChange);
+        deps.registry.on('catalog-updated', this.onRegistryChange);
+        this.sweepTimer = setInterval(() => this.sweep(), 60_000);
+        this.sweepTimer.unref();
+        this.keepaliveTimer = setInterval(() => this.keepalive(), SSE_KEEPALIVE_MS);
+        this.keepaliveTimer.unref();
+    }
+    get path() {
+        return this.cfg.path;
+    }
+    /** Apply hot-reloadable settings (everything except `enabled` and `path`). */
+    update(config) {
+        const next = { ...DEFAULT_MCP_CONFIG, ...stripUndefined(config ?? {}) };
+        if (next.enabled !== this.cfg.enabled || next.path !== this.cfg.path) {
+            logger.warn('Config "mcp.enabled" / "mcp.path" changed — restart required for it to take effect');
+        }
+        const namingChanged = next.toolNaming !== this.cfg.toolNaming;
+        this.cfg = { ...next, enabled: this.cfg.enabled, path: this.cfg.path };
+        if (namingChanged)
+            this.scheduleListChanged();
+    }
+    /** Express router serving POST / GET / DELETE on the configured path. */
+    router() {
+        const r = express.Router();
+        const json = express.json({ limit: '10mb', type: ['application/json', 'application/*+json'] });
+        const path = this.cfg.path;
+        const guard = (req, res, next) => this.checkOrigin(req, res, next);
+        r.post(path, guard, this.deps.authenticate, json, (req, res, next) => {
+            this.handlePost(req, res).catch(next);
+        });
+        r.get(path, guard, this.deps.authenticate, (req, res) => this.handleGet(req, res));
+        r.delete(path, guard, this.deps.authenticate, (req, res) => this.handleDelete(req, res));
+        r.all(path, (_req, res) => {
+            res.set('Allow', 'GET, POST, DELETE').status(405).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: 'Method not allowed' }));
+        });
+        // Malformed JSON bodies become JSON-RPC parse errors instead of REST error envelopes.
+        r.use(path, (err, _req, res, next) => {
+            if (res.headersSent)
+                return next(err);
+            const status = err?.status;
+            if (status === 413) {
+                res.status(413).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: 'Payload too large' }));
+                return;
+            }
+            if (status && status >= 400 && status < 500) {
+                res.status(400).json(rpcError(null, { code: JSONRPC_PARSE_ERROR, message: 'Parse error' }));
+                return;
+            }
+            logger.error(`MCP endpoint error: ${err instanceof Error ? err.message : String(err)}`);
+            res.status(500).json(rpcError(null, { code: JSONRPC_INTERNAL_ERROR, message: 'Internal error' }));
+        });
+        return r;
+    }
+    /** Close every stream and session (gateway shutdown). */
+    close() {
+        this.closed = true;
+        clearInterval(this.sweepTimer);
+        clearInterval(this.keepaliveTimer);
+        clearTimeout(this.notifyTimer);
+        this.deps.registry.off('tools-updated', this.onRegistryChange);
+        this.deps.registry.off('unregistered', this.onRegistryChange);
+        this.deps.registry.off('catalog-updated', this.onRegistryChange);
+        for (const s of [...this.sessions.values()])
+            this.endSession(s);
+    }
+    getSessions() {
+        return [...this.sessions.values()].map((s) => ({
+            id: s.id,
+            clientId: s.clientId,
+            protocolVersion: s.protocolVersion,
+            clientInfo: s.clientInfo,
+            createdAt: s.createdAt,
+            lastSeen: new Date(s.lastSeen),
+            streams: s.streams.length,
+            inflight: s.inflight.size,
+        }));
+    }
+    // ─── HTTP handlers ──────────────────────────────────────────────────────────
+    checkOrigin(req, res, next) {
+        // DNS-rebinding protection: browsers always send Origin on cross-origin
+        // requests; non-browser clients usually send none.
+        const origin = req.headers.origin;
+        if (origin) {
+            const allowed = this.cfg.allowedOrigins ?? this.deps.corsOrigins() ?? ['*'];
+            if (!originAllowed(allowed, origin)) {
+                res.status(403).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: 'Origin not allowed' }));
+                return;
+            }
+        }
+        next();
+    }
+    async handlePost(req, res) {
+        const body = req.body;
+        const batch = Array.isArray(body);
+        const messages = batch ? body : [body];
+        if (body === undefined || (batch && messages.length === 0)) {
+            res.status(400).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: 'Invalid Request: expected a JSON-RPC message' }));
+            return;
+        }
+        for (const m of messages) {
+            if (!isObject(m) || m.jsonrpc !== '2.0' || (m.method !== undefined && typeof m.method !== 'string')) {
+                res.status(400).json(rpcError(isObject(m) ? m.id : null, { code: JSONRPC_INVALID_REQUEST, message: 'Invalid Request' }));
+                return;
+            }
+        }
+        const msgs = messages;
+        // ── initialize: creates the session ──
+        const init = msgs.find((m) => m.method === 'initialize');
+        if (init) {
+            if (msgs.length > 1) {
+                res.status(400).json(rpcError(init.id, { code: JSONRPC_INVALID_REQUEST, message: 'initialize must not be batched' }));
+                return;
+            }
+            if (init.id === undefined || init.id === null) {
+                res.status(400).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: 'initialize must be a request' }));
+                return;
+            }
+            this.initialize(req, res, init);
+            return;
+        }
+        const session = this.resolveSession(req, res);
+        if (!session)
+            return;
+        const requests = [];
+        for (const m of msgs) {
+            if (m.method === undefined)
+                continue; // a response to a server request: we send none
+            if (m.id === undefined || m.id === null)
+                this.handleNotification(session, m);
+            else
+                requests.push(m);
+        }
+        if (requests.length === 0) {
+            res.status(202).end();
+            return;
+        }
+        // Abort in-flight upstream calls if the client goes away.
+        const controllers = [];
+        res.on('close', () => {
+            if (!res.writableFinished)
+                for (const c of controllers)
+                    c.abort();
+        });
+        const replies = await Promise.all(requests.map((m) => {
+            const ctrl = new AbortController();
+            controllers.push(ctrl);
+            const key = idKey(m.id);
+            session.inflight.set(key, ctrl);
+            return this.handleRequest(session, req, res, m, ctrl.signal, !batch)
+                .catch((err) => {
+                logger.error(`MCP ${m.method} failed: ${err instanceof Error ? err.message : String(err)}`);
+                return rpcError(m.id, { code: JSONRPC_INTERNAL_ERROR, message: 'Internal error' });
+            })
+                .finally(() => {
+                if (session.inflight.get(key) === ctrl)
+                    session.inflight.delete(key);
+            });
+        }));
+        if (res.headersSent || res.destroyed)
+            return;
+        res.status(200).json(batch ? replies : replies[0]);
+    }
+    initialize(req, res, msg) {
+        const params = isObject(msg.params) ? msg.params : {};
+        const requested = typeof params.protocolVersion === 'string' ? params.protocolVersion : undefined;
+        const protocolVersion = requested && DOWNSTREAM_PROTOCOL_VERSIONS.includes(requested) ? requested : LATEST_PROTOCOL_VERSION;
+        if (this.sessions.size >= this.cfg.maxSessions && !this.evictOne()) {
+            res.status(503).json(rpcError(msg.id, { code: JSONRPC_INTERNAL_ERROR, message: 'Too many sessions' }));
+            return;
+        }
+        const clientInfo = isObject(params.clientInfo)
+            ? {
+                name: typeof params.clientInfo.name === 'string' ? params.clientInfo.name : undefined,
+                version: typeof params.clientInfo.version === 'string' ? params.clientInfo.version : undefined,
+            }
+            : undefined;
+        const session = {
+            id: randomUUID(),
+            clientId: req.clientId,
+            protocolVersion,
+            clientInfo,
+            createdAt: new Date(),
+            lastSeen: Date.now(),
+            streams: [],
+            inflight: new Map(),
+            eventSeq: 0,
+            auth: identityOf(req),
+        };
+        session.toolsFingerprint = this.fingerprint(this.toolIndex(session.auth));
+        session.resourcesFingerprint = this.resourcesFingerprint(session.auth);
+        session.promptsFingerprint = this.promptsFingerprint(session.auth);
+        this.sessions.set(session.id, session);
+        logger.info(`MCP session ${session.id.slice(0, 8)} opened by ${clientInfo?.name ?? 'unknown client'}` +
+            ` (protocol ${protocolVersion}${session.clientId ? `, ${session.clientId}` : ''})`);
+        const result = {
+            protocolVersion,
+            capabilities: {
+                tools: { listChanged: true },
+                resources: { listChanged: true },
+                prompts: { listChanged: true },
+            },
+            serverInfo: { name: 'mcp-gateway', title: 'mcp-gateway', version: VERSION },
+        };
+        if (this.cfg.instructions)
+            result.instructions = this.cfg.instructions;
+        res.set('Mcp-Session-Id', session.id).status(200).json({ jsonrpc: '2.0', id: msg.id, result });
+    }
+    /** Validate session + protocol headers; on failure the response is already sent. */
+    resolveSession(req, res) {
+        const id = req.headers['mcp-session-id'];
+        if (typeof id !== 'string' || id.length === 0) {
+            res.status(400).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: 'Bad Request: Mcp-Session-Id header is required' }));
+            return undefined;
+        }
+        const session = this.sessions.get(id);
+        // A session presented by a different client is treated as unknown.
+        if (!session || session.clientId !== req.clientId) {
+            res.status(404).json(rpcError(null, { code: -32001, message: 'Session not found' }));
+            return undefined;
+        }
+        const version = req.headers['mcp-protocol-version'];
+        if (typeof version === 'string' && !DOWNSTREAM_PROTOCOL_VERSIONS.includes(version)) {
+            res.status(400).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: `Bad Request: unsupported MCP-Protocol-Version "${version}"` }));
+            return undefined;
+        }
+        session.lastSeen = Date.now();
+        session.auth = identityOf(req);
+        return session;
+    }
+    handleGet(req, res) {
+        if (!acceptsEventStream(req)) {
+            res.status(406).json(rpcError(null, { code: JSONRPC_INVALID_REQUEST, message: 'Not Acceptable: client must accept text/event-stream' }));
+            return;
+        }
+        const session = this.resolveSession(req, res);
+        if (!session)
+            return;
+        res.status(200).set({
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no',
+            'Mcp-Session-Id': session.id,
+        });
+        res.flushHeaders();
+        res.write(': connected\n\n');
+        session.streams.push(res);
+        req.socket.setTimeout(0);
+        res.on('close', () => {
+            session.streams = session.streams.filter((s) => s !== res);
+            session.lastSeen = Date.now();
+        });
+    }
+    handleDelete(req, res) {
+        const session = this.resolveSession(req, res);
+        if (!session)
+            return;
+        this.endSession(session);
+        logger.info(`MCP session ${session.id.slice(0, 8)} closed by client`);
+        res.status(204).end();
+    }
+    // ─── JSON-RPC ───────────────────────────────────────────────────────────────
+    handleNotification(session, msg) {
+        if (msg.method === 'notifications/cancelled') {
+            const params = isObject(msg.params) ? msg.params : {};
+            const rid = params.requestId;
+            if (typeof rid === 'string' || typeof rid === 'number') {
+                session.inflight.get(idKey(rid))?.abort();
+            }
+        }
+        // notifications/initialized and others need no action.
+    }
+    async handleRequest(session, req, res, msg, signal, single) {
+        const id = msg.id;
+        const ok = (result) => ({ jsonrpc: '2.0', id, result });
+        switch (msg.method) {
+            case 'ping':
+                return ok({});
+            case 'initialize':
+                return rpcError(id, { code: JSONRPC_INVALID_REQUEST, message: 'Session already initialized' });
+            case 'tools/list':
+                return this.listTools(session, msg);
+            case 'tools/call':
+                return this.callTool(session, req, res, msg, signal, single);
+            case 'resources/list': {
+                const list = this.resources(session.auth);
+                if (isFirstPage(msg))
+                    session.resourcesFingerprint = hashList(list);
+                return this.paginate(msg, list.map(toMcpResource), 'resources');
+            }
+            case 'resources/templates/list':
+                return this.paginate(msg, this.templates(session.auth).map(toMcpResourceTemplate), 'resourceTemplates');
+            case 'resources/read':
+                return this.readResource(session, req, res, msg, signal, single);
+            case 'prompts/list': {
+                const index = this.promptIndex(session.auth);
+                if (isFirstPage(msg))
+                    session.promptsFingerprint = this.promptsFingerprint(session.auth);
+                return this.paginate(msg, index.list.map(({ name, item }) => toMcpPrompt(name, item)), 'prompts');
+            }
+            case 'prompts/get':
+                return this.getPrompt(session, req, res, msg, signal, single);
+            default:
+                return rpcError(id, { code: JSONRPC_METHOD_NOT_FOUND, message: `Method not found: ${String(msg.method)}` });
+        }
+    }
+    /** Tools visible to a client (server filters + its scope), with exposed names. */
+    toolIndex(identity) {
+        const tools = filterToolsByScope(identity.scope, this.deps.registry.getAllTools());
+        return buildToolIndex(tools, this.cfg.toolNaming);
+    }
+    resources(identity) {
+        return dedupeResources(this.deps.registry.getAllResources().filter((r) => isServerInScope(identity.scope, r.serverId)));
+    }
+    templates(identity) {
+        return this.deps.registry
+            .getAllResourceTemplates()
+            .filter((t) => isServerInScope(identity.scope, t.serverId))
+            .sort((a, b) => (a.serverId < b.serverId ? -1 : a.serverId > b.serverId ? 1 : 0));
+    }
+    promptIndex(identity) {
+        const prompts = this.deps.registry.getAllPrompts().filter((p) => isServerInScope(identity.scope, p.serverId));
+        return buildPromptIndex(prompts, this.cfg.toolNaming);
+    }
+    resourcesFingerprint(identity) {
+        return hashList([...this.resources(identity), ...this.templates(identity)]);
+    }
+    promptsFingerprint(identity) {
+        return hashList(this.promptIndex(identity).list.map(({ name, item }) => toMcpPrompt(name, item)));
+    }
+    /** Cursor pagination over a list (same scheme as tools/list). */
+    paginate(msg, items, key) {
+        const params = isObject(msg.params) ? msg.params : {};
+        let offset = 0;
+        if (params.cursor !== undefined) {
+            const o = decodeCursor(params.cursor);
+            if (o === undefined)
+                return rpcError(msg.id, { code: JSONRPC_INVALID_PARAMS, message: 'Invalid cursor' });
+            offset = o;
+        }
+        const page = items.slice(offset, offset + this.cfg.pageSize);
+        const result = { [key]: page };
+        const next = offset + page.length;
+        if (next < items.length)
+            result.nextCursor = encodeCursor(next);
+        return { jsonrpc: '2.0', id: msg.id, result };
+    }
+    /** Forward resources/read or prompts/get with shared rate limit, metrics and error mapping. */
+    async forward(req, res, msg, serverId, method, params, kind, label, signal, single) {
+        const id = msg.id;
+        const limited = this.applyRateLimit(req, res, id, single);
+        if (limited)
+            return limited;
+        const server = this.deps.registry.getServer(serverId);
+        if (!server || !this.deps.proxy.isConnected(serverId)) {
+            return rpcError(id, { code: ERR_NOT_CONNECTED, message: `Server "${serverId}" is not connected` });
+        }
+        const result = await this.deps.proxy.request(serverId, method, params, server.timeout, { signal });
+        this.deps.metrics.record({
+            serverId,
+            toolName: label,
+            durationMs: result.durationMs,
+            success: result.success,
+            errorMessage: result.error?.message,
+            clientId: req.clientId,
+            via: 'mcp',
+            kind,
+        });
+        if (this.deps.requestLog()) {
+            logger.info(`${method} ${label} → ${serverId} ${result.success ? 'ok' : 'failed'} ${result.durationMs}ms (mcp)`);
+        }
+        if (result.success)
+            return { jsonrpc: '2.0', id, result: result.result ?? {} };
+        const err = result.error ?? { code: JSONRPC_INTERNAL_ERROR, message: 'Unknown error' };
+        return rpcError(id, err.code === ERR_CANCELLED ? { code: ERR_CANCELLED, message: 'Request cancelled' } : err);
+    }
+    readResource(session, req, res, msg, signal, single) {
+        const params = isObject(msg.params) ? msg.params : {};
+        const uri = params.uri;
+        if (typeof uri !== 'string' || uri.length === 0) {
+            return rpcError(msg.id, { code: JSONRPC_INVALID_PARAMS, message: '"uri" must be a non-empty string' });
+        }
+        const scope = session.auth.scope;
+        const serverId = routeResource(uri, this.resources(session.auth), this.templates(session.auth), this.deps.registry
+            .getEnabledServers()
+            .map((s) => s.id)
+            .filter((id) => isServerInScope(scope, id) && this.deps.proxy.hasCapability(id, 'resources')));
+        if (!serverId)
+            return rpcError(msg.id, { code: -32002, message: 'Resource not found', data: { uri } });
+        return this.forward(req, res, msg, serverId, 'resources/read', { uri }, 'resource', uri, signal, single);
+    }
+    getPrompt(session, req, res, msg, signal, single) {
+        const params = isObject(msg.params) ? msg.params : {};
+        const name = params.name;
+        const args = params.arguments ?? {};
+        if (typeof name !== 'string' || name.length === 0) {
+            return rpcError(msg.id, { code: JSONRPC_INVALID_PARAMS, message: '"name" must be a non-empty string' });
+        }
+        if (!isObject(args))
+            return rpcError(msg.id, { code: JSONRPC_INVALID_PARAMS, message: '"arguments" must be an object' });
+        const prompt = this.promptIndex(session.auth).byName.get(name);
+        if (!prompt)
+            return rpcError(msg.id, { code: JSONRPC_INVALID_PARAMS, message: `Unknown prompt: ${name}` });
+        return this.forward(req, res, msg, prompt.serverId, 'prompts/get', { name: prompt.name, arguments: args }, 'prompt', prompt.name, signal, single);
+    }
+    /** Count one call against the client's rate limit; returns an error reply when exceeded. */
+    applyRateLimit(req, res, id, single) {
+        const decision = this.deps.takeRateLimit(req);
+        if (!decision)
+            return undefined;
+        if (single && !res.headersSent)
+            setRateLimitHeaders(res, decision.limit, decision.remaining, decision.resetAt);
+        if (decision.allowed)
+            return undefined;
+        if (single && !res.headersSent)
+            res.set('Retry-After', String(decision.retryAfter));
+        return rpcError(id, {
+            code: ERR_RATE_LIMITED,
+            message: `Rate limit exceeded; retry after ${decision.retryAfter}s`,
+            data: { retryAfter: decision.retryAfter },
+        });
+    }
+    fingerprint(index) {
+        const h = createHash('sha256');
+        for (const t of index.list)
+            h.update(JSON.stringify(toMcpTool(t))).update('\n');
+        return h.digest('hex');
+    }
+    listTools(session, msg) {
+        const params = isObject(msg.params) ? msg.params : {};
+        let offset = 0;
+        if (params.cursor !== undefined) {
+            const o = decodeCursor(params.cursor);
+            if (o === undefined) {
+                return rpcError(msg.id, { code: JSONRPC_INVALID_PARAMS, message: 'Invalid cursor' });
+            }
+            offset = o;
+        }
+        const index = this.toolIndex(session.auth);
+        if (offset === 0)
+            session.toolsFingerprint = this.fingerprint(index);
+        const page = index.list.slice(offset, offset + this.cfg.pageSize);
+        const result = { tools: page.map(toMcpTool) };
+        const next = offset + page.length;
+        if (next < index.list.length)
+            result.nextCursor = encodeCursor(next);
+        return { jsonrpc: '2.0', id: msg.id, result };
+    }
+    async callTool(session, req, res, msg, signal, single) {
+        const id = msg.id;
+        const params = isObject(msg.params) ? msg.params : {};
+        const name = params.name;
+        const args = params.arguments ?? {};
+        if (typeof name !== 'string' || name.length === 0) {
+            return rpcError(id, { code: JSONRPC_INVALID_PARAMS, message: '"name" must be a non-empty string' });
+        }
+        if (!isObject(args)) {
+            return rpcError(id, { code: JSONRPC_INVALID_PARAMS, message: '"arguments" must be an object' });
+        }
+        const tool = this.toolIndex(session.auth).byName.get(name);
+        if (!tool) {
+            // A tool that exists but is outside the client's scope is refused with
+            // ERR_FORBIDDEN (the REST API's 403); it never appears in tools/list.
+            if (session.auth.scope) {
+                const unscoped = buildToolIndex(this.deps.registry.getAllTools(), this.cfg.toolNaming).byName.get(name);
+                const anyServer = this.deps.registry.findTools(name);
+                const target = unscoped ?? (anyServer.length > 0 ? anyServer[0] : undefined);
+                if (target && !isToolInScope(session.auth.scope, target.serverId, target.name)) {
+                    return rpcError(id, { code: ERR_FORBIDDEN, message: `Forbidden: tool "${name}" is not allowed for this client` });
+                }
+            }
+            return rpcError(id, { code: JSONRPC_INVALID_PARAMS, message: `Unknown tool: ${name}` });
+        }
+        const { serverId } = tool;
+        if (!this.deps.registry.isToolExposed(serverId, tool.name)) {
+            return rpcError(id, { code: JSONRPC_INVALID_PARAMS, message: `Unknown tool: ${name}` });
+        }
+        const limited = this.applyRateLimit(req, res, id, single);
+        if (limited)
+            return limited;
+        const server = this.deps.registry.getServer(serverId);
+        const toolError = (text) => ({
+            jsonrpc: '2.0',
+            id,
+            result: { content: [{ type: 'text', text }], isError: true },
+        });
+        if (!server || !this.deps.proxy.isConnected(serverId)) {
+            const status = this.deps.registry.getHealth(serverId)?.status;
+            return toolError(`Server "${serverId}" is not connected${status ? ` (${status})` : ''}; try again later.`);
+        }
+        const result = await this.deps.proxy.callTool(serverId, tool.name, args, server.timeout, { signal });
+        this.deps.metrics.record({
+            serverId,
+            toolName: tool.name,
+            durationMs: result.durationMs,
+            success: result.success,
+            errorMessage: result.error?.message,
+            clientId: req.clientId,
+            via: 'mcp',
+        });
+        if (this.deps.requestLog()) {
+            logger.info(`${tool.name} → ${serverId} ${result.success ? 'ok' : 'failed'} ${result.durationMs}ms (mcp)`);
+        }
+        if (result.success)
+            return { jsonrpc: '2.0', id, result: result.result ?? { content: [] } };
+        const err = result.error ?? { code: JSONRPC_INTERNAL_ERROR, message: 'Unknown error' };
+        switch (err.code) {
+            case ERR_CANCELLED:
+                return rpcError(id, { code: ERR_CANCELLED, message: 'Request cancelled' });
+            case ERR_TIMEOUT:
+                return toolError(`Tool "${name}" timed out after ${result.durationMs}ms`);
+            case ERR_NOT_CONNECTED:
+                return toolError(`Server "${serverId}" is not connected: ${err.message}`);
+            default:
+                // Upstream JSON-RPC error: forward unchanged.
+                return rpcError(id, err);
+        }
+    }
+    // ─── Notifications / housekeeping ───────────────────────────────────────────
+    scheduleListChanged() {
+        if (this.closed)
+            return;
+        clearTimeout(this.notifyTimer);
+        this.notifyTimer = setTimeout(() => this.sendListChanged(), 50);
+        this.notifyTimer.unref();
+    }
+    /** Re-evaluate every session's scope (after an auth hot reload) and notify changes. */
+    refreshClients() {
+        this.scheduleListChanged();
+    }
+    sendListChanged() {
+        for (const s of [...this.sessions.values()]) {
+            const current = this.deps.resolveClient?.(s.auth.clientId);
+            if (current && !current.known) {
+                // The key that opened this session is gone.
+                logger.info(`MCP session ${s.id.slice(0, 8)} ended: its credentials were removed`);
+                this.endSession(s);
+                continue;
+            }
+            if (current)
+                s.auth = { ...s.auth, scope: current.scope };
+            if (s.streams.length === 0)
+                continue;
+            const fp = this.fingerprint(this.toolIndex(s.auth));
+            if (fp !== s.toolsFingerprint) {
+                s.toolsFingerprint = fp;
+                this.send(s, { jsonrpc: '2.0', method: 'notifications/tools/list_changed' });
+            }
+            const rfp = this.resourcesFingerprint(s.auth);
+            if (rfp !== s.resourcesFingerprint) {
+                s.resourcesFingerprint = rfp;
+                this.send(s, { jsonrpc: '2.0', method: 'notifications/resources/list_changed' });
+            }
+            const pfp = this.promptsFingerprint(s.auth);
+            if (pfp !== s.promptsFingerprint) {
+                s.promptsFingerprint = pfp;
+                this.send(s, { jsonrpc: '2.0', method: 'notifications/prompts/list_changed' });
+            }
+        }
+    }
+    /** Send a message on the session's most recent stream. */
+    send(session, msg) {
+        const stream = session.streams[session.streams.length - 1];
+        if (!stream)
+            return false;
+        session.eventSeq++;
+        stream.write(`id: ${session.eventSeq}\nevent: message\ndata: ${JSON.stringify(msg)}\n\n`);
+        return true;
+    }
+    keepalive() {
+        for (const s of this.sessions.values())
+            for (const st of s.streams)
+                st.write(': keepalive\n\n');
+    }
+    sweep(now = Date.now()) {
+        const ttl = this.cfg.sessionIdleTimeoutSeconds * 1000;
+        for (const s of [...this.sessions.values()]) {
+            if (s.streams.length === 0 && s.inflight.size === 0 && now - s.lastSeen > ttl) {
+                logger.debug(`MCP session ${s.id.slice(0, 8)} expired`);
+                this.endSession(s);
+            }
+        }
+    }
+    /** Evict the least recently used idle session; false if none is idle. */
+    evictOne() {
+        let victim;
+        for (const s of this.sessions.values()) {
+            if (s.streams.length > 0 || s.inflight.size > 0)
+                continue;
+            if (!victim || s.lastSeen < victim.lastSeen)
+                victim = s;
+        }
+        if (!victim)
+            return false;
+        this.endSession(victim);
+        return true;
+    }
+    endSession(session) {
+        this.sessions.delete(session.id);
+        for (const c of session.inflight.values())
+            c.abort();
+        session.inflight.clear();
+        for (const st of session.streams)
+            st.end();
+        session.streams = [];
+    }
+    /** Test hook: expire idle sessions now. */
+    sweepNow(now) {
+        this.sweep(now);
+    }
+}
+function isFirstPage(msg) {
+    return !isObject(msg.params) || msg.params.cursor === undefined;
+}
+function hashList(items) {
+    const h = createHash('sha256');
+    for (const i of items)
+        h.update(JSON.stringify(i)).update('\n');
+    return h.digest('hex');
+}
+function stripUndefined(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}
+//# sourceMappingURL=endpoint.js.map