@zenixsolutions/streamlined-mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.2.0 — unreleased
+
+- **HTTP mode** (`--http [--port N] [--host H]`): MCP Streamable HTTP at `/mcp` on `127.0.0.1:3100`, for hosting behind Nginx (RFC-002). Stateless; serves 2025-era and 2026-07-28 clients.
+  - Each request authenticates with the caller's own API token (`Authorization: Bearer`). Any token may connect; it is checked with the app, cached only as a hash for 5 minutes, and used for that request only. No secret is configured on the server: `STREAMLINED_TOKEN` and `STREAMLINED_EXTRA_HEADER_*` are refused in this mode.
+  - Limits: 32 requests in flight, 30 checks per minute of tokens the app hasn't accepted in the last 24 hours (accepted tokens are exempt), 128 KB bodies, JSON only. Browser requests (`Origin`) and `subscriptions/listen` are refused.
+  - Graceful shutdown: on `TERM`, in-flight requests get up to 25 seconds to finish.
+  - `GET /healthz` for monitoring.
+- stdio mode is unchanged and remains the default.
+- `--help` and `--version`.
+- The 401 message no longer names `STREAMLINED_TOKEN`, since the token may come from a header.
+
+## 0.1.1 — 2026-10-19
+
+- No functional changes.
+- First release published by GitHub Actions through npm trusted publishing (OIDC). No npm token was used.
+
+## 0.1.0 — 2026-10-19
+
+First release (published by hand).
+
+- `streamlined_list_new_orders`: the cursor-paginated queue of New orders with a reference number and no contact, oldest first. Contacts are matched to the order's record type, with a fallback to the provider's details. The 4 latest notes are included as plain text.
+- `streamlined_list_record_types`.
+- `streamlined_add_order_note`: internal notes only, guarded by `reference_num`. Off unless `STREAMLINED_ENABLE_WRITES=true`.

package/README.md

@@ -2,27 +2,42 @@
 
 An MCP server (stdio) that lets an AI agent work the Streamlined Record Retrieval order queue: list New orders that have a reference number and no contact yet, see each order's provider, matching contacts and latest notes, and add internal notes.
 
-It runs locally as a subprocess of the MCP client (for example Grok Bot). It opens no ports, and all configuration comes from environment variables.
+It runs in one of two modes:
+
+- **stdio** (default): a subprocess of a local MCP client. Opens no ports; the token comes from `STREAMLINED_TOKEN`.
+- **HTTP** (`--http`): a Streamable HTTP server for a reverse proxy, at `/mcp` on `127.0.0.1:3100`. It holds no token: every request must send the caller's own API token as `Authorization: Bearer <token>`.
 
 ## Install / run
 
 ```sh
-npx -y @zenixsolutions/streamlined-mcp@0.1.0
+npx -y @zenixsolutions/streamlined-mcp@0.2.0                       # stdio
+npx -y @zenixsolutions/streamlined-mcp@0.2.0 --http --port 3100    # HTTP, behind Nginx
 ```
 
-Requires Node.js 20.3 or later. Pin the version in your MCP client configuration.
+Requires Node.js 20.3 or later. Pin the version.
 
 ## Configuration
 
-| Variable | Required | Description |
-|---|---|---|
-| `STREAMLINED_BASE_URL` | yes | Base URL of the app, `https://` only, e.g. `https://admin.example.com` |
-| `STREAMLINED_TOKEN` | yes | API token for the integration's service user. Reading needs no special permission; `notes:write` is needed to add notes |
-| `STREAMLINED_ENABLE_WRITES` | no | `true` to register the note tool. Default: read-only |
-| `STREAMLINED_EXTRA_HEADER_NAME` / `STREAMLINED_EXTRA_HEADER_VALUE` | no | An extra header sent on every request, e.g. a secret that a Cloudflare rule checks |
+| Variable | Mode | Required | Description |
+|---|---|---|---|
+| `STREAMLINED_BASE_URL` | both | yes | Base URL of the app, `https://` only, e.g. `https://admin.example.com` |
+| `STREAMLINED_TOKEN` | stdio | yes | API token for the integration's service user. Reading needs no special permission; `notes:write` is needed to add notes. **Refused in HTTP mode** |
+| `STREAMLINED_ENABLE_WRITES` | both | no | `true` to register the note tool. Default: read-only |
+| `STREAMLINED_EXTRA_HEADER_NAME` / `STREAMLINED_EXTRA_HEADER_VALUE` | stdio | no | An extra header sent to the app on every request, e.g. a secret that a Cloudflare rule checks. **Refused in HTTP mode** |
+| `STREAMLINED_HTTP_PORT` / `STREAMLINED_HTTP_HOST` | HTTP | no | Default `3100` / `127.0.0.1`. `--port` and `--host` take precedence |
+| `STREAMLINED_HTTP_ALLOW_REMOTE_BIND` | HTTP | no | `true` to allow a non-loopback host. Only for a private network: the server speaks plain HTTP |
 
 The server exits with a clear message if the configuration is invalid. Secrets are never printed.
 
+## HTTP mode
+
+- `POST /mcp` (MCP Streamable HTTP, stateless; 2025-era and 2026-07-28 clients) and `GET /healthz`. Everything else returns 404.
+- Every `/mcp` request needs `Authorization: Bearer <API token>`. Any token may connect: it is checked with the app (`GET /api/order_types`), which accepts or rejects it, and the result is cached for 5 minutes, as a hash only. The tools then call the app with that same token, for that request only.
+- Rejected: requests with an `Origin` header (browsers) with 403; missing or malformed tokens with 401, without contacting the app; tokens the app refuses with 401; more than 30 checks a minute of tokens the app hasn't accepted in the last 24 hours with 429 (tokens accepted in that time are exempt; the exemption is in memory, so it resets on restart); more than 32 requests in flight with 503; non-JSON bodies with 415; bodies over 128 KB with 413; `subscriptions/listen` with 400.
+- Logs: one line per request (method, route, status, duration). No headers, bodies, tokens or IP addresses.
+
+See `docs/DEPLOYMENT.md` in the repository for the Forge, Nginx and Cloudflare setup.
+
 ## Tools
 
 | Tool | Kind | What it does |

package/dist/api.js

@@ -16,7 +16,7 @@ export class ApiError extends Error {
 function statusMessage(status, detail) {
     switch (status) {
         case 401:
-            return "The Streamlined API rejected the token (401). Check STREAMLINED_TOKEN; it may have been revoked.";
+            return "The Streamlined API rejected the token (401). It may be wrong or revoked.";
         case 403:
             return "The token is not allowed to do this (403). Writing notes needs the notes:write permission on the token.";
         case 404:
@@ -164,7 +164,7 @@ export class StreamlinedClient {
         if (!response.ok) {
             // A Cloudflare challenge page comes back as HTML 403
             if (response.status === 403 && !contentType.includes("application/json")) {
-                throw new ApiError(403, "Blocked before reaching the app (Cloudflare challenge). The Cloudflare skip rule or STREAMLINED_EXTRA_HEADER_* settings need attention.");
+                throw new ApiError(403, "Blocked before reaching the app (Cloudflare challenge). The Cloudflare skip rule or STREAMLINED_EXTRA_HEADER_* settings need attention.", "blocked");
             }
             const detail = response.status === 422 ? validationDetail(body, (s) => this.redact(s)) : undefined;
             throw new ApiError(response.status, statusMessage(response.status, detail ? oneLine(detail) : undefined));

package/dist/cli.js

@@ -0,0 +1,42 @@
+import { ConfigError } from "./config.js";
+import { SERVER_NAME } from "./server.js";
+export const USAGE = `Usage: ${SERVER_NAME} [--http [--port N] [--host H]] [--version] [--help]
+
+Without arguments, runs on stdio (set STREAMLINED_BASE_URL and STREAMLINED_TOKEN).
+--http runs a Streamable HTTP server for a reverse proxy (default 127.0.0.1:3100, path /mcp).
+Clients authenticate with 'Authorization: Bearer <Streamlined API token>'.`;
+export function parseArgs(argv) {
+    const cli = { mode: "stdio" };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const [flag, inline] = arg.startsWith("--") && arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+        const value = () => {
+            const v = inline ?? argv[++i];
+            if (v === undefined || v === "")
+                throw new ConfigError(`${flag} needs a value.`);
+            return v;
+        };
+        switch (flag) {
+            case "--http":
+                cli.mode = "http";
+                break;
+            case "--port":
+                cli.port = value();
+                break;
+            case "--host":
+                cli.host = value();
+                break;
+            case "--help":
+            case "-h":
+                return { mode: "help" };
+            case "--version":
+            case "-v":
+                return { mode: "version" };
+            default:
+                throw new ConfigError(`Unknown argument: ${arg.slice(0, 40)}\n\n${USAGE}`);
+        }
+    }
+    if (cli.mode === "stdio" && (cli.port !== undefined || cli.host !== undefined))
+        throw new ConfigError("--port and --host need --http.");
+    return cli;
+}

package/dist/config.js

@@ -1,12 +1,17 @@
 /**
- * Configuration comes only from environment variables. The published package
- * contains no hostnames, tokens or other client-specific values.
+ * Configuration comes only from environment variables (and, for HTTP mode, the
+ * command line). The published package contains no hostnames, tokens or other
+ * client-specific values.
  */
 export class ConfigError extends Error {
 }
 const HEADER_NAME = /^[A-Za-z0-9-]{1,64}$/;
 const RESERVED_HEADERS = new Set(["authorization", "accept", "content-type", "host", "cookie", "user-agent", "content-length"]);
-export function loadConfig(env) {
+const TOKEN_PATTERN = /^[\x21-\x7e]+$/;
+export const DEFAULT_HTTP_PORT = 3100;
+export const DEFAULT_HTTP_HOST = "127.0.0.1";
+const LOOPBACK = new Set(["127.0.0.1", "::1"]);
+function loadCommon(env) {
     const rawBase = env.STREAMLINED_BASE_URL?.trim();
     if (!rawBase)
         throw new ConfigError("STREAMLINED_BASE_URL is required (for example https://admin.example.com).");
@@ -24,11 +29,6 @@ export function loadConfig(env) {
     if (url.search || url.hash)
         throw new ConfigError("STREAMLINED_BASE_URL must not contain a query string or fragment.");
     const baseUrl = url.origin + url.pathname.replace(/\/+$/, "");
-    const token = env.STREAMLINED_TOKEN?.trim();
-    if (!token)
-        throw new ConfigError("STREAMLINED_TOKEN is required.");
-    if (!/^[\x21-\x7e]+$/.test(token))
-        throw new ConfigError("STREAMLINED_TOKEN must be one line of visible ASCII with no whitespace; check how it was pasted.");
     const headerName = env.STREAMLINED_EXTRA_HEADER_NAME?.trim();
     const headerValue = env.STREAMLINED_EXTRA_HEADER_VALUE?.trim();
     let extraHeader;
@@ -45,5 +45,37 @@ export function loadConfig(env) {
     }
     const writes = (env.STREAMLINED_ENABLE_WRITES ?? "").trim().toLowerCase();
     const enableWrites = writes === "true" || writes === "1" || writes === "yes";
-    return { baseUrl, token, extraHeader, enableWrites };
+    return extraHeader ? { baseUrl, extraHeader, enableWrites } : { baseUrl, enableWrites };
+}
+/** stdio mode: one token for the whole process, from STREAMLINED_TOKEN. */
+export function loadConfig(env) {
+    const common = loadCommon(env);
+    const token = env.STREAMLINED_TOKEN?.trim();
+    if (!token)
+        throw new ConfigError("STREAMLINED_TOKEN is required.");
+    if (!TOKEN_PATTERN.test(token))
+        throw new ConfigError("STREAMLINED_TOKEN must be one line of visible ASCII with no whitespace; check how it was pasted.");
+    return { ...common, token };
+}
+/** HTTP mode. `options` come from the command line and take precedence over STREAMLINED_HTTP_HOST / STREAMLINED_HTTP_PORT. */
+export function loadHttpConfig(env, options = {}) {
+    if (env.STREAMLINED_TOKEN !== undefined) {
+        throw new ConfigError("STREAMLINED_TOKEN must not be set in HTTP mode: every client sends its own token in the Authorization header. Remove it from the daemon's environment.");
+    }
+    if (env.STREAMLINED_EXTRA_HEADER_NAME !== undefined || env.STREAMLINED_EXTRA_HEADER_VALUE !== undefined) {
+        throw new ConfigError("STREAMLINED_EXTRA_HEADER_* must not be set in HTTP mode: the server holds no secrets. Allow the server's IP in the Cloudflare /api/* skip rule instead.");
+    }
+    const base = loadCommon(env);
+    const rawPort = (options.port ?? env.STREAMLINED_HTTP_PORT ?? String(DEFAULT_HTTP_PORT)).trim();
+    if (!/^\d{1,5}$/.test(rawPort) || Number(rawPort) < 1 || Number(rawPort) > 65535) {
+        throw new ConfigError("The HTTP port must be a number from 1 to 65535.");
+    }
+    const host = (options.host ?? env.STREAMLINED_HTTP_HOST ?? DEFAULT_HTTP_HOST).trim();
+    if (!/^[A-Za-z0-9.:-]{1,253}$/.test(host))
+        throw new ConfigError("The HTTP host must be an IP address or hostname.");
+    const allowRemote = (env.STREAMLINED_HTTP_ALLOW_REMOTE_BIND ?? "").trim().toLowerCase() === "true";
+    if (!LOOPBACK.has(host) && !allowRemote) {
+        throw new ConfigError(`Refusing to listen on ${host}: HTTP mode speaks plain HTTP and must sit behind a TLS proxy on the same machine. Use 127.0.0.1 or ::1, or set STREAMLINED_HTTP_ALLOW_REMOTE_BIND=true if a private network carries the traffic.`);
+    }
+    return { base, host, port: Number(rawPort) };
 }

package/dist/http.js

@@ -0,0 +1,351 @@
+/**
+ * HTTP mode: MCP Streamable HTTP on loopback, behind a TLS-terminating proxy (Nginx on Forge).
+ *
+ * Every request must carry the caller's own Streamlined API token as `Authorization: Bearer`.
+ * The process holds no credential of its own: the token is checked against the API, cached only
+ * as a SHA-256 hash, and used for that one request. Nothing about a request is logged except the
+ * method, the route, the status and the duration.
+ */
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+import { createServer as createNodeServer } from "node:http";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { ApiError, StreamlinedClient } from "./api.js";
+import { createServer, RecordTypeCache } from "./server.js";
+export const MCP_PATH = "/mcp";
+export const HEALTH_PATH = "/healthz";
+export const MAX_REQUEST_BYTES = 128 * 1024;
+export const MAX_IN_FLIGHT = 32;
+export const TOKEN_TTL_MS = 5 * 60 * 1000;
+export const UNKNOWN_TOKEN_CHECKS_PER_MINUTE = 30;
+/** A token the API accepted within this window is re-checked outside the per-minute budget, so junk tokens cannot lock it out. */
+export const KNOWN_TOKEN_MS = 24 * 60 * 60 * 1000;
+export const MAX_CACHED_TOKENS = 1000;
+const TOKEN_PATTERN = /^[\x21-\x7e]{1,512}$/;
+const BEARER = /^Bearer +(\S+) *$/i;
+/** Request headers passed through to the MCP handler (plus any `mcp-param-*`). Authorization is deliberately not one of them. */
+const FORWARDED_HEADERS = new Set(["content-type", "accept", "mcp-protocol-version", "mcp-session-id", "last-event-id", "mcp-method", "mcp-name"]);
+/** Long-lived streams: the tools never change, so there is nothing to subscribe to, and open streams would hold capacity. */
+const REFUSED_METHODS = new Set(["subscriptions/listen"]);
+export const SHUTDOWN_GRACE_MS = 25_000;
+export function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function remember(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    while (map.size > MAX_CACHED_TOKENS)
+        map.delete(map.keys().next().value);
+}
+/**
+ * Any token may connect; the API decides. This class only avoids re-asking the API on every
+ * request (accepted tokens are trusted for TOKEN_TTL_MS) and stops junk tokens from flooding
+ * the API through this server: at most UNKNOWN_TOKEN_CHECKS_PER_MINUTE checks of tokens the
+ * API has not accepted in the last KNOWN_TOKEN_MS. Tokens are held only as SHA-256 hashes.
+ */
+export class TokenVerifier {
+    check;
+    now;
+    verified = new Map();
+    known = new Map();
+    pending = new Map();
+    windowStart = 0;
+    windowCount = 0;
+    constructor(check, now = Date.now) {
+        this.check = check;
+        this.now = now;
+    }
+    async verify(token) {
+        const key = hashToken(token);
+        const now = this.now();
+        const until = this.verified.get(key);
+        if (until !== undefined) {
+            if (until > now)
+                return "ok";
+            this.verified.delete(key);
+        }
+        const inFlight = this.pending.get(key);
+        if (inFlight)
+            return inFlight;
+        const acceptedAt = this.known.get(key);
+        const exempt = acceptedAt !== undefined && now - acceptedAt < KNOWN_TOKEN_MS;
+        if (!exempt) {
+            if (now - this.windowStart >= 60_000) {
+                this.windowStart = now;
+                this.windowCount = 0;
+            }
+            if (this.windowCount >= UNKNOWN_TOKEN_CHECKS_PER_MINUTE)
+                return "limited";
+            this.windowCount += 1;
+        }
+        const run = this.run(token, key).finally(() => this.pending.delete(key));
+        this.pending.set(key, run);
+        return run;
+    }
+    async run(token, key) {
+        try {
+            await this.check(token);
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                if (error.kind === "http" && (error.status === 401 || error.status === 403)) {
+                    this.known.delete(key);
+                    return "invalid";
+                }
+                if (error.kind === "timeout")
+                    return "timeout";
+            }
+            return "unavailable";
+        }
+        const now = this.now();
+        remember(this.verified, key, now + TOKEN_TTL_MS);
+        remember(this.known, key, now);
+        return "ok";
+    }
+}
+export function bearerToken(header) {
+    const match = header ? BEARER.exec(header) : null;
+    const token = match?.[1];
+    return token && TOKEN_PATTERN.test(token) ? token : undefined;
+}
+class RequestTooLarge extends Error {
+}
+async function readBody(req, limit) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        size += buf.byteLength;
+        if (size > limit)
+            throw new RequestTooLarge();
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks, size);
+}
+function sendError(res, status, message, headers = {}) {
+    const body = JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null });
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", ...headers });
+    res.end(body);
+    return status;
+}
+async function writeResponse(res, response) {
+    const headers = { "cache-control": "no-store" };
+    response.headers.forEach((value, key) => {
+        if (key !== "content-length" && key !== "transfer-encoding" && key !== "connection")
+            headers[key] = value;
+    });
+    res.writeHead(response.status, headers);
+    if (response.body) {
+        const reader = response.body.getReader();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done || res.destroyed)
+                    break;
+                // Wait for the socket to drain, or stop if the client went away meanwhile
+                if (!res.write(value)) {
+                    const done = new AbortController();
+                    await Promise.race([once(res, "drain", { signal: done.signal }), once(res, "close", { signal: done.signal })]).catch(() => undefined);
+                    done.abort();
+                }
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+        }
+    }
+    if (!res.destroyed)
+        res.end();
+    return response.status;
+}
+/** The request path without its query. Plain string handling: request targets are attacker-controlled, so no URL parsing. */
+function pathOf(target) {
+    const raw = target ?? "/";
+    const q = raw.indexOf("?");
+    return q === -1 ? raw : raw.slice(0, q);
+}
+function route(pathname) {
+    return pathname === MCP_PATH || pathname === HEALTH_PATH ? pathname : "(other)";
+}
+/** JSON-RPC methods named in a request body (single message or batch); empty if the body is not JSON. */
+function methodsIn(body) {
+    try {
+        // Decode exactly as the SDK does (TextDecoder strips a UTF-8 BOM), so both see the same messages
+        const parsed = JSON.parse(new TextDecoder().decode(body));
+        const messages = Array.isArray(parsed) ? parsed : [parsed];
+        return messages.flatMap((m) => (m && typeof m === "object" && typeof m.method === "string" ? [m.method] : []));
+    }
+    catch {
+        return [];
+    }
+}
+/** Builds the request listener; exported separately so tests can drive it without a port. */
+export function createHttpApp(config, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const log = deps.log ?? ((line) => console.error(line));
+    const now = deps.now ?? Date.now;
+    const types = new RecordTypeCache(undefined, now);
+    const clientFor = (token) => new StreamlinedClient({ ...config.base, token }, fetchImpl);
+    const verifier = new TokenVerifier(async (token) => {
+        await clientFor(token).request("GET", "order_types");
+    }, now);
+    const handler = createMcpHandler((ctx) => {
+        const token = ctx.authInfo?.token;
+        // Never reached without a verified token: the listener below supplies authInfo only after verification.
+        if (!token)
+            throw new Error("unauthenticated request reached the MCP handler");
+        return createServer({ ...config.base, token }, clientFor(token), types);
+    }, {
+        // The tools emit no progress notifications, so responses are plain JSON in practice
+        maxRequestBodySize: MAX_REQUEST_BYTES,
+        // Belt and braces: subscriptions are refused before reaching the handler
+        maxSubscriptions: 1,
+        // Error messages can quote request content, so only the error's name is logged.
+        onerror: (error) => log(`mcp: ${error.name}`)
+    });
+    let inFlight = 0;
+    async function serve(req, res) {
+        const pathname = pathOf(req.url);
+        const method = req.method ?? "GET";
+        if (pathname === HEALTH_PATH && (method === "GET" || method === "HEAD")) {
+            res.writeHead(200, { "content-type": "text/plain", "cache-control": "no-store" });
+            res.end(method === "HEAD" ? undefined : "ok");
+            return 200;
+        }
+        if (pathname !== MCP_PATH)
+            return sendError(res, 404, "Not found.");
+        // MCP clients do not send Origin; browsers do. Refusing them stops cross-site use of a token.
+        if (req.headers.origin !== undefined)
+            return sendError(res, 403, "Browser requests are not accepted.");
+        if (method !== "POST" && method !== "GET" && method !== "DELETE")
+            return sendError(res, 405, "Method not allowed.", { allow: "POST, GET, DELETE" });
+        const token = bearerToken(req.headers.authorization);
+        if (!token) {
+            return sendError(res, 401, "Send your Streamlined API token as 'Authorization: Bearer <token>'.", {
+                "www-authenticate": 'Bearer realm="streamlined-mcp"'
+            });
+        }
+        let body;
+        if (method === "POST") {
+            const type = (req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+            if (type !== "application/json")
+                return sendError(res, 415, "Content-Type must be application/json.");
+            const declared = Number(req.headers["content-length"] ?? NaN);
+            if (Number.isFinite(declared) && declared > MAX_REQUEST_BYTES)
+                return sendError(res, 413, "Request body too large.");
+        }
+        switch (await verifier.verify(token)) {
+            case "ok":
+                break;
+            case "invalid":
+                return sendError(res, 401, "The Streamlined API rejected this token. It may be wrong or revoked.", {
+                    "www-authenticate": 'Bearer realm="streamlined-mcp", error="invalid_token"'
+                });
+            case "limited":
+                return sendError(res, 429, "Too many unrecognised tokens. Try again in a minute.", { "retry-after": "60" });
+            case "timeout":
+                return sendError(res, 504, "The Streamlined API did not respond while checking the token. Try again.");
+            case "unavailable":
+                return sendError(res, 502, "Could not check the token with the Streamlined API. Try again later.");
+        }
+        if (method === "POST") {
+            try {
+                body = await readBody(req, MAX_REQUEST_BYTES);
+            }
+            catch (error) {
+                if (error instanceof RequestTooLarge)
+                    return sendError(res, 413, "Request body too large.", { connection: "close" });
+                throw error;
+            }
+        }
+        const header = req.headers["mcp-method"];
+        if ((typeof header === "string" && REFUSED_METHODS.has(header)) || (body && methodsIn(body).some((m) => REFUSED_METHODS.has(m)))) {
+            return sendError(res, 400, "Subscriptions are not supported by this server.");
+        }
+        const abort = new AbortController();
+        res.once("close", () => {
+            if (!res.writableFinished)
+                abort.abort();
+        });
+        const headers = new Headers();
+        for (const [name, value] of Object.entries(req.headers)) {
+            if (typeof value === "string" && (FORWARDED_HEADERS.has(name) || name.startsWith("mcp-param-")))
+                headers.set(name, value);
+        }
+        const request = new Request(`http://localhost${MCP_PATH}`, {
+            method,
+            headers,
+            body: body ? new Uint8Array(body) : undefined,
+            signal: abort.signal
+        });
+        const response = await handler.fetch(request, { authInfo: { token, clientId: "streamlined-api-token", scopes: [] } });
+        return writeResponse(res, response);
+    }
+    /** Never rejects: every failure becomes a 500 or a dropped connection, never an unhandled rejection. */
+    async function listener(req, res) {
+        const started = now();
+        let status = 500;
+        let label = "(other)";
+        try {
+            label = route(pathOf(req.url));
+            if (label === MCP_PATH && inFlight >= MAX_IN_FLIGHT) {
+                status = sendError(res, 503, "Server busy. Try again shortly.", { "retry-after": "5" });
+            }
+            else {
+                inFlight += 1;
+                try {
+                    status = await serve(req, res);
+                }
+                finally {
+                    inFlight -= 1;
+                }
+            }
+        }
+        catch (error) {
+            log(`http: ${error instanceof Error ? error.name : "error"}`);
+            try {
+                if (!res.headersSent)
+                    status = sendError(res, 500, "Internal error.");
+                else
+                    res.destroy();
+            }
+            catch {
+                res.destroy();
+            }
+        }
+        log(`${req.method ?? "GET"} ${label} ${status} ${now() - started}ms`);
+    }
+    return { listener, handler, verifier, types, inFlight: () => inFlight };
+}
+export async function startHttpServer(config, deps = {}) {
+    const app = createHttpApp(config, deps);
+    const server = createNodeServer({ maxHeaderSize: 16 * 1024 }, (req, res) => void app.listener(req, res));
+    server.headersTimeout = 15_000;
+    server.requestTimeout = 30_000;
+    server.keepAliveTimeout = 5_000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(config.port, config.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const host = address.family === "IPv6" ? `[${address.address}]` : address.address;
+    return {
+        server,
+        handler: app.handler,
+        url: `http://${host}:${address.port}${MCP_PATH}`,
+        /** Stops accepting connections, lets in-flight requests finish (up to graceMs), then closes everything. */
+        close: async (graceMs = SHUTDOWN_GRACE_MS) => {
+            const closed = new Promise((resolve) => server.close(() => resolve()));
+            server.closeIdleConnections();
+            const deadline = Date.now() + graceMs;
+            while (app.inFlight() > 0 && Date.now() < deadline)
+                await new Promise((r) => setTimeout(r, 50));
+            await app.handler.close();
+            server.closeAllConnections();
+            await closed;
+        }
+    };
+}

package/dist/index.js

@@ -1,22 +1,79 @@
 #!/usr/bin/env node
 /**
- * Streamlined MCP server (stdio). Configure with environment variables; see README.
- * stdout carries the MCP protocol, so everything else goes to stderr.
+ * Streamlined MCP server.
+ *
+ *   streamlined-mcp                     stdio (default); token from STREAMLINED_TOKEN
+ *   streamlined-mcp --http [--port N] [--host H]
+ *                                       Streamable HTTP on 127.0.0.1:3100; each client sends its own token
+ *
+ * Configure with environment variables; see README. In stdio mode stdout carries the MCP
+ * protocol, so all diagnostics go to stderr.
  */
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { StreamlinedClient } from "./api.js";
-import { ConfigError, loadConfig } from "./config.js";
+import { parseArgs, USAGE } from "./cli.js";
+import { ConfigError, loadConfig, loadHttpConfig } from "./config.js";
+import { startHttpServer } from "./http.js";
 import { createServer, RecordTypeCache, SERVER_NAME, SERVER_VERSION } from "./server.js";
-let config;
-try {
-    config = loadConfig(process.env);
-}
-catch (error) {
+function fail(error) {
     console.error(`${SERVER_NAME}: ${error instanceof ConfigError ? error.message : "invalid configuration"}`);
     process.exit(1);
 }
-const client = new StreamlinedClient(config);
-const types = new RecordTypeCache(client);
-const cfg = config;
-serveStdio(() => createServer(cfg, client, types));
-console.error(`${SERVER_NAME} ${SERVER_VERSION} running on stdio (writes ${cfg.enableWrites ? "enabled" : "disabled"})`);
+// Last line of defence: never let an unexpected error print request data. Log only the error's name.
+process.on("unhandledRejection", (reason) => {
+    console.error(`${SERVER_NAME}: unhandled rejection (${reason instanceof Error ? reason.name : typeof reason})`);
+});
+process.on("uncaughtException", (error) => {
+    console.error(`${SERVER_NAME}: uncaught exception (${error.name}); exiting`);
+    process.exit(1);
+});
+async function main() {
+    let cli;
+    try {
+        cli = parseArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        fail(error);
+    }
+    if (cli.mode === "help") {
+        console.log(USAGE);
+        return;
+    }
+    if (cli.mode === "version") {
+        console.log(SERVER_VERSION);
+        return;
+    }
+    if (cli.mode === "http") {
+        let config;
+        try {
+            config = loadHttpConfig(process.env, { port: cli.port, host: cli.host });
+        }
+        catch (error) {
+            fail(error);
+        }
+        const running = await startHttpServer(config).catch((error) => {
+            console.error(`${SERVER_NAME}: could not listen on ${config.host}:${config.port} (${error.code ?? error.name})`);
+            process.exit(1);
+        });
+        console.error(`${SERVER_NAME} ${SERVER_VERSION} listening on ${running.url} (writes ${config.base.enableWrites ? "enabled" : "disabled"})`);
+        const stop = () => {
+            void running.close().finally(() => process.exit(0));
+        };
+        process.once("SIGTERM", stop);
+        process.once("SIGINT", stop);
+        return;
+    }
+    let config;
+    try {
+        config = loadConfig(process.env);
+    }
+    catch (error) {
+        fail(error);
+    }
+    const client = new StreamlinedClient(config);
+    const types = new RecordTypeCache(client);
+    const cfg = config;
+    serveStdio(() => createServer(cfg, client, types));
+    console.error(`${SERVER_NAME} ${SERVER_VERSION} running on stdio (writes ${cfg.enableWrites ? "enabled" : "disabled"})`);
+}
+void main();

package/dist/server.js

@@ -3,7 +3,7 @@ import * as z from "zod/v4";
 import { ApiError } from "./api.js";
 import { clean, CURSOR_PATTERN, OrderPageSchema, OrderTypesSchema, sanitizeNoteInput, shapeOrder } from "./shape.js";
 export const SERVER_NAME = "streamlined-mcp";
-export const SERVER_VERSION = "0.1.0";
+export const SERVER_VERSION = "0.2.0";
 export const CHARACTER_LIMIT = 30_000;
 export const MAX_PAGE = 25;
 const TYPE_CACHE_MS = 24 * 60 * 60 * 1000;
@@ -22,15 +22,21 @@ export class RecordTypeCache {
     names = new Map();
     loadedAt = 0;
     failedAt = -Infinity;
+    /**
+     * `client` is the default caller. In HTTP mode the cache is shared and each call passes the
+     * caller's own client, so the lookup always runs with a token that is allowed to make it.
+     */
     constructor(client, now = Date.now) {
         this.client = client;
         this.now = now;
     }
-    async get(signal) {
+    async get(signal, caller = this.client) {
         if (this.loadedAt && this.now() - this.loadedAt < TYPE_CACHE_MS)
             return this.names;
+        if (!caller)
+            throw new ApiError(0, "No API client is available to load record types.", "format");
         try {
-            const raw = await this.client.request("GET", "order_types", { signal });
+            const raw = await caller.request("GET", "order_types", { signal });
             const parsed = OrderTypesSchema.safeParse(raw);
             if (!parsed.success)
                 invalid("record type");
@@ -44,11 +50,11 @@ export class RecordTypeCache {
         }
     }
     /** Never let a record-type lookup failure block the order list; after a failure, wait a minute before retrying. */
-    async getOrEmpty(signal) {
+    async getOrEmpty(signal, caller = this.client) {
         if (this.now() - this.failedAt < TYPE_RETRY_MS)
             return this.names;
         try {
-            return await this.get(signal);
+            return await this.get(signal, caller);
         }
         catch {
             return this.names;
@@ -62,7 +68,7 @@ export function createServer(config, client, types) {
         description: "List the record types an order can be for (Medical, Billing, Radiology Images, etc.) with their IDs.",
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
     }, async (ctx) => {
-        const names = await types.get(ctx.mcpReq.signal);
+        const names = await types.get(ctx.mcpReq.signal, client);
         return result({ record_types: [...names].map(([id, name]) => ({ id, name })) });
     });
     server.registerTool("streamlined_list_new_orders", {
@@ -84,7 +90,7 @@ ${UNTRUSTED}`,
         }),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
     }, async ({ limit, cursor }, ctx) => {
-        const names = await types.getOrEmpty(ctx.mcpReq.signal);
+        const names = await types.getOrEmpty(ctx.mcpReq.signal, client);
         // Stay under CHARACTER_LIMIT by asking the API for fewer orders, so next_cursor never skips any
         let pageSize = limit;
         for (;;) {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@zenixsolutions/streamlined-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@zenixsolutions/streamlined-mcp",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "license": "UNLICENSED",
       "dependencies": {
         "@modelcontextprotocol/server": "2.3.1",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zenixsolutions/streamlined-mcp",
-  "version": "0.1.0",
-  "description": "MCP server (stdio) for the Streamlined Record Retrieval order queue: list new orders, record types, and add order notes.",
+  "version": "0.2.0",
+  "description": "MCP server (stdio or Streamable HTTP) for the Streamlined Record Retrieval order queue: list new orders, record types, and add order notes.",
   "type": "module",
   "bin": {
     "streamlined-mcp": "dist/index.js"
@@ -10,6 +10,7 @@
     "dist",
     "!dist/**/*.map",
     "README.md",
+    "CHANGELOG.md",
     "npm-shrinkwrap.json"
   ],
   "scripts": {