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

package/dist/start.js

@@ -0,0 +1,83 @@
+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,
+    });
+    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,CAkHvB"}

package/dist/test/helpers.js

@@ -0,0 +1,169 @@
+/** 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() {
+            const response = await client.health();
+            if (response.status !== 200) {
+                throw new Error(`Expected /health 200, got ${response.status}`);
+            }
+            const body = (await response.json());
+            if (body.status !== 'ok') {
+                throw new Error(`Expected health status ok, got ${JSON.stringify(body)}`);
+            }
+            // Health must ignore Host allowlist (Railway probes).
+            const evil = await client.fetch(config.http.healthPath, {
+                method: 'GET',
+                headers: { host: 'evil.example' },
+            });
+            if (evil.status !== 200) {
+                throw new Error(`Expected /health 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,112 @@
+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;
+    /** Unauthenticated health path (default `/health`). */
+    healthPath: 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;
+};
+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;
+    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"}

package/docs/migration.md

@@ -0,0 +1,110 @@
+# Migrating existing kieksme MCP servers to `@kieksme/mcp-http-kit`
+
+This guide covers moving servers off hand-rolled HTTP/auth helpers onto the shared kit.
+
+## SDK decision
+
+The kit targets **MCP TypeScript SDK v2**:
+
+- `@modelcontextprotocol/server`
+- `@modelcontextprotocol/node`
+
+v2 is the current stable release line (spec 2026-07-28). The monolithic
+`@modelcontextprotocol/sdk` (v1) is legacy. New and migrated kieksme servers
+should use v2; do not keep a v1 adapter in the kit.
+
+| Before | After |
+| --- | --- |
+| `mcp-enhancv`, `mcp-balena` | Already on v2 — swap local `http.ts` for the kit |
+| `mcp-contabo`, `mcp-listmonk`, `mcp-swetrix`, `mcp-hashnode` | On v1 `@modelcontextprotocol/sdk` — upgrade packages + imports, then adopt the kit |
+
+## Env var rename map
+
+| Legacy | Canonical |
+| --- | --- |
+| `MCP_HTTP_AUTH_TOKEN` / `MCP_SERVER_AUTH_TOKEN` | `MCP_AUTH_TOKEN` (comma list OK) |
+| `MCP_HTTP_PORT` (as primary) | `PORT` (fallback still reads `MCP_HTTP_PORT`) |
+| `MCP_HTTP_ALLOWED_HOSTS` | `MCP_ALLOWED_HOSTS` |
+| `MCP_HTTP_ALLOWED_ORIGINS` | `MCP_ALLOWED_ORIGINS` |
+| `MCP_HTTP_ENDPOINT` | `MCP_HTTP_PATH` (default `/mcp`) |
+| `HEALTH_ENDPOINT` | `MCP_HEALTH_PATH` (default `/health`) |
+
+Legacy names still work and emit a one-line warning.
+
+New knobs:
+
+- `MCP_AUTH_MODE=bearer|oauth|none`
+- `MCP_AUTH_ALLOW_NONE=true` (only for public read-only demos off localhost)
+- OAuth: `MCP_OAUTH_RESOURCE`, `MCP_OAUTH_AUTHORIZATION_SERVERS`, `MCP_OAUTH_AUDIENCES`, `MCP_OAUTH_JWKS_URL`, `MCP_OAUTH_REQUIRED_SCOPES`, `MCP_OAUTH_SCOPES_SUPPORTED`
+
+## Code shape
+
+**Before (enhancv-style):** local `parseHttpConfig` + `createHttpServer` + Host check before `/health`.
+
+**After:**
+
+```ts
+import { McpServer } from '@modelcontextprotocol/server';
+import { loadConfig, startMcpServer } from '@kieksme/mcp-http-kit';
+
+function createServer(ctx) {
+  const server = new McpServer({ name: 'my-mcp', version: '1.0.0' });
+  // register tools; ctx.auth.scopes available under oauth
+  return server;
+}
+
+await startMcpServer({ createServer, config: loadConfig(process.env, { realm: 'my-mcp' }) });
+```
+
+Important behavior change: **`/health` is served before Host/Origin checks** so Railway (and similar) healthchecks keep working when `MCP_ALLOWED_HOSTS` is tight.
+
+## Per-request upstream credentials
+
+```ts
+import { resolveUpstreamCredential } from '@kieksme/mcp-http-kit';
+
+const cred = resolveUpstreamCredential(ctx.headers, {
+  mode: process.env.UPSTREAM_CREDENTIAL_MODE === 'header' ? 'header' : 'env',
+  envVar: 'CONTABO_API_KEY',
+  headerName: 'X-Contabo-Api-Key',
+  authMode: ctx.auth.mode,
+});
+```
+
+Header mode is rejected when `MCP_AUTH_MODE=none`.
+
+## Deploy templates
+
+Copy from this repo’s `templates/`:
+
+- `Dockerfile` — multi-stage, non-root, `HEALTHCHECK` on `/health`
+- `railway.json` — `healthcheckPath: /health`
+- `server.json` — npm + OCI + `remotes` streamable-http for the official registry
+- `smithery.yaml` — container runtime, HTTP start command
+
+## Contract tests
+
+```ts
+import { createMcpHttpApp } from '@kieksme/mcp-http-kit';
+import { createAppTestClient, createKitContractAssertions } from '@kieksme/mcp-http-kit/test';
+
+const config = loadConfig({ /* test env */ });
+const app = createMcpHttpApp({ createServer, config });
+const client = createAppTestClient(app, config);
+const assertions = createKitContractAssertions(client, config);
+
+await assertions.healthUnauthenticated();
+await assertions.unauthorizedWithoutToken();
+await assertions.forbiddenOnBadHost();
+await assertions.initializeAndListTools(token);
+```
+
+## Checklist
+
+1. Bump to `@modelcontextprotocol/server` + `@modelcontextprotocol/node` (drop v1 sdk).
+2. Add `@kieksme/mcp-http-kit` dependency.
+3. Replace local HTTP/auth modules with `loadConfig` + `startMcpServer`.
+4. Rename Railway/Docker env vars (or keep aliases temporarily).
+5. Ensure `/health` is what Railway probes (kit default).
+6. Copy deploy templates; publish `server.json` via `mcp-publisher` if applicable.
+7. Import kit contract assertions in CI.