@ultimatelemon-eu/mcp-http 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @ultimatelemon-eu/mcp-http
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs an [MCP](https://modelcontextprotocol.io) server over Streamable HTTP in
+stateless mode: `POST /mcp`, `GET /healthz`, an optional base path for a proxy,
+an optional API key the caller brings, and a JSON-RPC 500 instead of a stack
+trace when a handler throws. Everything else is your tools.
+
+```bash
+npm install @ultimatelemon-eu/mcp-http @modelcontextprotocol/server @modelcontextprotocol/node
+```
+
+```ts
+import { McpServer } from '@modelcontextprotocol/server';
+import { startMcpHttpServer } from '@ultimatelemon-eu/mcp-http';
+
+const http = await startMcpHttpServer({
+  createMcpServer: ({ apiKey }) => {
+    const server = new McpServer({ name: 'my-mcp', version: '1.0.0' });
+    server.registerTool('ping', { description: 'Replies pong' }, () => ({
+      content: [{ type: 'text', text: `pong for ${apiKey}` }]
+    }));
+    return server;
+  },
+  port: Number(process.env.PORT ?? 3000),
+  apiKey: { hint: 'Create one at https://example.com/keys.' }
+});
+
+process.once('SIGTERM', () => {
+  void http.close().then(
+    () => process.exit(0),
+    () => process.exit(0)
+  );
+});
+```
+
+## Options
+
+| Option            | Default     | Does                                                         |
+| ----------------- | ----------- | ------------------------------------------------------------ |
+| `createMcpServer` | required    | Returns a new `McpServer` per request, given `{ apiKey }`    |
+| `port`            | required    | `0` picks a free port; read it back from `.port`             |
+| `host`            | `'0.0.0.0'` | `'127.0.0.1'` keeps it local                                 |
+| `basePath`        | `''`        | Also serve `<basePath>/mcp` and `<basePath>/healthz`         |
+| `health`          | always ok   | Return `false` for a 503 on `/healthz`                       |
+| `apiKey`          | off         | Require the caller's key; `hint` is added to the 401 message |
+| `logger`          | silent      | Anything with `error(obj, msg)`, such as pino                |
+
+It returns `{ url, port, close() }`.
+
+## API key
+
+With `apiKey` set, every request to `/mcp` must carry the caller's own key for
+the upstream API, in `X-Api-Key` or as `Authorization: Bearer <key>`
+(`X-Api-Key` wins when both are present). Without one the server answers 401
+before building an MCP server. The key reaches `createMcpServer` as
+`apiKey`; it is never logged or stored.
+
+This suits public servers where each user brings their own credentials: no
+OAuth, no sessions, no database. In claude.ai, add the connector with
+"No sign-in" and the key as a request header.
+
+## Why stateless
+
+A new server per request means no session table, so it does not matter which
+replica a request lands on and a restart loses nothing. The price: no
+server-initiated messages outside a request and no `GET` stream, which is why
+`GET` and `DELETE` on `/mcp` answer 405. Tools that read and return data do not
+need either.
+
+Keep shared state, such as a cache or a loaded list, outside `createMcpServer`
+and close over it, so a request only builds the thin server.
+
+## Upgrading from 1.x
+
+- The MCP SDK moved to v2: replace `@modelcontextprotocol/sdk` with
+  `@modelcontextprotocol/server` and `@modelcontextprotocol/node`, and import
+  `McpServer` from `@modelcontextprotocol/server`.
+- `createMcpServer` receives a context object and may return a promise.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { startMcpHttpServer, type ApiKeyOptions, type Logger, type McpHttpOptions, type McpHttpServer, type RequestContext } from './server.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { startMcpHttpServer } from './server.js';

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+import { type McpServer } from '@modelcontextprotocol/server';
+/** The slice of a pino-style logger this package calls. */
+export interface Logger {
+    error(obj: object, msg?: string): void;
+}
+export interface RequestContext {
+    /** The caller's own key for the upstream API. Set when `apiKey` is configured. */
+    apiKey?: string;
+}
+export interface ApiKeyOptions {
+    /** Added to the 401 message, e.g. where to get a key. */
+    hint?: string;
+}
+export interface McpHttpOptions {
+    /** Builds a fresh server per request; the transport is stateless. */
+    createMcpServer: (context: RequestContext) => McpServer | Promise<McpServer>;
+    port: number;
+    /** Interface to listen on. Default `0.0.0.0`. */
+    host?: string;
+    /** Prefix a proxy leaves on the path, e.g. `/ns`. Both `/mcp` and `<basePath>/mcp` are served. */
+    basePath?: string;
+    /** Readiness for `/healthz`; return false for a 503. Default: always ready. */
+    health?: () => boolean | Promise<boolean>;
+    /** Require every MCP request to carry the caller's key in `X-Api-Key` or `Authorization: Bearer`. */
+    apiKey?: ApiKeyOptions;
+    logger?: Logger;
+}
+export interface McpHttpServer {
+    /** Full URL of the MCP endpoint, e.g. `http://localhost:3000/mcp`. */
+    url: string;
+    /** The port actually bound, useful with `port: 0`. */
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startMcpHttpServer(options: McpHttpOptions): Promise<McpHttpServer>;

package/dist/server.js

@@ -0,0 +1,156 @@
+import { createServer } from 'node:http';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { createMcpHandler } from '@modelcontextprotocol/server';
+const silent = { error: () => { } };
+// PKG-10: Node's `Server.close()` waits for every still-open connection to go
+// idle on its own; a keep-alive client that goes idle (or stays busy) *after*
+// close() has already fired its one-off `closeIdleConnections()` call is
+// never swept again, so the returned promise would never settle. We sweep
+// idle connections repeatedly and, as a last resort, force every remaining
+// connection closed after a fixed grace period - allowing in-flight requests
+// a chance to finish first. 5000ms mirrors `DEFAULT_CONNECTION_TIMEOUT_MS` in
+// packages/drizzle/src/client.ts and stays well under the grace period an
+// orchestrator (Dokploy/k8s) gives a process before SIGKILL (typically
+// 10-30s). packages/drizzle/src/client.ts's closeDb() has its own, longer
+// CLOSE_TIMEOUT_MS backstop for the same class of problem (PKG-18); the two
+// are chosen independently, since a stuck DB client and a stuck HTTP
+// keep-alive socket have different acceptable wait times. This is
+// intentionally internal and not exposed on `McpHttpOptions`.
+const FORCE_CLOSE_TIMEOUT_MS = 5000;
+const IDLE_SWEEP_INTERVAL_MS = 250;
+function normalizeBasePath(basePath = '') {
+    const trimmed = basePath.replace(/\/+$/, '');
+    if (!trimmed)
+        return '';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function jsonRpcError(res, status, message) {
+    sendJson(res, status, {
+        jsonrpc: '2.0',
+        error: { code: -32000, message },
+        id: null
+    });
+}
+function apiKeyFrom(req) {
+    const header = req.headers['x-api-key'];
+    const direct = (Array.isArray(header) ? header[0] : header)?.trim();
+    if (direct)
+        return direct;
+    const bearer = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? '');
+    return bearer?.[1]?.trim() || undefined;
+}
+// PKG-10: closes `http`, letting in-flight requests finish normally. A
+// one-off `closeIdleConnections()` call only catches connections that are
+// already idle at the exact moment close() runs; any connection that is
+// still mid-request at that moment, and only goes idle afterwards, would
+// otherwise never be swept, so we repeat the sweep on an interval instead. If
+// connections are still open once FORCE_CLOSE_TIMEOUT_MS has passed - e.g. a
+// keep-alive client that never goes idle - `closeAllConnections()`
+// force-closes whatever remains so the returned promise always settles and
+// the port is always released. Both timers are unref'd and are always
+// cleared once `http`'s own close callback fires, on every path (success,
+// forced, or error).
+function closeHttpServer(http) {
+    return new Promise((resolve, reject) => {
+        const sweep = setInterval(() => {
+            http.closeIdleConnections();
+        }, IDLE_SWEEP_INTERVAL_MS).unref();
+        const forceExit = setTimeout(() => {
+            http.closeAllConnections();
+        }, FORCE_CLOSE_TIMEOUT_MS).unref();
+        http.close((error) => {
+            clearInterval(sweep);
+            clearTimeout(forceExit);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+        http.closeIdleConnections();
+    });
+}
+export async function startMcpHttpServer(options) {
+    const logger = options.logger ?? silent;
+    const base = normalizeBasePath(options.basePath);
+    const mcpPaths = new Set([`${base}/mcp`, '/mcp']);
+    const healthPaths = new Set([`${base}/healthz`, '/healthz']);
+    // The key travels as pass-through authInfo, the SDK's channel from the
+    // HTTP request to the per-request factory.
+    const mcpHandler = createMcpHandler(({ authInfo }) => options.createMcpServer(authInfo ? { apiKey: authInfo.token } : {}), {
+        onerror: (error) => {
+            logger.error({ err: String(error) }, 'mcp request failed');
+        }
+    });
+    const nodeHandler = toNodeHandler(mcpHandler, {
+        onerror: (error) => {
+            logger.error({ err: String(error) }, 'mcp request failed');
+        }
+    });
+    async function handleMcp(req, res) {
+        // Stateless serving has no session to attach a GET stream or a DELETE to.
+        if (req.method !== 'POST') {
+            res.setHeader('allow', 'POST');
+            jsonRpcError(res, 405, 'Method not allowed');
+            return;
+        }
+        if (!options.apiKey) {
+            await nodeHandler(req, res);
+            return;
+        }
+        const apiKey = apiKeyFrom(req);
+        if (!apiKey) {
+            const hint = options.apiKey.hint ? ` ${options.apiKey.hint}` : '';
+            res.setHeader('www-authenticate', 'Bearer');
+            jsonRpcError(res, 401, `Missing API key: send it in the X-Api-Key header or as Authorization: Bearer <key>.${hint}`);
+            return;
+        }
+        await nodeHandler(Object.assign(req, {
+            auth: { token: apiKey, clientId: 'api-key', scopes: [] }
+        }), res);
+    }
+    async function handle(req, res) {
+        const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+        if (healthPaths.has(path) && req.method === 'GET') {
+            const ok = options.health ? await options.health() : true;
+            sendJson(res, ok ? 200 : 503, { status: ok ? 'ok' : 'starting' });
+            return;
+        }
+        if (mcpPaths.has(path)) {
+            await handleMcp(req, res);
+            return;
+        }
+        sendJson(res, 404, { error: 'Not found' });
+    }
+    const http = createServer((req, res) => {
+        handle(req, res).catch((error) => {
+            logger.error({ err: String(error), url: req.url }, 'request failed');
+            if (!res.headersSent)
+                jsonRpcError(res, 500, 'Internal server error');
+            else
+                res.end();
+        });
+    });
+    const host = options.host ?? '0.0.0.0';
+    await new Promise((resolve, reject) => {
+        http.once('error', reject);
+        http.listen(options.port, host, () => {
+            http.off('error', reject);
+            resolve();
+        });
+    });
+    const address = http.address();
+    const port = typeof address === 'object' && address ? address.port : options.port;
+    const shownHost = host === '0.0.0.0' ? 'localhost' : host;
+    return {
+        url: `http://${shownHost}:${String(port)}${base}/mcp`,
+        port,
+        close: async () => {
+            await closeHttpServer(http);
+            await mcpHandler.close();
+        }
+    };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@ultimatelemon-eu/mcp-http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Run an MCP server over stateless Streamable HTTP: /mcp, /healthz, a base path for proxies, the caller's own API key per request, and errors that never leak a stack trace.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ultimatelemon/packages.git",
+    "directory": "packages/mcp-http"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/node": "^2.1.1",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "@types/node": "^24.19.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.1",
+    "zod": "^4.6.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/node": "^2.1.0",
+    "@modelcontextprotocol/server": "^2.3.0"
+  }
+}