@george43g/mcp-kit 0.1.0 → 2.0.0

package/README.md

@@ -85,8 +85,9 @@ const dispatch = buildDispatcher({
 - A gated tool's response is **identical to an unknown tool name**. A distinct
   "this tool is disabled" error confirms the tool exists, which is what the gate
   is for.
-- **Omit it and nothing changes** — dev-only tools stay callable, which is what
-  this dispatcher did before the option existed.
+- **Omit it with a `devOnly` tool registered and `buildDispatcher` THROWS**, at
+  construction, naming the offending tools. See *Upgrading to 1.0.0* below.
+- A registry with **no** `devOnly` tools never needs it and is unaffected.
 
 ## Transports
 
@@ -100,6 +101,117 @@ token is caller-supplied or read from `MCP_HTTP_TOKEN`.
 
 ## Untrusted content
 
-`sanitize()` strips control characters and bounds length. `wrapToolError()` and
-the UUID-gated helpers in `prompt-injection.ts` fence tool output so a tool's
-own error text cannot impersonate the host.
+`sanitize()` strips control characters and bounds length (default 4096 — sized
+for a snippet). `wrapToolError()` and the UUID-gated helpers in
+`prompt-injection.ts` fence tool output so a tool's own error text cannot
+impersonate the host.
+
+For **large payloads** — page text, a file, a transcript — use
+`sanitizeContent()` instead:
+
+```ts
+import { sanitizeContent, CONTENT_BUDGET } from "@george43g/mcp-kit";
+
+sanitizeContent(pageText);                 // 1 MiB budget
+sanitizeContent(pageText, 64_000);         // or your own
+```
+
+Three differences from `sanitize()`, each deliberate:
+
+| | `sanitize` | `sanitizeContent` |
+|---|---|---|
+| null/undefined in | returns `null` | returns `""` — no guard at every call site |
+| default budget | 4096 | `CONTENT_BUDGET` = 1 MiB |
+| truncation marker | `…` | `…[truncated]` |
+
+The marker matters more than it looks: a **silently** shortened document is
+indistinguishable from a document that really ended there, and a model reading it
+will answer confidently from the fragment it received.
+
+## Upgrading to 1.0.0
+
+**One breaking change, and it affects you only if you register `devOnly` tools.**
+
+`buildDispatcher` now throws at construction when the registry contains a
+`devOnly` tool and no `devOnlyEnabled` predicate was passed:
+
+```
+buildDispatcher: 1 devOnly tool(s) registered with no devOnlyEnabled predicate: get_logs.
+  A devOnly tool with no predicate would be hidden from tools/list and still callable by name.
+  Fix: pass devOnlyEnabled to buildDispatcher, e.g. `devOnlyEnabled: () => envBool("MCP_DEV", false)`.
+  Or, if these tools are not meant to be gated at all, drop `devOnly` from their definitions.
+```
+
+**Migration is one line** — pass the predicate, as shown in *Dev-only tools*
+above. If you have no `devOnly` tools, there is nothing to do.
+
+### Upgrading to 2.0.0 — declare `@george43g/robustness` yourself
+
+**`robustness` moved from `dependencies` to `peerDependencies`.** If your app
+already depends on `@george43g/robustness` directly — as every known consumer
+does, and as the generated template does — **there is nothing to do**. If it does
+not, add it.
+
+```jsonc
+// your package.json
+"dependencies": {
+  "@george43g/robustness": ">=0.13.0 <1"   // or a caret; any 0.x satisfies the peer
+}
+```
+
+**What this fixes, and it is not cosmetic.** As a plain dependency with a
+*floor*, mcp-kit could resolve its **own second copy** of robustness whenever the
+app's range and mcp-kit's stopped overlapping. The logger keeps prefix and file
+state at module scope, so two copies means **two independent loggers**:
+`setLogFilePrefix` in your app cannot reach the instance mcp-kit's `perf()` spans
+write through, and dispatch spans silently land in the shared `$TMPDIR/mcp/`
+bucket no matter how correctly your app brands itself.
+
+That was live in **1.0.0**, whose floor was `>=0.12.0 <1`: an app on `^0.11.0`
+that bumped mcp-kit alone got exactly this split. **2.0.0 removes the failure
+mode by construction** — a peer is supplied by the consumer, so there is only
+ever one instance. The peer range is deliberately wide (`>=0.11.0 <1`, every
+symbol mcp-kit imports exists at 0.11.0), so no consumer is forced to move.
+
+`tui-kit` has always declared robustness this way; mcp-kit was the outlier.
+
+Verify with the one line that settles it:
+
+```sh
+grep -oE "@george43g/robustness@[0-9.]+" pnpm-lock.yaml | sort -u
+```
+
+One line is correct. Two means something still resolves its own copy.
+
+**The generalisable lesson:** a plain dependency with a *wide* range behaves like
+a peer — right up until the ranges stop overlapping. Two individually safe
+changes (raising a floor, cutting a major) were jointly hazardous. Found by
+`up-bank-mcp`.
+Found by `up-bank-mcp` as range arithmetic over the published manifests.
+**Not yet observed in a resolved tree by anyone** — treat the ordering as cheap
+insurance rather than a reproduction.
+
+**Why a throw and not a flipped default.** Before 1.0.0, omitting the predicate
+left dev-only tools *callable* — hidden from `tools/list` and answering by name.
+Two consumers hit that independently, and one measured a dev-only log reader
+returning a real payload with the dev flag unset.
+
+Defaulting to fail-closed would have fixed the symptom while leaving the real
+question open: does `devOnly` mean *hidden from the listing* or *not callable*? A
+default picks one silently, and the next reader inherits the same ambiguity.
+Throwing makes the ambiguous state **unrepresentable** — you cannot register a
+`devOnly` tool without saying when it is enabled — so `devOnly` genuinely is a
+gate, and the name stops lying without a rename.
+
+The failure is now loud, at startup, with a one-line fix, instead of silent and
+at runtime.
+
+**Also in 1.0.0, both additive:** `sanitizeContent()` / `CONTENT_BUDGET` (above),
+and `dispatch_error` log records now have the home-directory prefix replaced with
+`~` and are length-bounded. Stack frames always carry absolute paths, which
+contain the username, and the redactor in `@george43g/robustness` has no
+filesystem-path rule at any version — so an unmodified stack sent to a log
+collector carried an identifier nothing downstream would strip. This removes that
+one category; it does **not** make `err.message` safe. A throw that interpolates a
+URL or an account number still logs it verbatim, and no kit-side guard can know
+which of those your errors carry. Check your own throws.

package/dist/dispatch.d.ts

@@ -42,8 +42,28 @@ export interface BuildDispatcherOptions {
      * 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.
+     * REQUIRED IF — AND ONLY IF — the registry contains a `devOnly` tool. Omit it
+     * with such a tool registered and `buildDispatcher` **throws**, naming the
+     * offending tools. A registry with no `devOnly` tools never needs it and is
+     * completely unaffected.
+     *
+     * Why a throw rather than a default, either way (1.0.0):
+     *
+     * Until 1.0.0 this was optional and omitting it left dev-only tools
+     * **callable** — the gate did nothing unless the caller remembered it, which
+     * is the failure mode `devOnly` exists to prevent. Two consumers independently
+     * hit it, and one measured a dev-only log reader answering with a real payload
+     * in a repo fronting a bank account.
+     *
+     * Flipping the default to fail-closed was the obvious fix and is NOT what this
+     * does, because it leaves the real question unanswered: does `devOnly` mean
+     * "hidden from the listing" or "not callable"? A default picks one silently.
+     * Throwing makes the ambiguous state **unrepresentable** — you cannot have a
+     * `devOnly` tool without saying when it is enabled — so `devOnly` genuinely is
+     * a gate and the name stops lying, with no rename needed.
+     *
+     * The failure is loud, at construction, with a one-line fix, instead of silent
+     * and at runtime.
      *
      * 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

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAErE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAUlG,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,QAAQ,CA0FtE"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgCrE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAUlG,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,QAAQ,CA6GtE"}

package/dist/dispatch.js

@@ -17,8 +17,40 @@
  * The exported `buildDispatcher` returns a function whose shape matches the
  * SDK's `CallToolRequest` handler.
  */
+import { homedir } from "node:os";
 import { envNum, error as logError, warn as logWarn, noteActivity, perf, ToolTimeoutError, withTimeout, } from "@george43g/robustness";
 import { wrapToolError } from "./prompt-injection.js";
+import { sanitize } from "./sanitize.js";
+/**
+ * Replace the absolute home-directory prefix with `~` in anything headed for a
+ * log sink.
+ *
+ * WHY THIS EXISTS, and why redaction does not already cover it.
+ *
+ * `err.stack` contains absolute paths ALWAYS — every frame carries one — and on
+ * a normal machine every one of them starts with the user's home directory,
+ * which contains their username. `@george43g/robustness`'s redactor has exactly
+ * three rules at every published version: phone numbers, secret-shaped tokens,
+ * and emails (opt-in, default off). **There is no filesystem-path rule, no URL
+ * rule, and no free-text rule.** So an unmodified stack shipped to a log
+ * collector carries an identifier that nothing downstream will strip.
+ *
+ * This is cheap and lossless for debugging: `~/repos/foo/src/bar.ts:12` locates
+ * the frame exactly as well as the absolute path did.
+ *
+ * SCOPE, stated so nobody reads more into it than is there: this removes ONE
+ * category — the home prefix. It does not make `err.message` safe. A throw that
+ * interpolates a URL, an account number or a row of user data still logs it
+ * verbatim, and no kit-side guard can know which of those a consumer's errors
+ * carry. That check belongs in each consumer: assert your own throws do not
+ * interpolate sensitive values.
+ */
+function scrubHome(text) {
+    if (text === null)
+        return undefined;
+    const home = homedir();
+    return home.length > 1 ? text.split(home).join("~") : text;
+}
 function defaultTimeoutMs() {
     return envNum("MCP_TOOL_TIMEOUT_DEFAULT_MS", 30_000);
 }
@@ -26,6 +58,19 @@ function formatZodError(err) {
     return err.errors.map((e) => `  - ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
 }
 export function buildDispatcher(opts) {
+    // Make the ambiguous state unrepresentable, at construction, before a single
+    // request can be served. See `devOnlyEnabled` above for why this is a throw
+    // rather than a default in either direction.
+    if (opts.devOnlyEnabled === undefined) {
+        const ungated = opts.registry.tools.filter((d) => d.devOnly === true).map((d) => d.name);
+        if (ungated.length > 0) {
+            throw new Error(`buildDispatcher: ${ungated.length} devOnly tool(s) registered with no devOnlyEnabled predicate: ` +
+                `${ungated.join(", ")}.\n` +
+                "  A devOnly tool with no predicate would be hidden from tools/list and still callable by name.\n" +
+                '  Fix: pass devOnlyEnabled to buildDispatcher, e.g. `devOnlyEnabled: () => envBool("MCP_DEV", false)`.\n' +
+                "  Or, if these tools are not meant to be gated at all, drop `devOnly` from their definitions.");
+        }
+    }
     const fallback = defaultTimeoutMs();
     return async (name, args, signal) => {
         noteActivity();
@@ -34,7 +79,11 @@ export function buildDispatcher(opts) {
         // 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;
+        // Fail CLOSED in the residual case. The construction check above means a
+        // devOnly tool always has a predicate — unless a registry gained one after
+        // construction, which the readonly type discourages but does not prevent.
+        // If that ever happens the tool is gated, not exposed.
+        const devGated = def?.devOnly === true && !(opts.devOnlyEnabled?.() ?? false);
         if (!def || devGated) {
             opts.onError?.(name, new Error("unknown_tool"));
             return {
@@ -94,8 +143,8 @@ export function buildDispatcher(opts) {
             span.end({ error: true });
             opts.onError?.(name, err);
             logError(`dispatch_error: ${name}`, {
-                message: err?.message,
-                stack: err?.stack,
+                message: scrubHome(sanitize(err?.message, 1024)),
+                stack: scrubHome(sanitize(err?.stack, 4096)),
             });
             const message = err instanceof ToolTimeoutError
                 ? `Timed out after ${err.timeoutMs}ms. The server has unblocked; the underlying work may still be running.`

package/dist/dispatch.js.map

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

package/dist/index.d.ts

@@ -3,7 +3,7 @@ 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 { CONTENT_BUDGET, sanitize, sanitizeContent } 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";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,4BAA4B,EAC5B,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,4BAA4B,EAC5B,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 export { buildDispatcher } from "./dispatch.js";
 export { wrapInstructions, wrapToolError, wrapUntrusted, } from "./prompt-injection.js";
 export { buildResourcesHandler } from "./resources.js";
-export { sanitize } from "./sanitize.js";
+export { CONTENT_BUDGET, sanitize, sanitizeContent } from "./sanitize.js";
 export { makeRegistry } from "./tool-registry.js";
 export { startHttpServer } from "./transports/http.js";
 export { startStdio } from "./transports/stdio.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAEL,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAEL,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAO1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/sanitize.d.ts

@@ -15,4 +15,34 @@
  * sourced from a system you don't control.
  */
 export declare function sanitize(text: string | null | undefined, maxLength?: number): string | null;
+/**
+ * Default budget for {@link sanitizeContent} — 1 MiB.
+ *
+ * Sized for *documents*, not snippets: page text, file contents, a transcript.
+ * `sanitize`'s 4096 default is right for a chat line and destroys anything
+ * larger, which is why a second entry point exists rather than a different
+ * default on the same one.
+ */
+export declare const CONTENT_BUDGET = 1048576;
+/**
+ * Sanitize a large untrusted CONTENT payload — page text, a file, a transcript.
+ *
+ * Same escape/control-character handling as {@link sanitize}. Three deliberate
+ * differences, each of which is why this could not just be `sanitize(x, 1e6)`:
+ *
+ * 1. **Never returns `null`.** `null`/`undefined` in yields `""` out, so callers
+ *    can concatenate and measure without a guard at every site. `sanitize`
+ *    returning `null` is right for "was there a message?"; it is wrong for
+ *    "render this body".
+ * 2. **A 1 MiB budget** rather than 4096 — see {@link CONTENT_BUDGET}.
+ * 3. **Truncation is ANNOUNCED**, with `…[truncated]` rather than a bare `…`.
+ *    A silently shortened document is indistinguishable from a document that
+ *    really ended there, and a model reading it will confidently answer from the
+ *    part it received. The marker is the whole point.
+ *
+ * Lifted from browser-tab-mcp, which carried it in a vendored copy of this
+ * package and asked for it upstream when the vendoring ended. Semantics are
+ * theirs and were deliberately not "improved" during the lift.
+ */
+export declare function sanitizeContent(text: string | null | undefined, maxLength?: number): string;
 //# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,SAAS,SAAO,GAAG,MAAM,GAAG,IAAI,CAQzF"}
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,SAAS,SAAO,GAAG,MAAM,GAAG,IAAI,CAQzF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,SAAS,SAAiB,GACzB,MAAM,CAQR"}

package/dist/sanitize.js

@@ -30,4 +30,43 @@ export function sanitize(text, maxLength = 4096) {
     }
     return sanitized;
 }
+/**
+ * Default budget for {@link sanitizeContent} — 1 MiB.
+ *
+ * Sized for *documents*, not snippets: page text, file contents, a transcript.
+ * `sanitize`'s 4096 default is right for a chat line and destroys anything
+ * larger, which is why a second entry point exists rather than a different
+ * default on the same one.
+ */
+export const CONTENT_BUDGET = 1_048_576;
+/**
+ * Sanitize a large untrusted CONTENT payload — page text, a file, a transcript.
+ *
+ * Same escape/control-character handling as {@link sanitize}. Three deliberate
+ * differences, each of which is why this could not just be `sanitize(x, 1e6)`:
+ *
+ * 1. **Never returns `null`.** `null`/`undefined` in yields `""` out, so callers
+ *    can concatenate and measure without a guard at every site. `sanitize`
+ *    returning `null` is right for "was there a message?"; it is wrong for
+ *    "render this body".
+ * 2. **A 1 MiB budget** rather than 4096 — see {@link CONTENT_BUDGET}.
+ * 3. **Truncation is ANNOUNCED**, with `…[truncated]` rather than a bare `…`.
+ *    A silently shortened document is indistinguishable from a document that
+ *    really ended there, and a model reading it will confidently answer from the
+ *    part it received. The marker is the whole point.
+ *
+ * Lifted from browser-tab-mcp, which carried it in a vendored copy of this
+ * package and asked for it upstream when the vendoring ended. Semantics are
+ * theirs and were deliberately not "improved" during the lift.
+ */
+export function sanitizeContent(text, maxLength = CONTENT_BUDGET) {
+    if (text == null)
+        return "";
+    let sanitized = text.replace(ANSI_REGEX, "");
+    sanitized = sanitized.replace(CONTROL_CHAR_REGEX, "�");
+    if (sanitized.length > maxLength) {
+        sanitized = `${sanitized.slice(0, maxLength)}…[truncated]`;
+    }
+    return sanitized;
+}
 //# sourceMappingURL=sanitize.js.map

package/dist/sanitize.js.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,UAAU,GAAG,IAAI,MAAM,CAC3B;IACE,8HAA8H;IAC9H,0DAA0D;CAC3D,CAAC,IAAI,CAAC,GAAG,CAAC,EACX,GAAG,CACJ,CAAC;AAEF,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;AAE3D,MAAM,UAAU,QAAQ,CAAC,IAA+B,EAAE,SAAS,GAAG,IAAI;IACxE,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC7C,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACvD,IAAI,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QACjC,SAAS,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC;IACtD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,UAAU,GAAG,IAAI,MAAM,CAC3B;IACE,8HAA8H;IAC9H,0DAA0D;CAC3D,CAAC,IAAI,CAAC,GAAG,CAAC,EACX,GAAG,CACJ,CAAC;AAEF,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;AAE3D,MAAM,UAAU,QAAQ,CAAC,IAA+B,EAAE,SAAS,GAAG,IAAI;IACxE,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC7C,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACvD,IAAI,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QACjC,SAAS,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC;IACtD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC;AAExC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA+B,EAC/B,SAAS,GAAG,cAAc;IAE1B,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC5B,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC7C,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACvD,IAAI,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QACjC,SAAS,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,cAAc,CAAC;IAC7D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@george43g/mcp-kit",
-  "version": "0.1.0",
+  "version": "2.0.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",
@@ -51,12 +51,12 @@
     "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/robustness": "workspace:*",
     "@george43g/tsconfig": "workspace:*",
     "@george43g/vitest-config": "workspace:*",
     "@semantic-release/changelog": "^6.0.3",
@@ -68,5 +68,8 @@
     "semantic-release-monorepo": "^8.0.2",
     "typescript": "^5.7.0",
     "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "@george43g/robustness": ">=0.11.0 <1"
   }
 }

package/src/dispatch.ts

@@ -18,6 +18,7 @@
  * SDK's `CallToolRequest` handler.
  */
 
+import { homedir } from "node:os";
 import {
   envNum,
   error as logError,
@@ -29,8 +30,39 @@ import {
 } from "@george43g/robustness";
 import type { ZodError } from "zod";
 import { wrapToolError } from "./prompt-injection.js";
+import { sanitize } from "./sanitize.js";
 import type { ContentBlock, ToolRegistry } from "./tool-registry.js";
 
+/**
+ * Replace the absolute home-directory prefix with `~` in anything headed for a
+ * log sink.
+ *
+ * WHY THIS EXISTS, and why redaction does not already cover it.
+ *
+ * `err.stack` contains absolute paths ALWAYS — every frame carries one — and on
+ * a normal machine every one of them starts with the user's home directory,
+ * which contains their username. `@george43g/robustness`'s redactor has exactly
+ * three rules at every published version: phone numbers, secret-shaped tokens,
+ * and emails (opt-in, default off). **There is no filesystem-path rule, no URL
+ * rule, and no free-text rule.** So an unmodified stack shipped to a log
+ * collector carries an identifier that nothing downstream will strip.
+ *
+ * This is cheap and lossless for debugging: `~/repos/foo/src/bar.ts:12` locates
+ * the frame exactly as well as the absolute path did.
+ *
+ * SCOPE, stated so nobody reads more into it than is there: this removes ONE
+ * category — the home prefix. It does not make `err.message` safe. A throw that
+ * interpolates a URL, an account number or a row of user data still logs it
+ * verbatim, and no kit-side guard can know which of those a consumer's errors
+ * carry. That check belongs in each consumer: assert your own throws do not
+ * interpolate sensitive values.
+ */
+function scrubHome(text: string | null): string | undefined {
+  if (text === null) return undefined;
+  const home = homedir();
+  return home.length > 1 ? text.split(home).join("~") : text;
+}
+
 export interface ToolResult {
   content: ContentBlock[];
   structuredContent?: unknown;
@@ -57,8 +89,28 @@ export interface BuildDispatcherOptions {
    * 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.
+   * REQUIRED IF — AND ONLY IF — the registry contains a `devOnly` tool. Omit it
+   * with such a tool registered and `buildDispatcher` **throws**, naming the
+   * offending tools. A registry with no `devOnly` tools never needs it and is
+   * completely unaffected.
+   *
+   * Why a throw rather than a default, either way (1.0.0):
+   *
+   * Until 1.0.0 this was optional and omitting it left dev-only tools
+   * **callable** — the gate did nothing unless the caller remembered it, which
+   * is the failure mode `devOnly` exists to prevent. Two consumers independently
+   * hit it, and one measured a dev-only log reader answering with a real payload
+   * in a repo fronting a bank account.
+   *
+   * Flipping the default to fail-closed was the obvious fix and is NOT what this
+   * does, because it leaves the real question unanswered: does `devOnly` mean
+   * "hidden from the listing" or "not callable"? A default picks one silently.
+   * Throwing makes the ambiguous state **unrepresentable** — you cannot have a
+   * `devOnly` tool without saying when it is enabled — so `devOnly` genuinely is
+   * a gate and the name stops lying, with no rename needed.
+   *
+   * The failure is loud, at construction, with a one-line fix, instead of silent
+   * and at runtime.
    *
    * 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
@@ -80,6 +132,22 @@ function formatZodError(err: ZodError): string {
 }
 
 export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
+  // Make the ambiguous state unrepresentable, at construction, before a single
+  // request can be served. See `devOnlyEnabled` above for why this is a throw
+  // rather than a default in either direction.
+  if (opts.devOnlyEnabled === undefined) {
+    const ungated = opts.registry.tools.filter((d) => d.devOnly === true).map((d) => d.name);
+    if (ungated.length > 0) {
+      throw new Error(
+        `buildDispatcher: ${ungated.length} devOnly tool(s) registered with no devOnlyEnabled predicate: ` +
+          `${ungated.join(", ")}.\n` +
+          "  A devOnly tool with no predicate would be hidden from tools/list and still callable by name.\n" +
+          '  Fix: pass devOnlyEnabled to buildDispatcher, e.g. `devOnlyEnabled: () => envBool("MCP_DEV", false)`.\n' +
+          "  Or, if these tools are not meant to be gated at all, drop `devOnly` from their definitions.",
+      );
+    }
+  }
+
   const fallback = defaultTimeoutMs();
   return async (name, args, signal) => {
     noteActivity();
@@ -89,8 +157,11 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
     // 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;
+    // Fail CLOSED in the residual case. The construction check above means a
+    // devOnly tool always has a predicate — unless a registry gained one after
+    // construction, which the readonly type discourages but does not prevent.
+    // If that ever happens the tool is gated, not exposed.
+    const devGated = def?.devOnly === true && !(opts.devOnlyEnabled?.() ?? false);
 
     if (!def || devGated) {
       opts.onError?.(name, new Error("unknown_tool"));
@@ -156,8 +227,8 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
       span.end({ error: true });
       opts.onError?.(name, err);
       logError(`dispatch_error: ${name}`, {
-        message: (err as Error)?.message,
-        stack: (err as Error)?.stack,
+        message: scrubHome(sanitize((err as Error)?.message, 1024)),
+        stack: scrubHome(sanitize((err as Error)?.stack, 4096)),
       });
       const message =
         err instanceof ToolTimeoutError

package/src/index.ts

@@ -20,7 +20,7 @@ export type {
   ResourceTemplate,
 } from "./resources.js";
 export { buildResourcesHandler } from "./resources.js";
-export { sanitize } from "./sanitize.js";
+export { CONTENT_BUDGET, sanitize, sanitizeContent } from "./sanitize.js";
 export type {
   AnyToolDefinition,
   ContentBlock,

package/src/sanitize.ts

@@ -35,3 +35,46 @@ export function sanitize(text: string | null | undefined, maxLength = 4096): str
   }
   return sanitized;
 }
+
+/**
+ * Default budget for {@link sanitizeContent} — 1 MiB.
+ *
+ * Sized for *documents*, not snippets: page text, file contents, a transcript.
+ * `sanitize`'s 4096 default is right for a chat line and destroys anything
+ * larger, which is why a second entry point exists rather than a different
+ * default on the same one.
+ */
+export const CONTENT_BUDGET = 1_048_576;
+
+/**
+ * Sanitize a large untrusted CONTENT payload — page text, a file, a transcript.
+ *
+ * Same escape/control-character handling as {@link sanitize}. Three deliberate
+ * differences, each of which is why this could not just be `sanitize(x, 1e6)`:
+ *
+ * 1. **Never returns `null`.** `null`/`undefined` in yields `""` out, so callers
+ *    can concatenate and measure without a guard at every site. `sanitize`
+ *    returning `null` is right for "was there a message?"; it is wrong for
+ *    "render this body".
+ * 2. **A 1 MiB budget** rather than 4096 — see {@link CONTENT_BUDGET}.
+ * 3. **Truncation is ANNOUNCED**, with `…[truncated]` rather than a bare `…`.
+ *    A silently shortened document is indistinguishable from a document that
+ *    really ended there, and a model reading it will confidently answer from the
+ *    part it received. The marker is the whole point.
+ *
+ * Lifted from browser-tab-mcp, which carried it in a vendored copy of this
+ * package and asked for it upstream when the vendoring ended. Semantics are
+ * theirs and were deliberately not "improved" during the lift.
+ */
+export function sanitizeContent(
+  text: string | null | undefined,
+  maxLength = CONTENT_BUDGET,
+): string {
+  if (text == null) return "";
+  let sanitized = text.replace(ANSI_REGEX, "");
+  sanitized = sanitized.replace(CONTROL_CHAR_REGEX, "�");
+  if (sanitized.length > maxLength) {
+    sanitized = `${sanitized.slice(0, maxLength)}…[truncated]`;
+  }
+  return sanitized;
+}