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

package/README.md

@@ -1,3 +1,59 @@
-# 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,
+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/sdk
+```
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { startMcpHttpServer } from '@ultimatelemon-eu/mcp-http';
+
+function createMcpServer() {
+  const server = new McpServer({ name: 'my-mcp', version: '1.0.0' });
+  server.registerTool('ping', { description: 'Replies pong' }, () => ({
+    content: [{ type: 'text', text: 'pong' }]
+  }));
+  return server;
+}
+
+const http = await startMcpHttpServer({
+  createMcpServer,
+  port: Number(process.env.PORT ?? 3000)
+});
+
+process.once('SIGTERM', () => void http.close().then(() => process.exit(0)));
+```
+
+## Options
+
+| Option            | Default     | Does                                                 |
+| ----------------- | ----------- | ---------------------------------------------------- |
+| `createMcpServer` | required    | Returns a new `McpServer`; called once per request   |
+| `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`               |
+| `logger`          | silent      | Anything with `error(obj, msg)`, such as pino        |
+
+It returns `{ url, port, close() }`.
+
+## Why stateless
+
+A new server and transport 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 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 an API client, a cache or a loaded list, outside
+`createMcpServer` and close over it, so a request only builds the thin server.
+
+## Auth
+
+There is none. Put the server behind an authenticating proxy (Airlock, for the
+UltimateLemon MCPs) or keep it on localhost.

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** The slice of a pino-style logger this package calls. */
+export interface Logger {
+    error(obj: object, msg?: string): void;
+}
+export interface McpHttpOptions {
+    /** Builds a fresh server per request; the transport is stateless. */
+    createMcpServer: () => 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>;
+    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,86 @@
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+const silent = { error: () => { } };
+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
+    });
+}
+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']);
+    async function handleMcp(req, res) {
+        // Stateless mode 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;
+        }
+        const server = options.createMcpServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true
+        });
+        res.on('close', () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, 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: () => new Promise((resolve, reject) => {
+            http.close((error) => (error ? reject(error) : resolve()));
+            http.closeIdleConnections();
+        })
+    };
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@ultimatelemon-eu/mcp-http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Run an MCP server over stateless Streamable HTTP: /mcp, /healthz, a base path for proxies, 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"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@types/node": "^24.19.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}