@george43g/mcp-kit 0.1.0

package/dist/tool-registry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Tool registry — types and helpers for declaring MCP tools.
+ *
+ * Convention: each tool ships its own file with three exports:
+ *   - the Zod input schema (for runtime validation)
+ *   - the Zod output schema (for structuredContent shape)
+ *   - the ToolDefinition (registration metadata)
+ *
+ * The registry collects ToolDefinitions and converts them to the SDK's
+ * `Tool[]` shape via `toMcpTools()`.
+ */
+import type { Tool, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { ZodTypeAny, z } from "zod";
+/**
+ * A single MCP content block a tool may emit.
+ *
+ * Deliberately the same two members as `@george43g/cli-kit`'s `ContentBlock`,
+ * and deliberately WITHOUT a catch-all `{ type: string; ... }` member. A
+ * catch-all overlaps `type: "text"`, so every narrowing site needs a cast — and
+ * a future compile error is wanted here: it lands exactly at the render site
+ * where a decision about the new block type has to be made.
+ *
+ * `resource` and `audio` blocks are not modelled because no caller emits them.
+ * Add them when one does, not from a reading of the spec.
+ */
+export type ContentBlock = {
+    type: "text";
+    text: string;
+}
+/** `data` is RAW base64 — no `data:` URI prefix, and not a path. */
+ | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export interface ToolDefinition<TInput extends ZodTypeAny = ZodTypeAny, TOutput extends ZodTypeAny = ZodTypeAny> {
+    /** Snake_case tool name, e.g. "health_check". */
+    name: string;
+    /** One-paragraph description shown to the LLM. */
+    description: string;
+    /** Zod schema for tool arguments. */
+    input: TInput;
+    /** Zod schema for tool result (structuredContent). */
+    output: TOutput;
+    /** MCP annotations: read-only / destructive / idempotent / open-world hints. */
+    annotations: ToolAnnotations;
+    /**
+     * Per-tool timeout in ms. Set to 0 to disable the wrapper for this tool.
+     * Resolved against `MCP_TOOL_TIMEOUT_DEFAULT_MS` if omitted (default 30s).
+     */
+    timeoutMs?: number;
+    /** When true, only register the tool if `MCP_DEV=1`. Used for `get_logs`. */
+    devOnly?: boolean;
+    /** Handler: receives parsed input + AbortSignal, returns structured output. */
+    handler: (input: z.infer<TInput>, signal?: AbortSignal) => Promise<z.infer<TOutput>>;
+    /**
+     * Optional: derive extra content blocks (typically an image) from the result.
+     * The dispatcher emits them AHEAD of the default JSON text block, so a
+     * screenshot tool returns `[image, text]`.
+     *
+     * Runs synchronously at dispatch time and may read a file the handler just
+     * wrote. It must not throw on the happy path; a throw is caught, logged as
+     * `to_content_failed`, and degrades to the text block alone — a tool that
+     * cannot render its picture still returns its answer.
+     *
+     * From browser-tab-mcp, which carried this in a vendored copy of this file.
+     */
+    toContent?: (result: z.infer<TOutput>) => ContentBlock[];
+}
+export type AnyToolDefinition = ToolDefinition<any, any>;
+export interface ToolRegistry {
+    readonly tools: readonly AnyToolDefinition[];
+    get(name: string): AnyToolDefinition | undefined;
+    /** Convert all tools (or just enabled ones) to MCP SDK shape. */
+    toMcpTools(includeDevOnly?: boolean): Tool[];
+}
+export declare function makeRegistry(defs: AnyToolDefinition[]): ToolRegistry;
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGzC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChC,oEAAoE;GAClE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,OAAO,SAAS,UAAU,GAAG,UAAU;IAEvC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,WAAW,EAAE,eAAe,CAAC;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACrF;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;CAC1D;AAMD,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACjD,iEAAiE;IACjE,UAAU,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,CAAC;CAC9C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,YAAY,CA0BpE"}

package/dist/tool-registry.js

@@ -0,0 +1,38 @@
+/**
+ * Tool registry — types and helpers for declaring MCP tools.
+ *
+ * Convention: each tool ships its own file with three exports:
+ *   - the Zod input schema (for runtime validation)
+ *   - the Zod output schema (for structuredContent shape)
+ *   - the ToolDefinition (registration metadata)
+ *
+ * The registry collects ToolDefinitions and converts them to the SDK's
+ * `Tool[]` shape via `toMcpTools()`.
+ */
+import { zodToJsonSchema } from "zod-to-json-schema";
+export function makeRegistry(defs) {
+    const byName = new Map(defs.map((d) => [d.name, d]));
+    return {
+        tools: defs,
+        get(name) {
+            return byName.get(name);
+        },
+        toMcpTools(includeDevOnly = false) {
+            return defs
+                .filter((d) => includeDevOnly || !d.devOnly)
+                .map((d) => 
+            // The SDK Tool type narrows inputSchema/outputSchema to a JSON-
+            // schema with `type: "object"` literal; zodToJsonSchema returns
+            // the broader JsonSchema7Type union. Cast is safe because we
+            // only ever build Zod object schemas as tool I/O.
+            ({
+                name: d.name,
+                description: d.description,
+                annotations: d.annotations,
+                inputSchema: zodToJsonSchema(d.input),
+                outputSchema: zodToJsonSchema(d.output),
+            }));
+        },
+    };
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/tool-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAsErD,MAAM,UAAU,YAAY,CAAC,IAAyB;IACpD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO;QACL,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,IAAI;YACN,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,UAAU,CAAC,cAAc,GAAG,KAAK;YAC/B,OAAO,IAAI;iBACR,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;iBAC3C,GAAG,CACF,CAAC,CAAC,EAAE,EAAE;YACJ,gEAAgE;YAChE,gEAAgE;YAChE,6DAA6D;YAC7D,kDAAkD;YAClD,CAAC;gBACC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC;gBACrC,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC;aACxC,CAAoB,CACxB,CAAC;QACN,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/transports/http.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Streamable HTTP transport.
+ *
+ * Lifted from Gmail-MCP-Server/src/server/http.ts with the bearer token made
+ * caller-supplied: pass `token` directly, or let it read `tokenEnv`
+ * (default: MCP_HTTP_TOKEN). Single-tenant by design — one server process =
+ * one identity. Multi-tenant is a future enhancement; out of scope for the
+ * template.
+ *
+ * - POST /mcp   — MCP protocol (bearer-token required)
+ * - GET  /health — health snapshot (no auth; for reverse-proxy probes;
+ *                 returns 503 if unhealthy)
+ *
+ * TLS is delegated to a reverse proxy. Default bind is 127.0.0.1.
+ *
+ * The bearer-token check is constant-time to prevent timing attacks.
+ */
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+export interface HttpServerOptions {
+    server: McpServer;
+    port: number;
+    bind: string;
+    /**
+     * Bearer token, already resolved by the caller. Takes precedence over
+     * `tokenEnv`.
+     *
+     * This exists so the app can own *where* the secret comes from (env, .env,
+     * OS keychain, an external manager) without this transport growing an
+     * opinion — or a dependency — on secret storage. Omit it and the env-var
+     * lookup below is unchanged.
+     */
+    token?: string;
+    /** Env var name containing the bearer token. Default: "MCP_HTTP_TOKEN". */
+    tokenEnv?: string;
+    getCounters: () => {
+        toolCalls: number;
+        recentErrors: number;
+    };
+    log?: (line: string) => void;
+}
+export interface HttpServerHandle {
+    close(): Promise<void>;
+    port: number;
+    url: string;
+}
+export declare function startHttpServer(opts: HttpServerOptions): Promise<HttpServerHandle>;
+//# sourceMappingURL=http.d.ts.map

package/dist/transports/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,2CAA2C,CAAC;AAGhF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AA0CD,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiGxF"}

package/dist/transports/http.js

@@ -0,0 +1,150 @@
+/**
+ * Streamable HTTP transport.
+ *
+ * Lifted from Gmail-MCP-Server/src/server/http.ts with the bearer token made
+ * caller-supplied: pass `token` directly, or let it read `tokenEnv`
+ * (default: MCP_HTTP_TOKEN). Single-tenant by design — one server process =
+ * one identity. Multi-tenant is a future enhancement; out of scope for the
+ * template.
+ *
+ * - POST /mcp   — MCP protocol (bearer-token required)
+ * - GET  /health — health snapshot (no auth; for reverse-proxy probes;
+ *                 returns 503 if unhealthy)
+ *
+ * TLS is delegated to a reverse proxy. Default bind is 127.0.0.1.
+ *
+ * The bearer-token check is constant-time to prevent timing attacks.
+ */
+import { randomUUID } from "node:crypto";
+import http from "node:http";
+import { formatHealthText, snapshotHealth } from "@george43g/robustness";
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let mismatch = 0;
+    for (let i = 0; i < a.length; i++) {
+        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return mismatch === 0;
+}
+async function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                reject(new Error(`Request body exceeds ${MAX_BODY_BYTES} bytes`));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (chunks.length === 0) {
+                resolve(undefined);
+                return;
+            }
+            const raw = Buffer.concat(chunks).toString("utf8");
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch (err) {
+                reject(new Error(`Invalid JSON body: ${err.message}`));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+export async function startHttpServer(opts) {
+    const log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const tokenEnv = opts.tokenEnv ?? "MCP_HTTP_TOKEN";
+    const expectedToken = opts.token ?? process.env[tokenEnv];
+    if (!expectedToken || expectedToken.trim().length === 0) {
+        throw new Error(`HTTP mode requires a non-empty bearer token: set ${tokenEnv}, or pass one ` +
+            `as \`token\`. Generate one with: openssl rand -hex 32`);
+    }
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    // The SDK's Transport interface declares optional callbacks as required
+    // fields under `exactOptionalPropertyTypes`. Connect via a structural cast.
+    await opts.server.connect(transport);
+    const httpServer = http.createServer(async (req, res) => {
+        try {
+            const url = req.url ?? "/";
+            const method = req.method ?? "GET";
+            if (method === "GET" && (url === "/health" || url.startsWith("/health?"))) {
+                const snap = snapshotHealth(opts.getCounters());
+                res.writeHead(snap.status === "unhealthy" ? 503 : 200, {
+                    "content-type": "text/plain; charset=utf-8",
+                });
+                res.end(formatHealthText(snap));
+                return;
+            }
+            if (!url.startsWith("/mcp")) {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+                res.end("Not found. Use POST /mcp for MCP requests, GET /health for status.");
+                return;
+            }
+            const authHeader = (req.headers.authorization ?? "").trim();
+            const provided = authHeader.startsWith("Bearer ")
+                ? authHeader.slice("Bearer ".length).trim()
+                : "";
+            if (!provided || !timingSafeEqual(provided, expectedToken)) {
+                res.writeHead(401, {
+                    "content-type": "text/plain; charset=utf-8",
+                    "www-authenticate": 'Bearer realm="mcp"',
+                });
+                res.end("Unauthorized. Provide an Authorization: Bearer <token> header.");
+                return;
+            }
+            let body;
+            if (method === "POST") {
+                body = await readJsonBody(req);
+            }
+            await transport.handleRequest(req, res, body);
+        }
+        catch (err) {
+            const e = err;
+            log(`http_error: ${e.message}`);
+            if (!res.headersSent) {
+                res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+                res.end(`Internal error: ${e.message}`);
+            }
+            else {
+                try {
+                    res.end();
+                }
+                catch {
+                    // swallow
+                }
+            }
+        }
+    });
+    await new Promise((resolveListen, rejectListen) => {
+        httpServer.once("error", rejectListen);
+        httpServer.listen(opts.port, opts.bind, () => {
+            httpServer.off("error", rejectListen);
+            resolveListen();
+        });
+    });
+    const addr = httpServer.address();
+    const actualPort = typeof addr === "object" && addr ? addr.port : opts.port;
+    const url = `http://${opts.bind}:${actualPort}`;
+    log(`MCP HTTP listening on ${url}`);
+    log(`  POST ${url}/mcp     — MCP Streamable HTTP (Authorization: Bearer required)`);
+    log(`  GET  ${url}/health  — health snapshot (no auth)`);
+    return {
+        port: actualPort,
+        url,
+        async close() {
+            await new Promise((resolveClose) => httpServer.close(() => resolveClose()));
+            await transport.close();
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/transports/http.js.map

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

package/dist/transports/stdio.d.ts

@@ -0,0 +1,17 @@
+/**
+ * stdio transport bootstrap.
+ *
+ * Wires an MCP `Server` instance to `StdioServerTransport` with the
+ * standard set of lifecycle handlers (shutdown, stdin EOF, orphan watch,
+ * watchdog, heap monitor).
+ *
+ * Critical invariant after this returns: NEVER write to stdout. JSON-RPC
+ * owns it. All logging must go through @george43g/robustness/logger.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export interface StartStdioOptions {
+    server: Server;
+    entrypoint: string;
+}
+export declare function startStdio({ server, entrypoint }: StartStdioOptions): Promise<void>;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/transports/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCzF"}

package/dist/transports/stdio.js

@@ -0,0 +1,53 @@
+/**
+ * stdio transport bootstrap.
+ *
+ * Wires an MCP `Server` instance to `StdioServerTransport` with the
+ * standard set of lifecycle handlers (shutdown, stdin EOF, orphan watch,
+ * watchdog, heap monitor).
+ *
+ * Critical invariant after this returns: NEVER write to stdout. JSON-RPC
+ * owns it. All logging must go through @george43g/robustness/logger.
+ */
+import { enableOrphanWatchdog, enableStdinEofDetection, getShutdownCause, installShutdownHandlers, installWatchdog, logShutdown, logStartup, registerCleanup, startHeapMonitor, } from "@george43g/robustness";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+export async function startStdio({ server, entrypoint }) {
+    installShutdownHandlers();
+    enableStdinEofDetection();
+    enableOrphanWatchdog();
+    installWatchdog();
+    startHeapMonitor();
+    logStartup(entrypoint);
+    // Without this, `logStartup` has no counterpart: every clean exit looks like
+    // a crash to the rule AGENTS.md states ("file without `shutdown` = crash"),
+    // and stdin EOF — the MCP host going away, the most common exit of all —
+    // leaves no trace at all.
+    //
+    // Write-once, two ways, because either alone is insufficient.
+    //
+    // Registered LAST: the controller's `exit` listener sweeps the whole cleanup
+    // registry synchronously, so a cleanup the async pass already ran executes a
+    // SECOND time when a later one hangs and trips the force-exit net. Last is
+    // the position where the sweep is the only invocation.
+    //
+    // Guarded as well, because "last" is not a position you can hold. Anything
+    // registering a cleanup at RUNTIME lands after this one — a lazily armed
+    // watcher in a tool handler, an ink component registering on mount (tui-kit's
+    // FullScreenInk does exactly that). Measured on robustness 0.8.1: marker
+    // registered last, then a runtime registration that hangs → 2 lines unguarded,
+    // 1 guarded.
+    //
+    // NOT done inside the shutdown controller: EQStack and up-bank-mcp already
+    // call `logShutdown` themselves and would get a duplicate line. The transport
+    // is also the component that owns stdout, so the decision belongs here.
+    let markerWritten = false;
+    registerCleanup(() => {
+        if (markerWritten)
+            return;
+        markerWritten = true;
+        logShutdown(getShutdownCause());
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=stdio.js.map

package/dist/transports/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAOjF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,EAAqB;IACxE,uBAAuB,EAAE,CAAC;IAC1B,uBAAuB,EAAE,CAAC;IAC1B,oBAAoB,EAAE,CAAC;IACvB,eAAe,EAAE,CAAC;IAClB,gBAAgB,EAAE,CAAC;IACnB,UAAU,CAAC,UAAU,CAAC,CAAC;IAEvB,6EAA6E;IAC7E,4EAA4E;IAC5E,yEAAyE;IACzE,0BAA0B;IAC1B,EAAE;IACF,8DAA8D;IAC9D,EAAE;IACF,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,uDAAuD;IACvD,EAAE;IACF,2EAA2E;IAC3E,yEAAyE;IACzE,8EAA8E;IAC9E,yEAAyE;IACzE,+EAA+E;IAC/E,aAAa;IACb,EAAE;IACF,2EAA2E;IAC3E,8EAA8E;IAC9E,wEAAwE;IACxE,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,eAAe,CAAC,GAAG,EAAE;QACnB,IAAI,aAAa;YAAE,OAAO;QAC1B,aAAa,GAAG,IAAI,CAAC;QACrB,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@george43g/mcp-kit",
+  "version": "0.1.0",
+  "description": "MCP server building blocks: tool registry types, dispatcher with timeout/perf/abort/error-wrap baked in, stdio + Streamable HTTP transports, sanitize() for user content, UUID-gated prompt-injection helpers.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/george43g/mcp-cli-starter-template.git",
+    "directory": "packages/mcp-kit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/transports/http.d.ts",
+      "import": "./dist/transports/http.js",
+      "default": "./dist/transports/http.js"
+    },
+    "./stdio": {
+      "types": "./dist/transports/stdio.d.ts",
+      "import": "./dist/transports/stdio.js",
+      "default": "./dist/transports/stdio.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pack:check": "pnpm build && npm pack --dry-run --json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist coverage",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@george43g/robustness": ">=0.11.0 <1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.0"
+  },
+  "devDependencies": {
+    "@george43g/tsconfig": "workspace:*",
+    "@george43g/vitest-config": "workspace:*",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "^3.2.7",
+    "semantic-release": "^24.2.0",
+    "semantic-release-monorepo": "^8.0.2",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.7"
+  }
+}

package/src/dispatch.ts

@@ -0,0 +1,172 @@
+/**
+ * Dispatcher — the single place every MCP tool call passes through.
+ *
+ * DISPATCHER INVARIANTS (do not weaken without consulting AGENTS.md):
+ *  1. Every tool runs through withTimeout — declare a per-tool timeout
+ *     in ToolDefinition.timeoutMs or rely on MCP_TOOL_TIMEOUT_DEFAULT_MS.
+ *  2. noteActivity() fires on every dispatch (feeds the idle watchdog).
+ *  3. perf() span around every handler.
+ *  4. Errors wrapped with actionable hint + tool name (never bare error.message).
+ *  5. AbortSignal honored — long-running handlers check signal?.aborted
+ *     between iterations and return early with a structured error.
+ *  6. NEVER console.log after StdioServerTransport.connect() — JSON-RPC owns
+ *     stdout. Log via @george43g/robustness/logger.
+ *  7. Tool responses return { content, structuredContent } per the MCP spec,
+ *     plus a perf footer (engine + dur_ms) in `_meta`.
+ *
+ * The exported `buildDispatcher` returns a function whose shape matches the
+ * SDK's `CallToolRequest` handler.
+ */
+
+import {
+  envNum,
+  error as logError,
+  warn as logWarn,
+  noteActivity,
+  perf,
+  ToolTimeoutError,
+  withTimeout,
+} from "@george43g/robustness";
+import type { ZodError } from "zod";
+import { wrapToolError } from "./prompt-injection.js";
+import type { ContentBlock, ToolRegistry } from "./tool-registry.js";
+
+export interface ToolResult {
+  content: ContentBlock[];
+  structuredContent?: unknown;
+  isError?: boolean;
+  _meta?: Record<string, unknown>;
+}
+
+export interface DispatcherCounters {
+  /** Total successful + failed tool calls. */
+  toolCalls: number;
+  /** Errors in the last 5 minutes (caller maintains via dispatcher hook). */
+  recentErrors: number;
+}
+
+export interface BuildDispatcherOptions {
+  registry: ToolRegistry;
+  /** Called with the ToolTimeoutError / handler-thrown error to bump counters. */
+  onError?: (toolName: string, err: unknown) => void;
+  /** Called per dispatch (success or failure) to bump call counters. */
+  onCall?: (toolName: string) => void;
+  /** Engine label, e.g. "rust" or "ts". Surfaced in `_meta` and dev stats. */
+  engineLabel?: () => string;
+  /**
+   * Whether `devOnly` tools are callable. Evaluated PER DISPATCH, not once at
+   * construction, so flipping the env in a test takes effect immediately.
+   *
+   * Omitted, dev-only tools stay callable — which is what this dispatcher did
+   * before the option existed, so adding it changes nothing until you pass it.
+   *
+   * The gap it closes: `devOnly` was honoured only by `toMcpTools()`, so the
+   * tool was hidden from `tools/list` and still executed if you named it
+   * anyway, and every non-MCP caller (a CLI, a REPL tool list) bypassed the
+   * filter entirely. **Hiding a tool is not disabling it.** Found and fixed in
+   * browser-tab-mcp's vendored copy of this file.
+   */
+  devOnlyEnabled?: () => boolean;
+}
+
+export type Dispatch = (name: string, args: unknown, signal?: AbortSignal) => Promise<ToolResult>;
+
+function defaultTimeoutMs(): number {
+  return envNum("MCP_TOOL_TIMEOUT_DEFAULT_MS", 30_000);
+}
+
+function formatZodError(err: ZodError): string {
+  return err.errors.map((e) => `  - ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
+}
+
+export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
+  const fallback = defaultTimeoutMs();
+  return async (name, args, signal) => {
+    noteActivity();
+    opts.onCall?.(name);
+    const def = opts.registry.get(name);
+
+    // A dev-only tool that is not enabled must be INDISTINGUISHABLE from one
+    // that does not exist. A distinct "disabled" error confirms the tool is
+    // there, which is the thing a gate exists to avoid.
+    const devGated =
+      def?.devOnly === true && opts.devOnlyEnabled !== undefined ? !opts.devOnlyEnabled() : false;
+
+    if (!def || devGated) {
+      opts.onError?.(name, new Error("unknown_tool"));
+      return {
+        content: [
+          {
+            type: "text",
+            text: wrapToolError(name, "Unknown tool name.", "Check the result of tools/list."),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const parsed = def.input.safeParse(args ?? {});
+    if (!parsed.success) {
+      opts.onError?.(name, parsed.error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: wrapToolError(
+              name,
+              "Invalid arguments:",
+              `\n${formatZodError(parsed.error as ZodError)}`,
+            ),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const span = perf(`dispatch.${name}`);
+    const timeoutMs = def.timeoutMs ?? fallback;
+
+    try {
+      const result = await withTimeout(name, () => def.handler(parsed.data, signal), timeoutMs);
+      const dur = span.end({ engine: opts.engineLabel?.() ?? "ts" });
+      const textBlock: ContentBlock = {
+        type: "text",
+        text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
+      };
+      // Media blocks lead, the JSON summary follows: a screenshot tool returns
+      // `[image, text]`. Renderers depend on that order — cli-kit's prints the
+      // image line above the payload — so it is a contract, not a detail.
+      let extra: ContentBlock[] = [];
+      if (def.toContent) {
+        try {
+          extra = def.toContent(result);
+        } catch (err) {
+          logWarn(`to_content_failed: ${name}`, { message: (err as Error)?.message });
+        }
+      }
+      return {
+        content: [...extra, textBlock],
+        structuredContent: result,
+        _meta: {
+          engine: opts.engineLabel?.() ?? "ts",
+          duration_ms: Math.round(dur * 10) / 10,
+        },
+      };
+    } catch (err) {
+      span.end({ error: true });
+      opts.onError?.(name, err);
+      logError(`dispatch_error: ${name}`, {
+        message: (err as Error)?.message,
+        stack: (err as Error)?.stack,
+      });
+      const message =
+        err instanceof ToolTimeoutError
+          ? `Timed out after ${err.timeoutMs}ms. The server has unblocked; the underlying work may still be running.`
+          : ((err as Error)?.message ?? String(err));
+      return {
+        content: [{ type: "text", text: wrapToolError(name, message) }],
+        isError: true,
+      };
+    }
+  };
+}