@nexusbloom/mcp-server 2.0.0 → 2.0.2

package/README.md

@@ -107,19 +107,4 @@ server that explains itself on each request, not a process that exits or a host
 that concludes the server is broken. A failed catalogue refresh keeps serving the
 last good list rather than emptying it.
 
-## Development
 
-```bash
-npm test              # unit + integration, no network
-npm run test:coverage # with coverage
-npm run lint
-```
-
-The suite has **417 tests** at **100% line coverage** of `src/`. It includes
-end-to-end tests that drive the real server as a child process over stdio, using
-scripted miniature agents that discover, choose, read a schema and execute — the
-same loop a model runs, asserted on whether the *task* succeeded.
-
-No test touches the network: `NEXUSBLOOM_API_URL` is pointed at an unroutable
-`.invalid` host and every HTTP client is injected, so the suite cannot pass
-while production is broken, and cannot fail because production is down.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "MCP server for NexusBloom — agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
   "type": "module",
   "main": "index.js",
@@ -35,6 +35,9 @@
     "test:coverage": "node --test --experimental-test-coverage --import ./test/setup.mjs test/*.test.js",
     "test:watch": "node --test --watch --import ./test/setup.mjs test/*.test.js",
     "test:src-only": "node --test --import ./test/setup.mjs test/config.test.js test/errors.test.js test/manifests.test.js test/discovery.test.js test/client.test.js test/validate.test.js test/render.test.js test/cache.test.js test/handlers.test.js",
+    "shell": "node scripts/mcp-shell.mjs",
+    "shell:mock": "node scripts/mcp-shell.mjs --mock",
+    "mock-api": "node scripts/mock-api.mjs",
     "lint": "node --check index.js && for f in src/*.js; do node --check \"$f\" || exit 1; done"
   }
 }

package/src/client.js

@@ -41,6 +41,15 @@ export class ApiClient {
     // not fire (some fetch polyfills). Whichever rejects first wins; the loser
     // is an unhandled rejection we must not let crash the process.
     this._inFlight = new Set();
+
+    /**
+     * Most recent rate-limit state reported by the API, as
+     * `{remaining, limit, reset}`. Anonymous execution is capped per minute, so
+     * an agent benefits from seeing its own budget rather than discovering it
+     * as a 429.
+     * @type {{remaining: number|null, limit: number|null, reset: string|null}|null}
+     */
+    this.rateLimit = null;
   }
 
   /**
@@ -61,12 +70,13 @@ export class ApiClient {
     const headers = { Accept: "application/json" };
     if (body !== undefined) headers["Content-Type"] = "application/json";
     if (auth && this.config.apiKey) headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    Object.assign(headers, opts.headers || {});
 
     // Own controller so an external signal can cancel too, and so the timer is
     // always cleared — a leaked timer keeps the event loop alive and the MCP
     // server never exits cleanly.
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? this.config.timeoutMs);
     this._inFlight.add(controller);
 
     const onExternalAbort = () => controller.abort();
@@ -106,6 +116,23 @@ export class ApiClient {
   async _decode(res, ctx) {
     const text = await res.text().catch(() => "");
 
+    // Capture quota state before any early return. The API advertises these for
+    // CORS exposure but nothing consumed them, so agents hit 429 blind.
+    // `Number(null)` is 0, so an absent header must be rejected explicitly —
+    // otherwise a client with full quota would be told it has none left.
+    const numHeader = (name) => {
+      const raw = res.headers?.get?.(name);
+      if (raw === null || raw === undefined || raw === "") return null;
+      const n = Number(raw);
+      return Number.isFinite(n) ? n : null;
+    };
+
+    this.rateLimit = {
+      remaining: numHeader("x-ratelimit-remaining"),
+      limit: numHeader("x-ratelimit-limit"),
+      reset: res.headers?.get?.("x-ratelimit-reset") ?? null,
+    };
+
     let parsed = null;
     if (text) {
       try {

package/src/handlers.js

@@ -112,9 +112,13 @@ export function createHandlers({ client, cache, config }) {
     assertValidInput(params, inputSchema, tool.slug);
 
     const startedAt = Date.now();
+    // The run endpoint records usage itself, so attribution rides on a header
+    // rather than a second tracking call — a separate POST would either be a
+    // no-op anonymously or double-count once authenticated.
     const body = await client.request(`/run/${encodeURIComponent(tool.slug)}`, {
       method: "POST",
       body: params,
+      headers: { "X-NexusBloom-Source": "mcp" },
     });
     const durationMs = Date.now() - startedAt;
 
@@ -124,6 +128,7 @@ export function createHandlers({ client, cache, config }) {
       tool: tool.slug,
       execution: "remote",
       durationMs,
+      rateLimit: client.rateLimit ?? null,
     };
   }
 

package/src/preview.js

@@ -0,0 +1,319 @@
+/**
+ * Tier-1 result rendering.
+ *
+ * A tool's output is turned into a visual block by inferring from the *shape of
+ * the value* — never from the slug. Tools that do not exist yet render without
+ * their author doing anything, which is the whole point: the alternative is a
+ * per-slug renderer that dies at tool #31.
+ *
+ * Everything here is a pure function of (value, schema). No I/O, no network,
+ * no slug lookups, so it is trivially testable and deterministic.
+ *
+ * Security note: tool output is untrusted. Once third parties can publish tools,
+ * a "render the SVG" feature is a stored-XSS surface. Rather than attempt to
+ * sanitise arbitrary markup with regex — which gives false confidence — any SVG
+ * containing an active or external construct is REJECTED and falls back to
+ * plain text. Failing closed is cheaper than being wrong here.
+ */
+
+// ─── primitives ─────────────────────────────────────────────────────────────
+
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+// Unanchored: tools emit full CSS declarations such as
+// `background: linear-gradient(90deg, #a, #b);`, not a bare gradient function.
+const GRADIENT = /(?:repeating-)?(?:linear|radial|conic)-gradient\(/i;
+
+/** Escape text for safe interpolation into SVG markup. */
+export function escapeXml(value) {
+  return String(value).replace(/[<>&"']/g, (c) => ({
+    "<": "&lt;",
+    ">": "&gt;",
+    "&": "&amp;",
+    '"': "&quot;",
+    "'": "&apos;",
+  })[c]);
+}
+
+const isHex = (v) => typeof v === "string" && HEX.test(v.trim());
+
+// The subset of CSS colour syntax worth resolving for a preview. Anything else
+// (var(), color-mix, exotic functions) yields no stops, which means no preview
+// rather than a wrong one.
+const STOP = /#[0-9a-f]{3,8}\b|rgba?\(\s*[\d.\s,%]+\)|hsla?\(\s*[\d.\s,%deg]+\)|\b(?:red|blue|green|black|white|gray|grey|orange|purple|pink|yellow|cyan|magenta|teal|navy|olive|maroon|lime|aqua|silver|gold|brown|coral|salmon|khaki|violet|indigo|crimson)\b/gi;
+
+/** Expand `#abc` / `#abcd` to the 6/8-digit form SVG understands. */
+function normalizeHex(hex) {
+  const h = hex.slice(1);
+  if (h.length === 3) return `#${h[0]}${h[0]}${h[1]}${h[1]}${h[2]}${h[2]}`;
+  if (h.length === 4) return `#${h[0]}${h[0]}${h[1]}${h[1]}${h[2]}${h[2]}${h[3]}${h[3]}`;
+  return `#${h.toLowerCase()}`;
+}
+
+/** Colour stops from a CSS gradient string, in order, de-duplicated. */
+function extractStops(css) {
+  const out = [];
+  for (const m of css.matchAll(STOP)) {
+    const raw = m[0];
+    const value = raw.startsWith("#") ? normalizeHex(raw) : raw.toLowerCase();
+    if (!out.includes(value)) out.push(value);
+  }
+  return out.slice(0, 12);
+}
+
+/** Keys that, when their value is a hex colour, indicate a colour payload. */
+const COLOR_KEY = /^(?:colou?rs?|colors?|palette|hex|primary|secondary|accent|background|foreground|border|fill|stroke|shade|tone|from|to|start|end|base_?colou?r)$/i;
+
+/**
+ * Reject SVG that can execute or fetch. Deliberately a denylist of whole
+ * constructs: if any is present we refuse to render rather than strip it.
+ */
+export function isSafeSvg(svg) {
+  const s = String(svg);
+  return !(
+    /<\s*script/i.test(s) ||
+    /<\s*foreignObject/i.test(s) ||
+    /<\s*(iframe|object|embed|link|meta|base)\b/i.test(s) ||
+    /<!DOCTYPE|<!ENTITY/i.test(s) ||
+    /\son[a-z]+\s*=/i.test(s) ||
+    /javascript\s*:/i.test(s) ||
+    /\b(?:href|src|xlink:href)\s*=\s*["']?\s*(?:https?:|\/\/|data:text\/html)/i.test(s)
+  );
+}
+
+const svgWrap = (inner, w, h, label) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" role="img" aria-label="${escapeXml(label)}">${inner}</svg>`;
+
+// ─── detectors ──────────────────────���────────────────────────────────────────
+// Each: test(value, schema) -> boolean, render(value, ctx) -> block | null
+// Order matters: first match wins, so put the most precise rules first.
+
+const DATA_IMAGE = /^data:image\/(png|jpeg|jpg|gif|webp);base64,[A-Za-z0-9+/=\s]+$/i;
+
+const detectors = [
+  {
+    id: "data-image",
+    test: (v) => typeof v === "string" && DATA_IMAGE.test(v.trim()),
+    render: (v) => {
+      const m = DATA_IMAGE.exec(v.trim());
+      const mime = m[1].toLowerCase() === "jpg" ? "jpeg" : m[1].toLowerCase();
+      return {
+        kind: "image",
+        block: { type: "image", data: v.trim().split(",")[1], mimeType: `image/${mime}` },
+      };
+    },
+  },
+
+  {
+    id: "gradient",
+    test: (v) => typeof v === "string" && GRADIENT.test(v.trim()),
+    render: (v) => {
+      const css = v.trim();
+      // Resolve real stops rather than trusting `fill="linear-gradient(...)"`,
+      // which most SVG renderers ignore.
+      const stops = extractStops(css);
+      if (stops.length < 2) return null;
+
+      const type = /radial-gradient\(/i.test(css) ? "radial" : /conic-gradient\(/i.test(css) ? "conic" : "linear";
+      const W = 480;
+      const H = 72;
+      const w = W;
+      const gap = 0;
+      const offset = (i) => (stops.length === 1 ? 0 : (i / (stops.length - 1)) * 100).toFixed(2);
+
+      const stopEls = stops
+        .map((c, i) => `<stop offset="${offset(i)}%" stop-color="${escapeXml(c)}"/>`)
+        .join("");
+
+      // Conic has no SVG equivalent, so fall back to the stop ramp rather than
+      // draw something that lies about the result.
+      const fill =
+        type === "linear"
+          ? `<linearGradient id="g" x1="0" y1="0" x2="1" y2="0">${stopEls}</linearGradient>`
+          : type === "radial"
+            ? `<radialGradient id="g" cx="0.5" cy="0.5" r="0.7">${stopEls}</radialGradient>`
+            : null;
+
+      const inner = fill
+        ? `<defs>${fill}</defs><rect width="${W}" height="${H}" rx="10" fill="url(#g)"/>`
+        : `<rect width="${W}" height="${H}" rx="10" fill="none"/>` +
+          stops
+            .map((c, i) => {
+              const sw = W / stops.length;
+              return `<rect x="${(i * sw).toFixed(2)}" y="0" width="${sw.toFixed(2)}" height="${H}" fill="${escapeXml(c)}"/>`;
+            })
+            .join("");
+
+      return {
+        kind: type === "conic" ? "gradient-conic" : "gradient",
+        block: {
+          type: "resource",
+          resource: {
+            uri: "nexusbloom://preview/gradient.svg",
+            mimeType: "image/svg+xml",
+            text: svgWrap(inner, W, H, `${type} gradient`),
+          },
+        },
+        note: css,
+      };
+    },
+  },
+
+  {
+    id: "svg",
+    test: (v) => typeof v === "string" && /<\s*svg[\s>]/i.test(v),
+    render: (v, ctx) => {
+      const raw = v.trim();
+      if (!isSafeSvg(raw)) {
+        return { kind: "rejected-svg", block: null, note: "SVG contained active or external content; not rendered." };
+      }
+
+      // A square SVG is treated as a code symbol (QR and friends). The padding
+      // is the quiet zone: the spec requires >= 4 modules, and the generators
+      // emit 1, so a faithful render would not scan. 12px satisfies that at the
+      // default 3px module size.
+      const dim = /\bwidth=["'](\d+)["'][^>]*\bheight=["'](\d+)["']/i.exec(raw);
+      const w = dim ? Number(dim[1]) : 0;
+      const h = dim ? Number(dim[2]) : 0;
+      const square = w > 0 && h > 0 && Math.abs(w - h) <= Math.max(w, h) * 0.08;
+
+      if (square) {
+        const pad = 12;
+        const outer = w + pad * 2;
+        return {
+          kind: "code",
+          block: {
+            type: "resource",
+            resource: {
+              uri: `nexusbloom://preview/${ctx.slug}.svg`,
+              mimeType: "image/svg+xml",
+              // Nested svg keeps the original coordinate system intact.
+              text:
+                `<svg xmlns="http://www.w3.org/2000/svg" width="${outer}" height="${outer}" viewBox="0 0 ${outer} ${outer}" role="img" aria-label="${escapeXml(ctx.slug)} output">` +
+                `<rect width="${outer}" height="${outer}" rx="10" fill="#ffffff"/>` +
+                `<g transform="translate(${pad},${pad})">${raw}</g>` +
+                `</svg>`,
+            },
+          },
+        };
+      }
+
+      return {
+        kind: "svg",
+        block: {
+          type: "resource",
+          resource: {
+            uri: `nexusbloom://preview/${ctx.slug}.svg`,
+            mimeType: "image/svg+xml",
+            text: raw,
+          },
+        },
+      };
+    },
+  },
+
+  {
+    id: "colors",
+    test: (v) => {
+      if (Array.isArray(v)) return v.length > 0 && v.length <= 24 && v.every(isHex);
+      if (v && typeof v === "object") {
+        const hexes = Object.entries(v).filter(([, val]) => isHex(val));
+        return hexes.length > 0 && hexes.length <= 24;
+      }
+      return isHex(v);
+    },
+    render: (v) => {
+      const swatches = Array.isArray(v)
+        ? v
+        : v && typeof v === "object"
+          ? Object.values(v).filter(isHex)
+          : [v];
+
+      const cell = 72;
+      const gap = 10;
+      const w = swatches.length * cell + (swatches.length - 1) * gap;
+      const h = cell + 26;
+
+      const rects = swatches
+        .map((c, i) => {
+          const x = i * (cell + gap);
+          return (
+            `<rect x="${x}" y="0" width="${cell}" height="${cell}" rx="9" fill="${escapeXml(c.trim())}"/>` +
+            `<text x="${x + cell / 2}" y="${cell + 18}" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="11" fill="#8b93a7">${escapeXml(c.trim())}</text>`
+          );
+        })
+        .join("");
+
+      return {
+        kind: "colors",
+        block: {
+          type: "resource",
+          resource: {
+            uri: "nexusbloom://preview/swatches.svg",
+            mimeType: "image/svg+xml",
+            text: svgWrap(`<rect width="${w}" height="${h}" fill="none"/>${rects}`, w, h, "Colour swatches"),
+          },
+        },
+      };
+    },
+  },
+
+  {
+    id: "url",
+    test: (v) => typeof v === "string" && /^https?:\/\/\S+$/i.test(v.trim()),
+    render: () => ({ kind: "url", block: null }),
+  },
+];
+
+/**
+ * Infer a visual block from a tool result.
+ *
+ * Returns null when nothing matches — the caller then emits its normal text
+ * block, so this can never produce an empty or broken response.
+ *
+ * @param {unknown} value tool output
+ * @param {{slug?: string}} [ctx]
+ * @returns {{kind: string, block: object|null, note?: string}|null}
+ */
+export function inferPreview(value, ctx = {}) {
+  if (value === null || value === undefined) return null;
+
+  for (const d of detectors) {
+    let hit = false;
+    try {
+      hit = d.test(value);
+    } catch {
+      hit = false;
+    }
+    if (!hit) continue;
+
+    try {
+      const out = d.render(value, ctx);
+      if (out) return out;
+    } catch {
+      /* a broken renderer must never break the response */
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Walk a tool result and return the first renderable preview found.
+ * Results are shallow — the interesting payload is usually one level down.
+ */
+export function previewResult(data, ctx = {}) {
+  if (!data || typeof data !== "object") return inferPreview(data, ctx);
+
+  for (const value of Object.values(data)) {
+    const found = inferPreview(value, ctx);
+    if (found && found.block) return found;
+  }
+
+  // Arrays of hex (a bare palette) as a last resort.
+  if (Array.isArray(data)) {
+    const found = inferPreview(data, ctx);
+    if (found && found.block) return found;
+  }
+
+  return null;
+}

package/src/preview.test.js

@@ -0,0 +1,185 @@
+/**
+ * Tier-1 preview inference.
+ *
+ * Two properties matter more than the individual detectors:
+ *   1. it never looks at the slug, so tools that do not exist yet still render;
+ *   2. it fails closed — anything unsafe or unrecognised returns null and the
+ *      caller emits its normal text block.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  inferPreview,
+  previewResult,
+  isSafeSvg,
+  escapeXml,
+} from "./preview.js";
+
+// ─── colours ────────────────────────────────────────────────────────────────
+
+test("renders an array of hex colours as swatches", () => {
+  const out = inferPreview(["#0b1a31", "#16305c", "#204787"], { slug: "x" });
+  assert.equal(out.kind, "colors");
+  const svg = out.block.resource.text;
+  assert.match(svg, /#0b1a31/);
+  assert.match(svg, /#204787/);
+  assert.match(svg, /<text/);
+});
+
+test("renders 3-digit hex", () => {
+  const out = inferPreview(["#fff", "#000"], { slug: "x" });
+  assert.equal(out.kind, "colors");
+});
+
+test("renders colours pulled from a colour-keyed object", () => {
+  const out = inferPreview({ primary: "#3b82f6", accent: "#ff7a59" }, { slug: "x" });
+  assert.equal(out.kind, "colors");
+  assert.match(out.block.resource.text, /#3b82f6/);
+});
+
+test("ignores an array that is not all hex", () => {
+  assert.equal(inferPreview(["#fff", "not-a-colour"]), null);
+});
+
+test("ignores an oversized swatch list", () => {
+  assert.equal(inferPreview(Array.from({ length: 40 }, () => "#fff")), null);
+});
+
+// ─── gradients ──────────────────────────────────────────────────────────────
+
+test("renders a linear gradient from real stops", () => {
+  const out = inferPreview("linear-gradient(90deg, #3b82f6, #ff7a59)");
+  assert.equal(out.kind, "gradient");
+  const svg = out.block.resource.text;
+  assert.match(svg, /<linearGradient/);
+  assert.match(svg, /#3b82f6/);
+  assert.match(svg, /#ff7a59/);
+});
+
+test("detects a gradient inside a full CSS declaration", () => {
+  // What css-gradient-generator actually returns.
+  const out = inferPreview("background: linear-gradient(90deg, #3b82f6, #ff7a59);");
+  assert.equal(out.kind, "gradient");
+  assert.match(out.block.resource.text, /#3b82f6/);
+});
+
+test("renders a radial gradient as a radialGradient", () => {
+  const out = inferPreview("radial-gradient(circle, #fff, #000)");
+  assert.equal(out.kind, "gradient");
+  assert.match(out.block.resource.text, /<radialGradient/);
+});
+
+test("conic degrades to a stop ramp rather than lying about the shape", () => {
+  const out = inferPreview("conic-gradient(#f00, #0f0, #00f)");
+  assert.equal(out.kind, "gradient-conic");
+  // 3-digit stops are expanded, and drawn as discrete bands not a real conic.
+  assert.match(out.block.resource.text, /#ff0000/);
+  assert.doesNotMatch(out.block.resource.text, /<radialGradient|<linearGradient/);
+});
+
+test("expands 3-digit hex stops", () => {
+  const out = inferPreview("linear-gradient(#abc, #def)");
+  assert.match(out.block.resource.text, /#aabbcc/);
+});
+
+test("a gradient with unresolvable colours yields no preview", () => {
+  assert.equal(inferPreview("linear-gradient(var(--a), var(--b))"), null);
+});
+
+// ─── svg ────────────────────────────────────────────────────────────────────
+
+const safeSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="40" height="20"><rect width="40" height="20" fill="#3b82f6"/></svg>`;
+
+test("renders a safe svg verbatim", () => {
+  const out = inferPreview(safeSvg, { slug: "x" });
+  assert.equal(out.kind, "svg");
+  assert.equal(out.block.resource.text, safeSvg);
+});
+
+test("pads a square svg so a QR code keeps its quiet zone", () => {
+  // 63px at the default 3px module pitch needs >= 4 modules = 12px.
+  const qr = `<svg xmlns="http://www.w3.org/2000/svg" width="63" height="63" viewBox="0 0 63 63"><rect width="63" height="63" fill="#fff"/></svg>`;
+  const out = inferPreview(qr, { slug: "qr-code-generator" });
+  assert.equal(out.kind, "code");
+  assert.match(out.block.resource.text, /width="87" height="87"/);
+  assert.match(out.block.resource.text, /translate\(12,12\)/);
+  assert.match(out.block.resource.text, /fill="#ffffff"/);
+});
+
+test("rejects svg carrying a script", () => {
+  const bad = `<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>`;
+  assert.equal(isSafeSvg(bad), false);
+  const out = inferPreview(bad, { slug: "x" });
+  assert.equal(out.block, null);
+  assert.equal(out.kind, "rejected-svg");
+});
+
+test("rejects svg with an event handler", () => {
+  assert.equal(isSafeSvg(`<svg onload="x()"></svg>`), false);
+  assert.equal(isSafeSvg(`<svg><rect onclick="x()"/></svg>`), false);
+});
+
+test("rejects svg reaching out to the network", () => {
+  assert.equal(isSafeSvg(`<svg><image href="https://evil.example/x.png"/></svg>`), false);
+  assert.equal(isSafeSvg(`<svg><use xlink:href="http://evil/x#y"/></svg>`), false);
+});
+
+test("rejects foreignObject and entity tricks", () => {
+  assert.equal(isSafeSvg(`<svg><foreignObject><body/></foreignObject></svg>`), false);
+  assert.equal(isSafeSvg(`<!DOCTYPE svg [<!ENTITY x SYSTEM "file:///etc/passwd">]><svg/>`), false);
+});
+
+test("accepts a plain svg", () => {
+  assert.equal(isSafeSvg(safeSvg), true);
+});
+
+// ─── data images ────────────────────────────────────────────────────────────
+
+test("renders a raster data uri as a real image block", () => {
+  const out = inferPreview("data:image/png;base64,iVBORw0KGgo=");
+  assert.equal(out.kind, "image");
+  assert.equal(out.block.type, "image");
+  assert.equal(out.block.mimeType, "image/png");
+  assert.equal(out.block.data, "iVBORw0KGgo=");
+});
+
+// ─── falling open ───────────────────────────────────────────────────────────
+
+test("returns null for values with no visual meaning", () => {
+  assert.equal(inferPreview(null), null);
+  assert.equal(inferPreview(undefined), null);
+  assert.equal(inferPreview(42), null);
+  assert.equal(inferPreview("just some text"), null);
+  assert.equal(inferPreview(true), null);
+});
+
+test("a broken detector never throws", () => {
+  const circular = {};
+  circular.self = circular;
+  assert.doesNotThrow(() => inferPreview(circular));
+});
+
+test("finds a preview one level down in a result object", () => {
+  const out = previewResult({ palette: ["#0b1a31", "#3574dd"], count: 5 }, { slug: "color-palette" });
+  assert.equal(out.kind, "colors");
+});
+
+test("returns null when nothing in the result is renderable", () => {
+  assert.equal(previewResult({ count: 5, text: "hello" }, { slug: "x" }), null);
+  assert.equal(previewResult({ error: "nope" }, { slug: "x" }), null);
+});
+
+// ─── escaping ───────────────────────────────────────────────────────────────
+
+test("escapes text interpolated into svg", () => {
+  assert.equal(escapeXml(`<script>&"'`), "&lt;script&gt;&amp;&quot;&apos;");
+});
+
+test("a hex-like label cannot inject markup", () => {
+  // Colours are matched by a strict regex before reaching the renderer, so this
+  // documents that the escape is a second line of defence rather than the gate.
+  const hostile = '" onload="alert(1)';
+  assert.equal(inferPreview([hostile]), null);
+});

package/src/render.js

@@ -17,6 +17,7 @@
 import { describeParameters, groupByCategory } from "./discovery.js";
 import { ErrorCode } from "./errors.js";
 import { normaliseTool } from "./manifests.js";
+import { previewResult } from "./preview.js";
 
 /**
  * Build an MCP response.
@@ -26,7 +27,9 @@ import { normaliseTool } from "./manifests.js";
  * over prose gets an exact payload instead of parsing markdown.
  */
 export function respond(payload) {
-  const content = [{ type: "text", text: payload.text }];
+  // A renderer may supply its own block list (tier-1 preview). When it does we
+  // still append the JSON resource so the model always has the raw payload.
+  const content = Array.isArray(payload.content) ? [...payload.content] : [{ type: "text", text: payload.text }];
   if (payload.data !== undefined) {
     content.push({
       type: "resource",
@@ -116,9 +119,10 @@ export function renderToolList(tools, { total } = {}) {
  */
 export function renderSearchResults(query, tools, catalogueSize, categories = []) {
   if (tools.length === 0) {
-    const categoryHint = categories.length
-      ? `\n• A category name: ${categories.slice(0, 8).join(", ")}`
-      : "";
+    // "uncategorized" is a placeholder, not a category an agent can search by,
+    // so offering it as a hint wastes one of the three suggestions.
+    const useful = [...new Set(categories.filter((c) => c && c !== "uncategorized"))];
+    const categoryHint = useful.length ? `\n• A category name: ${useful.slice(0, 8).join(", ")}` : "";
     return {
       text:
         `# No tools match "${query}"\n\n` +
@@ -282,14 +286,40 @@ function placeholderFor(prop) {
  * re-read it, and deeply indented JSON costs tokens on every turn. Kept at 2
  * spaces because it is far easier to diff and reason about.
  */
-export function renderResult(slug, data, { durationMs, execution = "remote" } = {}) {
+export function renderResult(slug, data, { durationMs, execution = "remote", rateLimit } = {}) {
   const json = safeStringify(data);
   const meta = [`Tool: \`${slug}\``, `Execution: ${execution}`];
   if (typeof durationMs === "number") meta.push(`Duration: ${durationMs}ms`);
 
-  return {
+  // Anonymous execution is capped at 30 requests/minute. Showing the remaining
+  // budget lets an agent pace itself instead of discovering the cap as a 429.
+  if (rateLimit && Number.isFinite(rateLimit.remaining)) {
+    const limit = Number.isFinite(rateLimit.limit) ? `/${rateLimit.limit}` : "";
+    const warns = rateLimit.remaining <= 3 ? " — **pace down, further calls will 429**" : "";
+    meta.push(`Quota: ${rateLimit.remaining}${limit} left${warns}`);
+  }
+
+  // Tier-1 preview. Value-shape inference only — never the slug — so tools
+  // that do not exist yet still render. Returns null when nothing matches, in
+  // which case the response is exactly what it was before.
+  const preview = previewResult(data, { slug });
+
+  // The visual is addressed to the human; the JSON to the model. That split is
+  // what makes rich output affordable: an image in context costs roughly 1.5k
+  // tokens, so showing one unconditionally would make the agent worse.
+  const text = {
+    type: "text",
     text: `# Result: ${slug}\n\n${meta.join(" · ")}\n\n\`\`\`json\n${json}\n\`\`\``,
+    annotations: { audience: preview?.block ? ["assistant"] : ["user", "assistant"] },
+  };
+
+  const content = preview?.block ? [text, preview.block] : [text];
+
+  return {
+    text: text.text,
     data,
+    content,
+    previewKind: preview?.kind ?? null,
   };
 }