@kieksme/mcp-http-kit 0.0.0-stage → 0.2.0

package/dist/http/node.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { loadConfig, isLocalhostHostname, resolveHealthPaths, type LoadConfigOptions, } from './config.js';
+export { authenticateRequest, unauthorizedWwwAuthenticate, verifyBearerToken, extractBearerToken, verifyOAuthAccessToken, buildProtectedResourceMetadata, oauthWwwAuthenticate, resourceMetadataUrl, clearOAuthJwksCache, type AuthenticateResult, type AuthenticateOptions, } from './auth/index.js';
+export { toAuthInfo, fromAuthInfo } from './auth/context.js';
+export { createMcpHttpApp, protectedResourceMetadataPath, checkHostAndOrigin, normalizeHostname, createNodeHttpServer, createNodeRequestListener, handleWithKitApp, type McpHttpApp, type McpHttpAppOptions, type HostGuardConfig, type HostGuardResult, type NodeHttpServerOptions, } from './http/index.js';
+export { startMcpServer } from './start.js';
+export { resolveUpstreamCredential, parseUpstreamCredentialMode, assertHeaderModeAllowed, type UpstreamCredentialResult, } from './upstream.js';
+export type { TransportMode, AuthMode, UpstreamCredentialMode, BearerAuthConfig, OAuthAuthConfig, NoneAuthConfig, AuthConfig, HttpListenConfig, HealthInfo, HealthInfoProvider, KitConfig, AuthContext, RequestContext, ServerFactory, UpstreamCredentialOptions, StartMcpServerOptions, StartedServer, } from './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,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,8BAA8B,EAC9B,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,6BAA6B,EAC7B,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,aAAa,EACb,QAAQ,EACR,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,cAAc,EACd,aAAa,EACb,yBAAyB,EACzB,qBAAqB,EACrB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { loadConfig, isLocalhostHostname, resolveHealthPaths, } from './config.js';
+export { authenticateRequest, unauthorizedWwwAuthenticate, verifyBearerToken, extractBearerToken, verifyOAuthAccessToken, buildProtectedResourceMetadata, oauthWwwAuthenticate, resourceMetadataUrl, clearOAuthJwksCache, } from './auth/index.js';
+export { toAuthInfo, fromAuthInfo } from './auth/context.js';
+export { createMcpHttpApp, protectedResourceMetadataPath, checkHostAndOrigin, normalizeHostname, createNodeHttpServer, createNodeRequestListener, handleWithKitApp, } from './http/index.js';
+export { startMcpServer } from './start.js';
+export { resolveUpstreamCredential, parseUpstreamCredentialMode, assertHeaderModeAllowed, } from './upstream.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,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,kBAAkB,GAEnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,8BAA8B,EAC9B,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GAGpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,6BAA6B,EAC7B,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,gBAAgB,GAMjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,uBAAuB,GAExB,MAAM,eAAe,CAAC"}

package/dist/start.d.ts

@@ -0,0 +1,16 @@
+import type { StartedServer, StartMcpServerOptions } from './types.js';
+/**
+ * Start an MCP server over stdio or stateless Streamable HTTP based on config.
+ *
+ * ```ts
+ * await startMcpServer({
+ *   createServer: (ctx) => {
+ *     const server = new McpServer({ name: 'demo', version: '1.0.0' });
+ *     // register tools; ctx.auth.scopes available for oauth
+ *     return server;
+ *   },
+ * });
+ * ```
+ */
+export declare function startMcpServer(options: StartMcpServerOptions): Promise<StartedServer>;
+//# sourceMappingURL=start.d.ts.map

package/dist/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOlF;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CAqE3F"}

package/dist/start.js

@@ -0,0 +1,84 @@
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { loadConfig } from './config.js';
+import { createMcpHttpApp } from './http/app.js';
+import { createNodeHttpServer } from './http/node.js';
+function publicUrl(config) {
+    const host = config.http.host === '0.0.0.0' ? '127.0.0.1' : config.http.host;
+    return `http://${host}:${config.http.port}${config.http.path}`;
+}
+/**
+ * Start an MCP server over stdio or stateless Streamable HTTP based on config.
+ *
+ * ```ts
+ * await startMcpServer({
+ *   createServer: (ctx) => {
+ *     const server = new McpServer({ name: 'demo', version: '1.0.0' });
+ *     // register tools; ctx.auth.scopes available for oauth
+ *     return server;
+ *   },
+ * });
+ * ```
+ */
+export async function startMcpServer(options) {
+    const config = options.config ?? loadConfig(options.env ?? process.env);
+    for (const warning of config.warnings) {
+        console.warn(`[mcp-http-kit] ${warning}`);
+    }
+    if (config.transport === 'stdio') {
+        const handle = serveStdio(() => options.createServer({
+            auth: { mode: 'none', scopes: [] },
+            headers: new Headers(),
+            url: new URL('stdio://local'),
+            era: 'modern',
+        }));
+        const close = async () => {
+            await handle.close();
+        };
+        if (options.signal) {
+            if (options.signal.aborted)
+                await close();
+            else
+                options.signal.addEventListener('abort', () => void close(), { once: true });
+        }
+        return { close, config };
+    }
+    const app = createMcpHttpApp({
+        createServer: options.createServer,
+        config,
+        ...(options.getHealthInfo ? { getHealthInfo: options.getHealthInfo } : {}),
+    });
+    const server = createNodeHttpServer({ app, config });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(config.http.port, config.http.host, () => resolve());
+    });
+    const url = publicUrl(config);
+    options.onListening?.({ host: config.http.host, port: config.http.port, url });
+    let closing;
+    const close = async () => {
+        if (closing)
+            return closing;
+        closing = (async () => {
+            await new Promise((resolve, reject) => {
+                server.close(error => (error ? reject(error) : resolve()));
+            });
+            await app.close();
+        })();
+        return closing;
+    };
+    const onSignal = () => {
+        void close().finally(() => {
+            // allow process to exit after graceful shutdown
+        });
+    };
+    process.once('SIGTERM', onSignal);
+    process.once('SIGINT', onSignal);
+    if (options.signal) {
+        if (options.signal.aborted)
+            await close();
+        else
+            options.signal.addEventListener('abort', () => void close(), { once: true });
+    }
+    return { close, url, config };
+}
+//# sourceMappingURL=start.js.map

package/dist/start.js.map

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

package/dist/test/helpers.d.ts

@@ -0,0 +1,35 @@
+import type { McpHttpApp } from '../http/app.js';
+import type { KitConfig } from '../types.js';
+export type KitHttpTestClient = {
+    baseUrl: string;
+    health: () => Promise<Response>;
+    mcp: (init?: RequestInit & {
+        token?: string;
+        host?: string;
+        origin?: string;
+    }) => Promise<Response>;
+    fetch: (path: string, init?: RequestInit) => Promise<Response>;
+};
+/** Parse a Streamable HTTP MCP response (JSON body or SSE `data:` frames). */
+export declare function readMcpJsonResponse(response: Response): Promise<unknown>;
+/** In-process client against a kit `McpHttpApp.fetch` (no real listen required). */
+export declare function createAppTestClient(app: McpHttpApp, config: KitConfig): KitHttpTestClient;
+export type KitContractAssertions = {
+    /** GET /health without auth → 200 */
+    healthUnauthenticated: () => Promise<void>;
+    /** POST /mcp without token → 401 (+ WWW-Authenticate) */
+    unauthorizedWithoutToken: () => Promise<void>;
+    /** Bad Host → 403 (health stays 200 even with bad Host) */
+    forbiddenOnBadHost: () => Promise<void>;
+    /** Bad Origin → 403 on MCP path */
+    forbiddenOnBadOrigin: () => Promise<void>;
+    /** initialize + tools/list round-trip with a valid token */
+    initializeAndListTools: (token: string) => Promise<{
+        tools: unknown[];
+    }>;
+};
+/**
+ * Reusable HTTP contract checks servers can call from their own vitest suites.
+ */
+export declare function createKitContractAssertions(client: KitHttpTestClient, config: KitConfig): KitContractAssertions;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/test/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/test/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpG,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChE,CAAC;AAEF,8EAA8E;AAC9E,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAsB9E;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,GAAG,iBAAiB,CA6BzF;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,qCAAqC;IACrC,qBAAqB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,yDAAyD;IACzD,wBAAwB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,2DAA2D;IAC3D,kBAAkB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,mCAAmC;IACnC,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,4DAA4D;IAC5D,sBAAsB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CAC1E,CAAC;AAEF;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,SAAS,GAChB,qBAAqB,CAoHvB"}

package/dist/test/helpers.js

@@ -0,0 +1,171 @@
+/** Parse a Streamable HTTP MCP response (JSON body or SSE `data:` frames). */
+export async function readMcpJsonResponse(response) {
+    const contentType = response.headers.get('content-type') ?? '';
+    const text = await response.text();
+    if (contentType.includes('application/json') || text.trimStart().startsWith('{')) {
+        return JSON.parse(text);
+    }
+    // SSE: take the last JSON payload from data: lines
+    const payloads = [];
+    for (const line of text.split(/\r?\n/)) {
+        if (!line.startsWith('data:'))
+            continue;
+        const data = line.slice(5).trim();
+        if (!data || data === '[DONE]')
+            continue;
+        try {
+            payloads.push(JSON.parse(data));
+        }
+        catch {
+            // ignore non-JSON data frames
+        }
+    }
+    if (payloads.length === 0) {
+        throw new Error(`No JSON payload in MCP response (${contentType}): ${text.slice(0, 200)}`);
+    }
+    return payloads[payloads.length - 1];
+}
+/** In-process client against a kit `McpHttpApp.fetch` (no real listen required). */
+export function createAppTestClient(app, config) {
+    const originHost = config.http.allowedHosts[0] ?? '127.0.0.1';
+    const baseUrl = `http://${originHost}:${config.http.port}`;
+    const fetch = (path, init) => {
+        const headers = new Headers(init?.headers);
+        if (!headers.has('host'))
+            headers.set('host', originHost);
+        return app.fetch(new Request(`${baseUrl}${path}`, { ...init, headers }));
+    };
+    return {
+        baseUrl,
+        health: () => fetch(config.http.healthPath, { method: 'GET' }),
+        mcp: (init = {}) => {
+            const headers = new Headers(init.headers);
+            if (init.token)
+                headers.set('authorization', `Bearer ${init.token}`);
+            if (init.host)
+                headers.set('host', init.host);
+            if (init.origin)
+                headers.set('origin', init.origin);
+            if (!headers.has('accept')) {
+                headers.set('accept', 'application/json, text/event-stream');
+            }
+            if (!headers.has('content-type') && init.body) {
+                headers.set('content-type', 'application/json');
+            }
+            const { token: _t, host: _h, origin: _o, ...rest } = init;
+            return fetch(config.http.path, { method: 'POST', ...rest, headers });
+        },
+        fetch,
+    };
+}
+/**
+ * Reusable HTTP contract checks servers can call from their own vitest suites.
+ */
+export function createKitContractAssertions(client, config) {
+    return {
+        async healthUnauthenticated() {
+            for (const path of config.http.healthPaths) {
+                const response = await client.fetch(path, { method: 'GET' });
+                if (response.status !== 200) {
+                    throw new Error(`Expected ${path} 200, got ${response.status}`);
+                }
+                const body = (await response.json());
+                if (body.status !== 'ok') {
+                    throw new Error(`Expected health status ok on ${path}, got ${JSON.stringify(body)}`);
+                }
+                // Health must ignore Host allowlist (Railway probes).
+                const evil = await client.fetch(path, {
+                    method: 'GET',
+                    headers: { host: 'evil.example' },
+                });
+                if (evil.status !== 200) {
+                    throw new Error(`Expected ${path} 200 with bad Host, got ${evil.status}`);
+                }
+            }
+        },
+        async unauthorizedWithoutToken() {
+            if (config.auth.mode === 'none')
+                return;
+            const response = await client.mcp({
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: 'initialize',
+                    params: {
+                        protocolVersion: '2025-06-18',
+                        capabilities: {},
+                        clientInfo: { name: 'kit-test', version: '0' },
+                    },
+                }),
+            });
+            if (response.status !== 401) {
+                throw new Error(`Expected 401 without token, got ${response.status}`);
+            }
+            if (!response.headers.get('www-authenticate')) {
+                throw new Error('Expected WWW-Authenticate header on 401');
+            }
+        },
+        async forbiddenOnBadHost() {
+            const token = config.auth.mode === 'bearer' ? config.auth.tokens[0] : 'dummy';
+            const response = await client.mcp({
+                host: 'evil.example',
+                ...(token ? { token } : {}),
+                body: '{}',
+            });
+            if (response.status !== 403) {
+                throw new Error(`Expected 403 for bad Host, got ${response.status}`);
+            }
+        },
+        async forbiddenOnBadOrigin() {
+            const token = config.auth.mode === 'bearer' ? config.auth.tokens[0] : 'dummy';
+            const response = await client.mcp({
+                ...(token ? { token } : {}),
+                origin: 'https://evil.example',
+                body: '{}',
+            });
+            if (response.status !== 403) {
+                throw new Error(`Expected 403 for bad Origin, got ${response.status}`);
+            }
+        },
+        async initializeAndListTools(token) {
+            const initBody = {
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-06-18',
+                    capabilities: {},
+                    clientInfo: { name: 'kit-test', version: '0' },
+                },
+            };
+            const initResponse = await client.mcp({
+                token,
+                body: JSON.stringify(initBody),
+            });
+            if (!initResponse.ok) {
+                throw new Error(`initialize failed: ${initResponse.status} ${await initResponse.text()}`);
+            }
+            await readMcpJsonResponse(initResponse);
+            const listBody = {
+                jsonrpc: '2.0',
+                id: 2,
+                method: 'tools/list',
+                params: {},
+            };
+            const listResponse = await client.mcp({
+                token,
+                headers: {
+                    'mcp-protocol-version': '2025-06-18',
+                },
+                body: JSON.stringify(listBody),
+            });
+            if (!listResponse.ok) {
+                throw new Error(`tools/list failed: ${listResponse.status} ${await listResponse.text()}`);
+            }
+            const payload = (await readMcpJsonResponse(listResponse));
+            const tools = payload.result?.tools ?? payload.tools ?? [];
+            return { tools };
+        },
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/test/helpers.js.map

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

package/dist/test/index.d.ts

@@ -0,0 +1,2 @@
+export { createAppTestClient, createKitContractAssertions, readMcpJsonResponse, type KitContractAssertions, type KitHttpTestClient, } from './helpers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/test/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC"}

package/dist/test/index.js

@@ -0,0 +1,2 @@
+export { createAppTestClient, createKitContractAssertions, readMcpJsonResponse, } from './helpers.js';
+//# sourceMappingURL=index.js.map

package/dist/test/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,mBAAmB,GAGpB,MAAM,cAAc,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,123 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { AuthInfo, McpServer, Server } from '@modelcontextprotocol/server';
+/** Transport selected by `MCP_TRANSPORT`. */
+export type TransportMode = 'stdio' | 'http';
+/** Authentication strategy for Streamable HTTP. */
+export type AuthMode = 'bearer' | 'oauth' | 'none';
+/** How upstream service credentials are resolved per request. */
+export type UpstreamCredentialMode = 'env' | 'header';
+export type BearerAuthConfig = {
+    mode: 'bearer';
+    /** Accepted bearer tokens (rotation-friendly). */
+    tokens: string[];
+};
+export type OAuthAuthConfig = {
+    mode: 'oauth';
+    /** Canonical resource identifier (usually the public MCP URL). */
+    resource: string;
+    /** Authorization server issuer URLs (RFC 9728 `authorization_servers`). */
+    authorizationServers: string[];
+    /** Expected JWT audience values (resource indicator and/or explicit aud). */
+    audiences: string[];
+    /** Optional JWKS URL override; otherwise derived from AS metadata / well-known. */
+    jwksUrl?: string;
+    /** Required scopes (all must be present). Empty = any scope / no scope check. */
+    requiredScopes: string[];
+    /** Scopes advertised in protected-resource metadata. */
+    scopesSupported: string[];
+};
+export type NoneAuthConfig = {
+    mode: 'none';
+    /** Must be true when binding beyond localhost. */
+    allowPublic: boolean;
+};
+export type AuthConfig = BearerAuthConfig | OAuthAuthConfig | NoneAuthConfig;
+export type HttpListenConfig = {
+    host: string;
+    port: number;
+    /** MCP endpoint path (default `/mcp`). */
+    path: string;
+    /** Primary unauthenticated health path (default `/health`). */
+    healthPath: string;
+    /**
+     * Extra health paths served like `healthPath` (e.g. `/healthz`).
+     * Always includes `healthPath`; duplicates are removed.
+     */
+    healthPaths: string[];
+    allowedHosts: string[];
+    allowedOrigins: string[];
+    /** Max request body size in bytes. */
+    maxBodyBytes: number;
+    /** When true, GET/DELETE on the MCP path are forwarded (default: 405). */
+    enableSessionMethods: boolean;
+};
+/** Extra fields merged into the JSON health response (alongside `status: "ok"`). */
+export type HealthInfo = Record<string, unknown>;
+/** Optional hook to enrich `/health` (and aliases) with version, tool counts, etc. */
+export type HealthInfoProvider = () => HealthInfo | Promise<HealthInfo>;
+export type KitConfig = {
+    transport: TransportMode;
+    http: HttpListenConfig;
+    auth: AuthConfig;
+    /** Realm used in WWW-Authenticate for bearer. */
+    realm: string;
+    /** Warnings emitted while loading (e.g. deprecated env aliases). */
+    warnings: string[];
+};
+/** Auth context attached to an accepted HTTP request. */
+export type AuthContext = {
+    mode: AuthMode;
+    /** Bearer token or access token string when present. */
+    token?: string;
+    /** JWT `sub` (oauth) when available. */
+    subject?: string;
+    /** Granted scopes (oauth) or empty for bearer/none. */
+    scopes: string[];
+    /** Raw JWT claims (oauth only). */
+    claims?: Record<string, unknown>;
+};
+export type RequestContext = {
+    auth: AuthContext;
+    headers: Headers;
+    /** Absolute request URL. */
+    url: URL;
+    /** Protocol era from the SDK factory (`modern` | `legacy`). */
+    era: 'legacy' | 'modern';
+    /** SDK pass-through auth info (scopes available to `requireScopes` / tool handlers). */
+    authInfo?: AuthInfo;
+};
+export type ServerFactory = (context: RequestContext) => McpServer | Server | Promise<McpServer | Server>;
+export type UpstreamCredentialOptions = {
+    mode: UpstreamCredentialMode;
+    /** Env var used when `mode === 'env'`. */
+    envVar: string;
+    /** Header name used when `mode === 'header'` (e.g. `X-Contabo-Api-Key`). */
+    headerName: string;
+    /** Current kit auth mode — header mode is refused when auth is `none`. */
+    authMode: AuthMode;
+    env?: NodeJS.ProcessEnv;
+};
+export type NodeHttpRequest = IncomingMessage;
+export type NodeHttpResponse = ServerResponse;
+export type StartMcpServerOptions = {
+    createServer: ServerFactory;
+    /** Pre-loaded config; defaults to `loadConfig()`. */
+    config?: KitConfig;
+    env?: NodeJS.ProcessEnv;
+    /** Optional hook fired after the HTTP server starts listening. */
+    onListening?: (info: {
+        host: string;
+        port: number;
+        url: string;
+    }) => void;
+    /** Optional extra fields for the health JSON body (merged under `status: "ok"`). */
+    getHealthInfo?: HealthInfoProvider;
+    signal?: AbortSignal;
+};
+export type StartedServer = {
+    close: () => Promise<void>;
+    /** Present in HTTP mode. */
+    url?: string;
+    config: KitConfig;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

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

package/dist/types.js.map

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

package/dist/upstream.d.ts

@@ -0,0 +1,17 @@
+import type { AuthMode, UpstreamCredentialMode, UpstreamCredentialOptions } from './types.js';
+export type UpstreamCredentialResult = {
+    mode: UpstreamCredentialMode;
+    value: string;
+    source: 'env' | 'header';
+};
+/**
+ * Resolve per-request upstream credentials (e.g. `X-Contabo-Api-Key`).
+ *
+ * Header mode is refused when kit auth is `none` — otherwise anyone could
+ * smuggle upstream keys through an open endpoint.
+ */
+export declare function resolveUpstreamCredential(headers: Headers | Record<string, string | string[] | undefined>, options: UpstreamCredentialOptions): UpstreamCredentialResult;
+export declare function parseUpstreamCredentialMode(raw: string | undefined, fallback?: UpstreamCredentialMode): UpstreamCredentialMode;
+/** Guard used by servers that expose a documented `X-<Service>-*` header. */
+export declare function assertHeaderModeAllowed(authMode: AuthMode): void;
+//# sourceMappingURL=upstream.d.ts.map

package/dist/upstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.d.ts","sourceRoot":"","sources":["../src/upstream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE9F,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EAChE,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CAsB1B;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,GAAE,sBAA8B,GACvC,sBAAsB,CAKxB;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAIhE"}

package/dist/upstream.js

@@ -0,0 +1,49 @@
+/**
+ * Resolve per-request upstream credentials (e.g. `X-Contabo-Api-Key`).
+ *
+ * Header mode is refused when kit auth is `none` — otherwise anyone could
+ * smuggle upstream keys through an open endpoint.
+ */
+export function resolveUpstreamCredential(headers, options) {
+    const { mode, envVar, headerName, authMode, env = process.env } = options;
+    if (mode === 'header' && authMode === 'none') {
+        throw new Error('Upstream credential mode "header" is not allowed when MCP_AUTH_MODE=none');
+    }
+    if (mode === 'env') {
+        const value = env[envVar]?.trim();
+        if (!value) {
+            throw new Error(`${envVar} is required when upstream credential mode is "env"`);
+        }
+        return { mode: 'env', value, source: 'env' };
+    }
+    const raw = getHeader(headers, headerName);
+    if (!raw?.trim()) {
+        throw new Error(`Missing required upstream credential header: ${headerName}`);
+    }
+    return { mode: 'header', value: raw.trim(), source: 'header' };
+}
+export function parseUpstreamCredentialMode(raw, fallback = 'env') {
+    if (!raw)
+        return fallback;
+    const value = raw.trim().toLowerCase();
+    if (value === 'env' || value === 'header')
+        return value;
+    throw new Error(`Upstream credential mode must be env|header (got ${JSON.stringify(raw)})`);
+}
+/** Guard used by servers that expose a documented `X-<Service>-*` header. */
+export function assertHeaderModeAllowed(authMode) {
+    if (authMode === 'none') {
+        throw new Error('Header-based upstream credentials require bearer or oauth auth');
+    }
+}
+function getHeader(headers, name) {
+    if (typeof headers.get === 'function') {
+        return headers.get(name) ?? undefined;
+    }
+    const record = headers;
+    const direct = record[name] ?? record[name.toLowerCase()];
+    if (Array.isArray(direct))
+        return direct[0];
+    return direct;
+}
+//# sourceMappingURL=upstream.js.map

package/dist/upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.js","sourceRoot":"","sources":["../src/upstream.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAgE,EAChE,OAAkC;IAElC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;IAE1E,IAAI,IAAI,KAAK,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,0EAA0E,CAC3E,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,qDAAqD,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,gDAAgD,UAAU,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,GAAuB,EACvB,WAAmC,KAAK;IAExC,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxD,MAAM,IAAI,KAAK,CAAC,oDAAoD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC9F,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,uBAAuB,CAAC,QAAkB;IACxD,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAChB,OAAgE,EAChE,IAAY;IAEZ,IAAI,OAAQ,OAAmB,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QACnD,OAAQ,OAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;IACrD,CAAC;IACD,MAAM,MAAM,GAAG,OAAwD,CAAC;IACxE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC"}