@lerianstudio/matcher-mcp 1.0.0-beta.5

package/dist/transport/http.js

@@ -0,0 +1,154 @@
+// Streamable HTTP transport boundary for the Matcher MCP server.
+//
+// This module mounts the SDK's Streamable HTTP server transport on a plain
+// Node HTTP server. It runs in the SDK's documented *stateless* mode
+// (`sessionIdGenerator: undefined`): a fresh McpServer + transport is created
+// per inbound POST /mcp request and torn down when the response completes.
+// Statelessness is the right model for a credential relay — each request
+// carries its own bearer token (task 1.1.3) and the server holds no per-client
+// state between calls. We follow the SDK's stateless recipe rather than
+// inventing a session model.
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { runWithBearerToken } from '../auth/request-token.js';
+import { loadConfig } from '../config.js';
+import { buildMcpServer } from '../server.js';
+import { BodySizeGuard, BodyTooLargeError, HEADERS_TIMEOUT_MS, REQUEST_TIMEOUT_MS, } from './body-limit.js';
+/** The conventional MCP protocol endpoint path. */
+const MCP_PATH = '/mcp';
+/** Liveness endpoint, separate from the MCP protocol (used by the container). */
+const HEALTHZ_PATH = '/healthz';
+/**
+ * Read the request body and return it as a string, bounded by `maxBodyBytes`.
+ * The SDK's Node transport can parse the body itself, but reading it here lets
+ * us pass a pre-parsed JSON body and keeps the handler in control of malformed
+ * input — and, critically, lets us cap an unbounded read.
+ *
+ * The size guard is checked BEFORE each chunk is retained, so an over-limit
+ * payload is rejected (via `BodyTooLargeError`) without ever buffering more than
+ * the limit (+ one chunk) of an attacker's body. The guard counts only bytes —
+ * it never inspects body content, headers, or any token.
+ */
+async function readBody(req, maxBodyBytes) {
+    const guard = new BodySizeGuard(maxBodyBytes);
+    const chunks = [];
+    for await (const chunk of req) {
+        const buf = chunk;
+        // Throws BodyTooLargeError the moment the running total exceeds the limit,
+        // before the over-limit chunk is appended to memory.
+        guard.add(buf.length);
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Handle a single MCP protocol request in stateless mode: spin up a transport
+ * + server, connect, dispatch, and tear both down when the response finishes.
+ */
+async function handleMcpRequest(info, config, req, res) {
+    // Read + bound the body BEFORE spinning up the transport/server, so an
+    // over-limit payload is rejected without allocating an McpServer for it.
+    let parsedBody;
+    if (req.method === 'POST') {
+        const raw = await readBody(req, config.maxBodyBytes);
+        parsedBody = raw.length > 0 ? JSON.parse(raw) : undefined;
+    }
+    const transport = new StreamableHTTPServerTransport({
+        // Stateless: no session id is issued or validated. Each request is
+        // self-contained — the SDK's documented stateless configuration.
+        sessionIdGenerator: undefined,
+    });
+    const server = buildMcpServer(info);
+    // Ensure both are released once the HTTP response is done, regardless of
+    // success or error path.
+    res.on('close', () => {
+        void transport.close();
+        void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, parsedBody);
+}
+/**
+ * Build (but do not start) the Node HTTP server that routes /healthz and /mcp.
+ * Exposed separately from `start` so tests can drive a listener on an ephemeral
+ * port and close it deterministically.
+ *
+ * `config` is optional and defaults to `loadConfig()` so existing call sites
+ * (tests, `start`) keep working; it supplies `maxBodyBytes` for the inbound
+ * body-size guard. Server-level timeouts (`requestTimeout` / `headersTimeout`)
+ * are set on the returned server so a stuck or trickled request is shed.
+ */
+export function createHttpServer(info, config = loadConfig()) {
+    const httpServer = createServer((req, res) => {
+        const url = req.url ?? '/';
+        const path = url.split('?', 1)[0];
+        if (req.method === 'GET' && path === HEALTHZ_PATH) {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('ok');
+            return;
+        }
+        if (path === MCP_PATH) {
+            // Seed the request-scoped auth store at the boundary so tool handlers can
+            // recover the caller's bearer token even when the SDK does not thread the
+            // raw Authorization header through `extra`. The header value is forwarded
+            // verbatim and never logged here (token-relay rule). `req.headers` lower-
+            // cases names, so `authorization` is the canonical key.
+            runWithBearerToken(req.headers.authorization, () => {
+                handleMcpRequest(info, config, req, res).catch((err) => {
+                    // An over-limit body is a client fault: answer 413 (no token, no body
+                    // content — BodyTooLargeError carries only byte counts).
+                    if (err instanceof BodyTooLargeError) {
+                        if (!res.headersSent) {
+                            res.writeHead(err.status, { 'Content-Type': 'application/json' });
+                        }
+                        res.end(JSON.stringify({
+                            jsonrpc: '2.0',
+                            error: { code: -32600, message: 'request body too large' },
+                            id: null,
+                        }));
+                        return;
+                    }
+                    // Never leak internals (and never a token) into the response body.
+                    if (!res.headersSent) {
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                    }
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: { code: -32603, message: 'internal server error' },
+                        id: null,
+                    }));
+                    console.error('matcher-mcp request handling failed:', err);
+                });
+            });
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('not found');
+    });
+    // Shed stuck / Slowloris-style connections. headersTimeout must be < the
+    // overall requestTimeout (Node enforces this) so a header trickle is dropped
+    // well before the full-request budget.
+    httpServer.requestTimeout = REQUEST_TIMEOUT_MS;
+    httpServer.headersTimeout = HEADERS_TIMEOUT_MS;
+    return httpServer;
+}
+/**
+ * Start the MCP HTTP server listening on the configured port. Resolves once the
+ * listener is bound. The returned handle closes the listener gracefully.
+ */
+export function start(config, info) {
+    const httpServer = createHttpServer(info, config);
+    return new Promise((resolve, reject) => {
+        httpServer.once('error', reject);
+        httpServer.listen(config.port, () => {
+            httpServer.removeListener('error', reject);
+            resolve({
+                httpServer,
+                close: () => new Promise((res, rej) => {
+                    httpServer.close((err) => (err ? rej(err) : res()));
+                }),
+            });
+        });
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/transport/http.js.map

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

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@lerianstudio/matcher-mcp",
+  "version": "1.0.0-beta.5",
+  "type": "module",
+  "description": "Model Context Protocol server for the Matcher reconciliation engine",
+  "license": "Apache-2.0",
+  "author": "Lerian Studio",
+  "keywords": [
+    "model-context-protocol",
+    "mcp",
+    "matcher",
+    "reconciliation",
+    "mcp-server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LerianStudio/matcher.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/LerianStudio/matcher/tree/main/mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "packageManager": "pnpm@11.5.2",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=11.5.2 <12"
+  },
+  "bin": {
+    "matcher-mcp": "./dist/server.js"
+  },
+  "main": "./dist/server.js",
+  "scripts": {
+    "vendor-spec": "node scripts/vendor-spec.mjs",
+    "predev": "node scripts/vendor-spec.mjs",
+    "dev": "node --watch --experimental-strip-types src/server.ts",
+    "prebuild": "node scripts/vendor-spec.mjs",
+    "build": "tsc",
+    "postbuild": "node scripts/vendor-spec.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/exporter-metrics-otlp-http": "0.219.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.219.0",
+    "@opentelemetry/resources": "2.8.0",
+    "@opentelemetry/sdk-metrics": "2.8.0",
+    "@opentelemetry/sdk-node": "0.219.0",
+    "@opentelemetry/semantic-conventions": "1.41.1",
+    "ajv": "^8.20.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.10.2",
+    "eslint": "^10.4.1",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.60.1",
+    "vitest": "^4.1.5"
+  }
+}