@george43g/mcp-kit 0.1.0

package/src/index.ts

@@ -0,0 +1,34 @@
+export type {
+  BuildDispatcherOptions,
+  Dispatch,
+  DispatcherCounters,
+  ToolResult,
+} from "./dispatch.js";
+export { buildDispatcher } from "./dispatch.js";
+export {
+  type WrapInstructionsResult,
+  wrapInstructions,
+  wrapToolError,
+  wrapUntrusted,
+} from "./prompt-injection.js";
+export type {
+  BuildResourcesHandlerOptions,
+  ResourceContent,
+  ResourceHandlers,
+  ResourceListEntry,
+  ResourcesProvider,
+  ResourceTemplate,
+} from "./resources.js";
+export { buildResourcesHandler } from "./resources.js";
+export { sanitize } from "./sanitize.js";
+export type {
+  AnyToolDefinition,
+  ContentBlock,
+  ToolDefinition,
+  ToolRegistry,
+} from "./tool-registry.js";
+export { makeRegistry } from "./tool-registry.js";
+export type { HttpServerHandle, HttpServerOptions } from "./transports/http.js";
+export { startHttpServer } from "./transports/http.js";
+export type { StartStdioOptions } from "./transports/stdio.js";
+export { startStdio } from "./transports/stdio.js";

package/src/prompt-injection.ts

@@ -0,0 +1,56 @@
+/**
+ * Prompt-injection defense helpers.
+ *
+ * Two primitives:
+ *
+ * 1. `wrapUntrusted(text)` — wrap arbitrary content with `<untrusted>...
+ *    </untrusted>` markers. Use whenever a tool returns content sourced
+ *    from an external system (user message, scraped page, etc.). The LLM
+ *    is trained to treat tagged content as data, not instructions.
+ *
+ * 2. `wrapInstructions(text, uuid)` — emit instructions to the LLM that
+ *    only "fire" when the same UUID is present in the user's most recent
+ *    message. Pattern documented in docs/GUARDRAILS_MCP_RESPONSES.md.
+ *
+ *    Tool returns:
+ *      <instructions uuid="d8a3..."> follow steps... </instructions>
+ *
+ *    The LLM, having been trained on this pattern, will refuse to follow
+ *    the embedded instructions unless the user's prior message contains
+ *    the UUID — proving the user genuinely wanted to authorize them.
+ *
+ *    Use sparingly: prefer not to embed instructions in tool responses
+ *    at all. When you must (multi-step workflows, follow-ups), use this
+ *    wrapper.
+ */
+
+import { randomUUID } from "node:crypto";
+
+export function wrapUntrusted(text: string): string {
+  return `<untrusted>\n${text}\n</untrusted>`;
+}
+
+export interface WrapInstructionsResult {
+  text: string;
+  uuid: string;
+}
+
+export function wrapInstructions(
+  text: string,
+  uuid: string = randomUUID(),
+): WrapInstructionsResult {
+  return {
+    text: `<instructions uuid="${uuid}">\n${text}\n</instructions>`,
+    uuid,
+  };
+}
+
+/**
+ * Wrap an actionable error message so the LLM gets a hint without
+ * treating the rest of the response as instructions.
+ */
+export function wrapToolError(toolName: string, message: string, hint?: string): string {
+  let out = `Tool "${toolName}" failed: ${message}`;
+  if (hint) out += `\nHint: ${hint}`;
+  return out;
+}

package/src/resources.ts

@@ -0,0 +1,120 @@
+/**
+ * MCP Resources — the second handler shape MCP clients can talk to.
+ *
+ * Tools run a verb ("call this function"). Resources expose addressable
+ * read-only state ("read this URI"). Hosts can subscribe to resources or
+ * browse them without re-invoking tools — useful for log streams, health
+ * snapshots, document content, etc.
+ *
+ * This kit mirrors the spec's two request shapes:
+ *
+ *   - ListResourcesRequest / ListResourcesResult     (concrete URIs)
+ *   - ListResourceTemplatesRequest / ...Result       (URI templates)
+ *   - ReadResourceRequest / ReadResourceResult       (resolve a URI)
+ *
+ * Consumers wire the returned `{ onList, onListTemplates, onRead }` into
+ * `server.setRequestHandler(...)`. Each callback handles its own error
+ * shape per the SDK contract.
+ *
+ * INVARIANT: like the tools dispatcher, every read goes through a perf
+ * span + structured error wrap. Never throw bare errors; the caller can
+ * inspect `error.message` for the resource URI + hint.
+ */
+
+import { perf } from "@george43g/robustness";
+import { wrapToolError } from "./prompt-injection.js";
+
+/** A directly-addressable resource (URI is the full address). */
+export interface ResourceListEntry {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/** A URI template (e.g. "logs://recent/{n}") clients fill in to read. */
+export interface ResourceTemplate {
+  uriTemplate: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/** Returned by the read callback when the URI is resolved. */
+export interface ResourceContent {
+  uri: string;
+  mimeType: string;
+  /** UTF-8 text body. Mutually exclusive with `blob`. */
+  text?: string;
+  /** base64-encoded binary body. Mutually exclusive with `text`. */
+  blob?: string;
+}
+
+export interface ResourcesProvider {
+  /** Concrete resources to expose; default: none. */
+  list?(): Promise<ResourceListEntry[]> | ResourceListEntry[];
+  /** URI templates to expose; default: none. */
+  listTemplates?(): Promise<ResourceTemplate[]> | ResourceTemplate[];
+  /**
+   * Resolve a URI. Throw if unknown — the wrapper turns it into a
+   * structured error the SDK propagates to the client.
+   */
+  read(uri: string): Promise<ResourceContent> | ResourceContent;
+}
+
+export interface BuildResourcesHandlerOptions {
+  provider: ResourcesProvider;
+  /** Optional engine label surfaced in perf spans. */
+  engineLabel?: string;
+}
+
+export interface ResourceHandlers {
+  /** Wire into `server.setRequestHandler(ListResourcesRequestSchema, ...)`. */
+  onList(): Promise<{ resources: ResourceListEntry[] }>;
+  /** Wire into `server.setRequestHandler(ListResourceTemplatesRequestSchema, ...)`. */
+  onListTemplates(): Promise<{ resourceTemplates: ResourceTemplate[] }>;
+  /** Wire into `server.setRequestHandler(ReadResourceRequestSchema, ...)`. */
+  onRead(request: { params: { uri: string } }): Promise<{ contents: ResourceContent[] }>;
+}
+
+export function buildResourcesHandler(opts: BuildResourcesHandlerOptions): ResourceHandlers {
+  const { provider, engineLabel = "ts" } = opts;
+
+  async function onList() {
+    const span = perf("resources.list");
+    try {
+      const resources = provider.list ? await provider.list() : [];
+      return { resources };
+    } finally {
+      span.end();
+    }
+  }
+
+  async function onListTemplates() {
+    const span = perf("resources.listTemplates");
+    try {
+      const resourceTemplates = provider.listTemplates ? await provider.listTemplates() : [];
+      return { resourceTemplates };
+    } finally {
+      span.end();
+    }
+  }
+
+  async function onRead(request: { params: { uri: string } }) {
+    const uri = request.params.uri;
+    const span = perf(`resources.read[${engineLabel}]`);
+    try {
+      const content = await provider.read(uri);
+      return { contents: [content] };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      // wrapToolError produces a structured shape with an actionable
+      // hint — same pattern the tools dispatcher uses.
+      throw new Error(wrapToolError(`resources/read`, msg, `Unknown resource URI: "${uri}"`));
+    } finally {
+      span.end();
+    }
+  }
+
+  return { onList, onListTemplates, onRead };
+}

package/src/sanitize.ts

@@ -0,0 +1,37 @@
+/**
+ * Sanitize untrusted user text before emitting via MCP or terminal.
+ *
+ * Lifted from imsg-mcp/src/sanitize.ts.
+ *
+ * - Strips ANSI CSI and OSC escape sequences to prevent terminal corruption.
+ * - Replaces NUL bytes and C0 control characters (except \n, \t, \r) with
+ *   U+FFFD (Replacement Character) — keeps text scannable while making the
+ *   substitution visible.
+ * - Truncates the string if it exceeds `maxLength` (default 4096),
+ *   appending a horizontal ellipsis.
+ *
+ * Call this on every user-content surface in tool responses: chat
+ * snippets, search results, anything originally typed by a human or
+ * sourced from a system you don't control.
+ */
+
+const ANSI_REGEX = new RegExp(
+  [
+    "[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)",
+    "(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]))",
+  ].join("|"),
+  "g",
+);
+
+// Matches C0 control characters, excluding \t (0x09), \n (0x0A), and \r (0x0D)
+const CONTROL_CHAR_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1F]/g;
+
+export function sanitize(text: string | null | undefined, maxLength = 4096): string | null {
+  if (text == null) return null;
+  let sanitized = text.replace(ANSI_REGEX, "");
+  sanitized = sanitized.replace(CONTROL_CHAR_REGEX, "�");
+  if (sanitized.length > maxLength) {
+    sanitized = `${sanitized.slice(0, maxLength - 1)}…`;
+  }
+  return sanitized;
+}

package/src/tool-registry.ts

@@ -0,0 +1,111 @@
+/**
+ * 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";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+/**
+ * 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[];
+}
+
+// AnyToolDefinition widens both Zod generic params so the registry can hold
+// tools with narrow input/output schemas under a single uniform array type.
+// Tool authors keep their narrow types at the declaration site; this is the
+// boundary alias used internally.
+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 function makeRegistry(defs: AnyToolDefinition[]): ToolRegistry {
+  const byName = new Map(defs.map((d) => [d.name, d]));
+  return {
+    tools: defs,
+    get(name) {
+      return byName.get(name);
+    },
+    toMcpTools(includeDevOnly = false): Tool[] {
+      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),
+            }) as unknown as Tool,
+        );
+    },
+  };
+}

package/src/transports/http.ts

@@ -0,0 +1,188 @@
+/**
+ * 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";
+
+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;
+}
+
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+function timingSafeEqual(a: string, b: string): boolean {
+  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: http.IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    req.on("data", (chunk: Buffer) => {
+      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 as Error).message}`));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+export async function startHttpServer(opts: HttpServerOptions): Promise<HttpServerHandle> {
+  const log = opts.log ?? ((line: string) => 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 as unknown as Parameters<McpServer["connect"]>[0]);
+
+  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: unknown;
+      if (method === "POST") {
+        body = await readJsonBody(req);
+      }
+
+      await transport.handleRequest(req, res, body);
+    } catch (err) {
+      const e = err as Error;
+      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<void>((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<void>((resolveClose) => httpServer.close(() => resolveClose()));
+      await transport.close();
+    },
+  };
+}

package/src/transports/stdio.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 interface StartStdioOptions {
+  server: Server;
+  entrypoint: string;
+}
+
+export async function startStdio({ server, entrypoint }: StartStdioOptions): Promise<void> {
+  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);
+}