iit-mcp-hudu 0.1.0

package/dist/config.js

@@ -0,0 +1,323 @@
+/**
+ * config.ts — the process's entire configuration surface, validated once at boot.
+ *
+ * Every knob is an environment variable. The server refuses to start on an invalid config rather
+ * than failing at the first tool call: a missing credential discovered by a model mid-conversation
+ * is a far worse failure than a container that never came up.
+ *
+ */
+import * as z from 'zod';
+import { getCapability } from 'node-hudu/capabilities';
+import { SEARCH_RESOURCES } from 'node-hudu/mcp';
+import { isWriteEffect } from './policy.js';
+/**
+ * `stdio` is the local path (Claude Code, Claude Desktop, VS Code): one process, one credential,
+ * the process boundary IS the trust boundary. `http` is the remote path (an HTTP MCP client)
+ * and takes the caller's Hudu credential per request.
+ */
+export const TRANSPORTS = ['stdio', 'http'];
+/**
+ * The deployment's authority over `hudu_read / hudu_write / hudu_delete`'s write surface.
+ *
+ * `deny` is the default on purpose: an operator who forgets the variable gets a read-only server,
+ * never an open one. `all` is today's behaviour and has to be typed out deliberately.
+ */
+export const WRITE_POLICIES = ['deny', 'allow_list', 'all'];
+/**
+ * The deployment's authority over reads that can return a plaintext credential.
+ *
+ * `asset_passwords.get` returns `password` and `otp_secret` in plaintext as an ordinary read, so no
+ * write policy touches it — so it needs its own flag that closes both reachable paths in one place. `deny` is the default for the same reason
+ * {@link WRITE_POLICIES} defaults that way: an operator who forgets the variable gets a server that
+ * cannot hand a secret to a model, never one that can.
+ */
+export const SECRET_READ_POLICIES = ['deny', 'allow'];
+/** Parse `HUDU_WRITE_ALLOW` once, here, so every consumer reads the same list. */
+function parseAllowList(raw) {
+    return (raw ?? '')
+        .split(',')
+        .map((key) => key.trim())
+        .filter((key) => key.length > 0);
+}
+/**
+ * Parse `HUDU_SEARCH_RESOURCES` once, here, so every consumer reads the same list.
+ *
+ * `undefined` means the variable is unset: the SDK's full searchable set. A set-but-empty value is
+ * a list, not a default — the caller asked to narrow the surface and named nothing, which is a
+ * config error rather than a server that silently searches nothing.
+ */
+function parseSearchResources(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = raw
+        .split(',')
+        .map((resource) => resource.trim())
+        .filter((resource) => resource.length > 0);
+    // Normalise duplicates: a repeated name would otherwise inflate the effective list's length and
+    // make a membership check against the SDK set read as "full" while a resource is missing.
+    return [...new Set(parsed)];
+}
+/**
+ * Parse `HUDU_ALLOWED_BASE_HOSTS`: unset or blank stays `undefined` (no list); otherwise a
+ * lowercased, de-duplicated list. Validation of the entries happens in the schema refinement.
+ */
+function parseBaseHosts(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const parsed = raw
+        .split(',')
+        .map((host) => host.trim().toLowerCase())
+        .filter((host) => host.length > 0);
+    return [...new Set(parsed)];
+}
+/**
+ * A plausible hostname label (RFC 952/1123): 1-63 characters of lowercase alphanumerics and
+ * hyphens, no leading or trailing hyphen. The `*` wildcard is not a real label: it is legal only
+ * as the first label of a `*.` suffix entry, which the caller strips before delegating here.
+ */
+const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * Whether an entry could match a real hostname, or only a typo.
+ *
+ * The boot-time regex below rejects what is plainly not a hostname (scheme, port, path, a bare
+ * `*`), but its middle `[a-z0-9.-]*` also admits entries that are structurally impossible in any
+ * parsed hostname: an empty label (consecutive or edge dots), a label over 63 characters, or a
+ * label with a leading or trailing hyphen. Such an entry boots cleanly and then sits in an active
+ * list matching nothing — a silent dead entry, so it must fail boot just like a scheme or port
+ * entry (see `baseHostAllowed` for what a live entry matches).
+ */
+function isPlausibleHost(entry) {
+    const body = entry.startsWith('*.') ? entry.slice(2) : entry;
+    if (body === '')
+        return false;
+    return body.split('.').every((label) => HOST_LABEL.test(label));
+}
+const schema = z
+    .object({
+    /**
+     * The Hudu origin. Required under `stdio`; an optional default under `http`.
+     *
+     * On `stdio` the process IS the trust boundary, so the origin comes from the environment like
+     * any other local configuration. Under `http` it is the origin a request falls back to when it
+     * sends no `x-hudu-base-url`; a header, when present, still wins. A blank value
+     * (`HUDU_BASE_URL=`, as a copied `.env.example` leaves it) is normalised to unset first: an
+     * empty string is not an origin, so it must mean "no default" rather than fail boot.
+     */
+    HUDU_BASE_URL: z.preprocess((raw) => (typeof raw === 'string' && raw.trim() === '' ? undefined : raw), z.string().url('HUDU_BASE_URL must be an absolute URL, e.g. https://hudu.example.com').optional()),
+    /**
+     * The server-held Hudu credential — required on `stdio`, an optional default on `http`.
+     *
+     * On `stdio` the process IS the trust boundary, so the key comes from the environment like any
+     * other local credential. On `http` the key normally arrives per request in `x-hudu-api-key`;
+     * when set here it is the default for a request that brings none, and is only ever presented to
+     * the default `HUDU_BASE_URL` (see `resolveHuduClient`). A blank value (`HUDU_API_KEY=`, as a
+     * copied `.env.example` leaves it) is normalised to unset first: an empty string is not a
+     * credential, so it must select the same path an absent variable does rather than fail boot.
+     */
+    HUDU_API_KEY: z.preprocess((raw) => (typeof raw === 'string' && raw.trim() === '' ? undefined : raw), z.string().min(1, 'HUDU_API_KEY must not be empty').optional()),
+    /**
+     * Hosts a caller may name in `x-hudu-base-url` under `http` — the SSRF guard for that header.
+     *
+     * Comma-separated exact hostnames or `*.example.com` subdomain suffixes. When unset alongside
+     * a default `HUDU_BASE_URL`, only that default origin is accepted. When both are unset, any
+     * caller-named origin would be accepted (bring-your-own-origin mode, where the SDK still requires
+     * http/https and no path), so that mode must be opted into with {@link HUDU_ALLOW_ANY_BASE_HOST}.
+     * The default `HUDU_BASE_URL` is always usable and is not checked against an explicit list.
+     * Ignored under `stdio`, where no caller names an origin.
+     */
+    HUDU_ALLOWED_BASE_HOSTS: z.string().optional().transform(parseBaseHosts),
+    /**
+     * Explicit opt-out of the allow-list requirement under `http`. When `true` and no list is set,
+     * any origin a caller names in `x-hudu-base-url` is accepted (the SDK still requires http/https
+     * and no path), so the server will send requests, with the caller's key, to hosts of the
+     * caller's choosing. Only for a listener reachable by trusted callers alone. Defaults to `false`.
+     */
+    HUDU_ALLOW_ANY_BASE_HOST: z.enum(['true', 'false']).default('false').transform((value) => value === 'true'),
+    MCP_TRANSPORT: z.enum(TRANSPORTS).default('stdio'),
+    /**
+     * Pages the body index walks per resource per build (SDK default 250 = 25,000 records).
+     *
+     * Tenant-shaped, so it is a knob rather than a constant. The walk runs articles first and assets
+     * second, and both compete for one 64 MB text budget that evicts least-recently-read text: on a
+     * tenant with tens of thousands of assets the asset text arrives last, so the ARTICLE BODIES are
+     * the first thing evicted — and article bodies are the only reason this index exists (assets
+     * carry no body, and Hudu's own ?search= already covers their titles and fields). Sizing this so
+     * the article walk completes with budget left over is what keeps searches from going body-blind.
+     * A tenant with 3,000+ articles needs about 32 pages.
+     */
+    HUDU_SEARCH_MAX_INDEX_PAGES: z.coerce.number().int().min(1).max(1000).optional(),
+    /**
+     * The resources `hudu_search` may offer and query — the read-edge counterpart to
+     * `HUDU_WRITE_POLICY`.
+     *
+     * The SDK publishes eight searchable resources, but a deployment's Hudu credential can read
+     * fewer (a Hudu API key inherits its user's role). Unset means the SDK's full set; set it to the
+     * resources THIS credential can read so the tool never advertises a guaranteed-empty search and
+     * a model never spends a turn on a resource the key is not allowed to read. Every name is
+     * validated against the SDK's searchable set at boot, so a typo fails the container instead of a
+     * call weeks later. Applies to `hudu_search` only; the dedicated resolve tools are unaffected.
+     */
+    HUDU_SEARCH_RESOURCES: z.string().optional().transform(parseSearchResources),
+    /**
+     * Whether `hudu_read / hudu_write / hudu_delete` may reach a `write` or `destructive` operation at all. Read/`null`
+     * effects are never touched by this policy. Defaults to `deny` — see {@link WRITE_POLICIES}.
+     */
+    HUDU_READ_ONLY: z.enum(['true', 'false']).default('true').transform((value) => value === 'true'),
+    HUDU_WRITE_POLICY: z.enum(WRITE_POLICIES).default('deny'),
+    /**
+     * The operation keys `HUDU_WRITE_POLICY=allow_list` permits. Read only under `allow_list`;
+     * ignored under `deny`/`all`. Exposed as the parsed array so no consumer re-splits the string.
+     */
+    HUDU_WRITE_ALLOW: z.string().optional().transform(parseAllowList),
+    /**
+     * Whether any operation on a credential-bearing resource may run at all — the secret-read
+     * counterpart to `HUDU_WRITE_POLICY`, and independent of it.
+     *
+     * Scoped to the whole `asset_passwords` / `password_folders` surface rather than to the `expand`
+     * flag alone: `asset_passwords.get` returns the secret without `expand`, so gating the flag
+     * would leave the plainest path open. Defaults to `deny` — see {@link SECRET_READ_POLICIES}.
+     * `hudu_search` is unaffected; it redacts those resources already. The curated context reads
+     * always have asset custom-field values masked by the SDK, under every policy.
+     */
+    HUDU_SECRET_READS: z.enum(SECRET_READ_POLICIES).default('deny'),
+    PORT: z.coerce.number().int().positive().max(65535).default(8787),
+    LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+})
+    .superRefine((c, ctx) => {
+    // `stdio` has exactly one origin and one credential (the environment's), so it requires both.
+    // Under `http` both are optional defaults: a caller's `x-hudu-*` headers win, and the defaults
+    // fill in whatever a request leaves out (see `resolveHuduClient` for how they pair).
+    if (c.MCP_TRANSPORT === 'stdio' && c.HUDU_API_KEY === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['HUDU_API_KEY'],
+            message: 'HUDU_API_KEY is required when MCP_TRANSPORT is "stdio"',
+        });
+    }
+    if (c.MCP_TRANSPORT === 'stdio' && c.HUDU_BASE_URL === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['HUDU_BASE_URL'],
+            message: 'HUDU_BASE_URL is required when MCP_TRANSPORT is "stdio"',
+        });
+    }
+    // Fail closed: with no allow-list and no default origin, any caller picks the origin this server
+    // calls (bring-your-own-origin mode). Booting that way has to be typed out, never reached by
+    // forgetting a variable. A set `HUDU_BASE_URL` already restricts callers to that one origin.
+    if (c.MCP_TRANSPORT === 'http' &&
+        c.HUDU_ALLOWED_BASE_HOSTS === undefined &&
+        c.HUDU_BASE_URL === undefined &&
+        !c.HUDU_ALLOW_ANY_BASE_HOST) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['HUDU_ALLOWED_BASE_HOSTS'],
+            message: 'or HUDU_BASE_URL is required when MCP_TRANSPORT is "http": without either, any caller can make this server send requests to a host of their choosing. Set one (e.g. HUDU_BASE_URL=https://hudu.example.com), or set HUDU_ALLOW_ANY_BASE_HOST=true to accept any origin deliberately',
+        });
+    }
+    // A host entry is a bare hostname or `*.` suffix. A scheme, port or path would never match the
+    // parsed hostname, so it would silently refuse every caller; fail boot instead.
+    for (const host of c.HUDU_ALLOWED_BASE_HOSTS ?? []) {
+        if (!/^(\*\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/.test(host)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_ALLOWED_BASE_HOSTS'],
+                message: `"${host}" is not a hostname; use e.g. hudu.example.com or *.example.com (no scheme, port or path)`,
+            });
+        }
+        else if (!isPlausibleHost(host)) {
+            // Passes the shape check but matches no real hostname: an empty label (consecutive dots),
+            // an over-long label, or a label with a leading or trailing hyphen. A dead entry in an
+            // active list is a config error, not a harmless one — name it and fail boot.
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_ALLOWED_BASE_HOSTS'],
+                message: `"${host}" can match no hostname (labels are 1-63 characters, no leading or trailing hyphen, no consecutive dots); use e.g. hudu.example.com or *.example.com`,
+            });
+        }
+    }
+    // The search-resource list is independent of the write policy, so it is validated before the
+    // early return below. A set list must be non-empty and every name must exist in the SDK's
+    // searchable set — a typo fails boot with the variable and the name, not one empty search later.
+    if (c.HUDU_SEARCH_RESOURCES !== undefined) {
+        if (c.HUDU_SEARCH_RESOURCES.length === 0) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_SEARCH_RESOURCES'],
+                message: 'must name at least one searchable resource when set (an empty list would make hudu_search search nothing)',
+            });
+        }
+        else {
+            const searchable = new Set(SEARCH_RESOURCES.searchable.map((r) => r.resource));
+            for (const resource of c.HUDU_SEARCH_RESOURCES) {
+                if (!searchable.has(resource)) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        path: ['HUDU_SEARCH_RESOURCES'],
+                        message: `"${resource}" is not a searchable resource; the SDK searchable set is ${[...searchable].join(', ')}`,
+                    });
+                }
+            }
+        }
+    }
+    // `HUDU_WRITE_ALLOW` is only meaningful under `allow_list`, where a bad list must fail the
+    // container rather than a call six months later. Every problem is reported at once, on the one
+    // error path `loadConfig` already owns.
+    if (c.HUDU_WRITE_POLICY !== 'allow_list')
+        return;
+    if (c.HUDU_WRITE_ALLOW.length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['HUDU_WRITE_ALLOW'],
+            message: 'must list at least one operation key when HUDU_WRITE_POLICY=allow_list (an empty list is a config error, not a silently read-only server)',
+        });
+        return;
+    }
+    for (const key of c.HUDU_WRITE_ALLOW) {
+        const record = getCapability(key);
+        if (record === undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_WRITE_ALLOW'],
+                message: `"${key}" is not a registry operation key; check the spelling against hudu_list_operations`,
+            });
+        }
+        else if (!isWriteEffect(record)) {
+            // An allow-list entry must name a write. Assert the positive rather than negating `read`:
+            // `getCapability` is a prototype-backed lookup, so an inherited name (`constructor`,
+            // `toString`) resolves to a function whose `effect` is `undefined`, not to `undefined`.
+            // Testing `effect === 'read' || effect === null` let those keys fall through as writes.
+            const detail = record.effect === 'read' || record.effect === null
+                ? `"${key}" is a ${record.effect ?? 'non-write'} operation`
+                : `"${key}" is not a write operation`;
+            // It grants nothing either way, so silently accepting it would let the config's apparent
+            // scope differ from its effect. A non-write key in a write allow-list is a misunderstanding
+            // worth failing on.
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_WRITE_ALLOW'],
+                message: `${detail}; HUDU_WRITE_ALLOW is a write allow-list and it would grant nothing`,
+            });
+        }
+    }
+});
+/**
+ * Parse and validate configuration from an environment-shaped record.
+ *
+ * Takes the environment as an argument rather than reading `process.env` directly so the failure
+ * paths are testable without mutating global state.
+ *
+ * @throws {ConfigError} when any variable is missing or malformed. The message lists every problem
+ *   at once — a boot loop that surfaces one missing variable per restart wastes real minutes.
+ */
+export function loadConfig(env = process.env) {
+    const parsed = schema.safeParse(env);
+    if (parsed.success)
+        return parsed.data;
+    const problems = parsed.error.issues.map((i) => `  ${i.path.join('.') || '(config)'}: ${i.message}`);
+    throw new ConfigError(`Invalid configuration:\n${problems.join('\n')}`);
+}
+/** Thrown only by {@link loadConfig}. Never carries a credential value — only variable names. */
+export class ConfigError extends Error {
+    name = 'ConfigError';
+}
+//# sourceMappingURL=config.js.map

package/dist/http.d.ts

@@ -0,0 +1,45 @@
+/**
+ * http.ts — the remote transport: streamable HTTP.
+ *
+ * This is the path remote MCP clients use. Many clients speak streamable HTTP only
+ * (one POST endpoint), so this transport is not optional for that consumer. The per-caller Hudu key
+ * in `X-Hudu-Api-Key` — together with the origin in `X-Hudu-Base-Url` — is what the tools use to
+ * reach Hudu, unless the optional `HUDU_API_KEY` / `HUDU_BASE_URL` defaults fill them in — see
+ * `src/auth.ts` and `resolveHuduClient`.
+ * The transport boundary is the network: the listener must stay on a private, unpublished network.
+ *
+ * A request with no Hudu key is allowed through so the SDK can serve `initialize`/`tools/list` for
+ * a catalog sync; it resolves to a credential-less client that fails closed on any tool call, so
+ * no caller borrows an identity.
+ *
+ */
+import { type IncomingMessage, type ServerResponse, type Server } from 'node:http';
+import type { Config } from './config.js';
+import type { Logger } from './logger.js';
+/** A fetch-shaped MCP handler, as returned by the SDK's `createMcpHandler`. */
+export interface FetchHandler {
+    fetch(request: Request): Promise<Response>;
+}
+/** Liveness path. Answered before authentication so a container healthcheck needs no credential. */
+export declare const HEALTH_PATH = "/healthz";
+/**
+ * Build the fetch-level request handler: health, then MCP.
+ *
+ * Split out from the listener so the request path is testable without binding a port.
+ */
+export declare function createFetchHandler(mcp: FetchHandler): (request: Request) => Promise<Response>;
+/** Node has no fetch-shaped HTTP server; this is the smallest bridge to one. */
+export declare function toWebRequest(req: IncomingMessage, port: number): Promise<Request>;
+/**
+ * Stream a web Response into the Node response — incrementally, never buffered.
+ *
+ * Buffering would deliver nothing to the client until the upstream body closed, hanging any
+ * long-lived or incremental body.
+ */
+export declare function send(res: ServerResponse, response: Response): Promise<void>;
+/**
+ * Bind the listener. `mcp` is supplied by the caller so this module never builds tools itself.
+ *
+ * `exit` is a parameter only so a test can watch a listen failure without killing the test runner.
+ */
+export declare function startHttpServer(config: Config, mcp: FetchHandler, log: Logger, exit?: (code: number) => void): Server;

package/dist/http.js

@@ -0,0 +1,129 @@
+/**
+ * http.ts — the remote transport: streamable HTTP.
+ *
+ * This is the path remote MCP clients use. Many clients speak streamable HTTP only
+ * (one POST endpoint), so this transport is not optional for that consumer. The per-caller Hudu key
+ * in `X-Hudu-Api-Key` — together with the origin in `X-Hudu-Base-Url` — is what the tools use to
+ * reach Hudu, unless the optional `HUDU_API_KEY` / `HUDU_BASE_URL` defaults fill them in — see
+ * `src/auth.ts` and `resolveHuduClient`.
+ * The transport boundary is the network: the listener must stay on a private, unpublished network.
+ *
+ * A request with no Hudu key is allowed through so the SDK can serve `initialize`/`tools/list` for
+ * a catalog sync; it resolves to a credential-less client that fails closed on any tool call, so
+ * no caller borrows an identity.
+ *
+ */
+import { createServer } from 'node:http';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { HUDU_BASE_URL_HEADER, HUDU_KEY_HEADER } from './auth.js';
+/** The headers that carry per-request scope, and so must never be read from a duplicated pair. */
+const CREDENTIAL_HEADERS = new Set([HUDU_KEY_HEADER, HUDU_BASE_URL_HEADER]);
+/** Liveness path. Answered before authentication so a container healthcheck needs no credential. */
+export const HEALTH_PATH = '/healthz';
+/**
+ * Build the fetch-level request handler: health, then MCP.
+ *
+ * Split out from the listener so the request path is testable without binding a port.
+ */
+export function createFetchHandler(mcp) {
+    return async function handle(request) {
+        const url = new URL(request.url);
+        // Liveness only. It must not touch Hudu — see the Dockerfile HEALTHCHECK note.
+        if (url.pathname === HEALTH_PATH) {
+            return Response.json({ status: 'ok' });
+        }
+        // No check for the Hudu key: a request with no key is let through so the SDK can answer
+        // `initialize`/`tools/list`, which never reach Hudu and which clients need to sync the tool
+        // catalog. The per-request factory resolves such a request to a client that holds no credential
+        // and throws before any Hudu request is built, so every tool call fails closed and no caller
+        // borrows an identity.
+        return mcp.fetch(request);
+    };
+}
+/** Node has no fetch-shaped HTTP server; this is the smallest bridge to one. */
+export async function toWebRequest(req, port) {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? `localhost:${port}`}`);
+    const headers = new Headers();
+    // Iterate `headersDistinct`, not `headers`. Node has already joined a duplicated custom header
+    // with ", " in `req.headers`, so by the time a `Headers` bag was built the two values would look
+    // like one well-formed credential and pass a non-blank check. The distinct view keeps them apart
+    // so a credential presented twice can be treated as absent — see `readSingleHeader`.
+    for (const [name, values] of Object.entries(req.headersDistinct)) {
+        if (values === undefined || values.length === 0)
+            continue;
+        if (values.length > 1) {
+            // A credential presented more than once is malformed. Drop it rather than trust one value,
+            // which is the rule `readSingleHeader` applies to an array. Non-credential duplicates keep
+            // Node's combining behaviour.
+            if (CREDENTIAL_HEADERS.has(name))
+                continue;
+            for (const one of values)
+                headers.append(name, one);
+            continue;
+        }
+        // `values.length` is exactly 1 here (empty was skipped, greater-than-one handled above).
+        headers.set(name, values[0]);
+    }
+    if (req.method === 'GET' || req.method === 'HEAD')
+        return new Request(url, { method: req.method, headers });
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(Buffer.from(chunk));
+    return new Request(url, { method: req.method, headers, body: Buffer.concat(chunks).toString('utf8') });
+}
+/**
+ * Stream a web Response into the Node response — incrementally, never buffered.
+ *
+ * Buffering would deliver nothing to the client until the upstream body closed, hanging any
+ * long-lived or incremental body.
+ */
+export async function send(res, response) {
+    res.statusCode = response.status;
+    response.headers.forEach((value, name) => res.setHeader(name, value));
+    if (response.body === null || res.req.method === 'HEAD') {
+        res.end();
+        return;
+    }
+    try {
+        await pipeline(Readable.fromWeb(response.body), res);
+    }
+    catch {
+        // Status and headers are already on the wire; pipeline has destroyed both ends.
+    }
+}
+/**
+ * Bind the listener. `mcp` is supplied by the caller so this module never builds tools itself.
+ *
+ * `exit` is a parameter only so a test can watch a listen failure without killing the test runner.
+ */
+export function startHttpServer(config, mcp, log, exit = process.exit) {
+    const handle = createFetchHandler(mcp);
+    const server = createServer((req, res) => {
+        void toWebRequest(req, config.PORT)
+            .then(handle)
+            .then((response) => send(res, response))
+            .catch((err) => {
+            // Never echo the error to the caller: it can carry internal detail.
+            log.error('request failed', { err: err instanceof Error ? err.message : String(err) });
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.end('internal error');
+            }
+            else {
+                res.destroy();
+            }
+        });
+    });
+    // Without a listener here, a bind failure (EADDRINUSE, EACCES on a privileged port) is an
+    // unhandled 'error' event and Node rethrows it as a raw stack trace. It is the same class of boot
+    // failure as an invalid config: name the problem, exit non-zero, so an orchestrator sees a failed
+    // container rather than a healthy-but-useless one.
+    server.on('error', (err) => {
+        log.error('listen failed', { port: config.PORT, err: err.message });
+        exit(1);
+    });
+    server.listen(config.PORT, () => log.info('listening', { port: config.PORT, transport: 'http' }));
+    return server;
+}
+//# sourceMappingURL=http.js.map

package/dist/lifecycle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * lifecycle.ts — process-level crash, signal and exit logging for the http transport.
+ *
+ * Node's default SIGTERM handling is silent: a killed container leaves zero log lines, and the
+ * only way to learn the process died was to watch the port free (a server that died mid-run left no crash line at all). The http transport installs process-level handlers here so a crash,
+ * a signal or a clean exit always leaves a record in the server log:
+ *
+ * - `uncaughtException` / `unhandledRejection` → a structured error line, then exit 1
+ * - `SIGTERM` / `SIGINT` → a "shutting down" line (signal + exit code), a short grace period for
+ *   in-flight work, a final "server closed" line, then exit 0
+ *
+ * The stdio transport keeps its own handler in main.ts, unchanged: its process life is tied to
+ * the client, and no orchestrator signals it.
+ */
+import type { Logger } from './logger.js';
+/** The slice of `node:http`'s Server that shutdown needs: stop accepting, then force-close sockets. */
+export interface CloseableServer {
+    close(callback?: (err?: Error) => void): void;
+    closeAllConnections?(): void;
+}
+/** How long shutdown waits for in-flight work before force-closing keep-alive sockets. */
+export declare const SHUTDOWN_GRACE_MS = 2000;
+/**
+ * Install the process-level lifecycle handlers for the http transport.
+ *
+ * `exit` is a parameter so a test can watch the code without killing the test runner — the same
+ * pattern as `startHttpServer`'s listen-failure path.
+ */
+export declare function installHttpLifecycle(server: CloseableServer, log: Logger, exit?: (code: number) => void): void;

package/dist/lifecycle.js

@@ -0,0 +1,52 @@
+/** How long shutdown waits for in-flight work before force-closing keep-alive sockets. */
+export const SHUTDOWN_GRACE_MS = 2000;
+/**
+ * Install the process-level lifecycle handlers for the http transport.
+ *
+ * `exit` is a parameter so a test can watch the code without killing the test runner — the same
+ * pattern as `startHttpServer`'s listen-failure path.
+ */
+export function installHttpLifecycle(server, log, exit = process.exit) {
+    // Node's default unhandledRejection handling already terminates — silently. The handler turns
+    // that into a log line and an explicit exit code; uncaughtException gets the same treatment.
+    process.on('uncaughtException', (err) => {
+        log.error('uncaught exception', { err: describe(err) });
+        exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        log.error('unhandled rejection', { err: describe(reason) });
+        exit(1);
+    });
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    // A second signal mid-shutdown is a nudge, not a new shutdown: without the guard the log would
+    // carry two "shutting down" lines and two forced exits.
+    let shuttingDown = false;
+    function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log.info('shutting down', { signal, exitCode: 0 });
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            log.info('server closed', { signal });
+            exit(0);
+        };
+        server.close(() => finish());
+        // MCP clients hold keep-alive connections, which can hold `close` open indefinitely. After
+        // the grace window force-close them and finish no matter what `close` says. `unref` keeps
+        // the timer from pinning the event loop on the fast path.
+        setTimeout(() => {
+            server.closeAllConnections?.();
+            finish();
+        }, SHUTDOWN_GRACE_MS).unref();
+    }
+}
+/** An Error as its stack (or message); anything else stringified. Same shape as main.ts' stdio handler. */
+function describe(value) {
+    return value instanceof Error ? (value.stack ?? value.message) : String(value);
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/logger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * logger.ts — structured JSON logs to stdout, one object per line.
+ *
+ * Deliberately tiny: a container's log collector wants newline-delimited JSON on stdout and nothing
+ * else. No dependency, no transports, no file rotation.
+ *
+ * On the stdio transport, stdout IS the MCP protocol channel — writing logs there would corrupt
+ * every message. Logs go to stderr in that case; see {@link createLogger}.
+ */
+export declare const LEVELS: readonly ["debug", "info", "warn", "error"];
+export type Level = (typeof LEVELS)[number];
+export interface Logger {
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * @param minLevel messages below this are dropped.
+ * @param write sink for one complete line. Defaults to stderr, which is always safe: on the stdio
+ *   transport stdout carries the MCP protocol itself, so a log line written there would be parsed
+ *   as a protocol message and break the session.
+ */
+export declare function createLogger(minLevel?: Level, write?: (line: string) => void): Logger;

package/dist/logger.js

@@ -0,0 +1,26 @@
+/**
+ * logger.ts — structured JSON logs to stdout, one object per line.
+ *
+ * Deliberately tiny: a container's log collector wants newline-delimited JSON on stdout and nothing
+ * else. No dependency, no transports, no file rotation.
+ *
+ * On the stdio transport, stdout IS the MCP protocol channel — writing logs there would corrupt
+ * every message. Logs go to stderr in that case; see {@link createLogger}.
+ */
+export const LEVELS = ['debug', 'info', 'warn', 'error'];
+/**
+ * @param minLevel messages below this are dropped.
+ * @param write sink for one complete line. Defaults to stderr, which is always safe: on the stdio
+ *   transport stdout carries the MCP protocol itself, so a log line written there would be parsed
+ *   as a protocol message and break the session.
+ */
+export function createLogger(minLevel = 'info', write = (l) => process.stderr.write(l + '\n')) {
+    const threshold = LEVELS.indexOf(minLevel);
+    const at = (level) => (msg, fields) => {
+        if (LEVELS.indexOf(level) < threshold)
+            return;
+        write(JSON.stringify({ ts: new Date().toISOString(), level, msg, ...fields }));
+    };
+    return { debug: at('debug'), info: at('info'), warn: at('warn'), error: at('error') };
+}
+//# sourceMappingURL=logger.js.map

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};