@nexusbloom/mcp-server 2.0.0 → 2.1.0

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/progress.js

@@ -0,0 +1,88 @@
+/**
+ * Progress notifications.
+ *
+ * A batch of five tools can take fifteen seconds, and a host that shows nothing
+ * for fifteen seconds is a host the user interrupts. The protocol already has a
+ * channel for this — `notifications/progress`, keyed by the `progressToken` the
+ * client sent in `_meta` — but it is opt-in on both sides, so every detail here
+ * is about degrading quietly when it is absent.
+ *
+ * The rules that matter:
+ *
+ * - **No token, no notifications.** A client that does not send one has not asked
+ *   for progress, and unsolicited notifications are noise at best and a protocol
+ *   violation at worst.
+ * - **Progress is monotonic.** The spec requires it to increase; a host that
+ *   renders a percentage bar will go backwards if a report repeats a value.
+ * - **A failed notification never fails the call.** The report is diagnostics
+ *   about work already done. Losing one must not lose the result.
+ *
+ * No SDK import: the notification is a plain object, and the suite validates it
+ * against the SDK's own schema in test/progress.test.js rather than coupling
+ * this file to a transport.
+ */
+
+/**
+ * Build a progress reporter bound to one in-flight request.
+ *
+ * @param {object} deps
+ * @param {object} [deps.extra]        The SDK's per-request extra, which carries
+ *   `sendNotification` already associated with the originating request.
+ * @param {string|number} [deps.progressToken]  From `params._meta.progressToken`.
+ * @returns {{enabled: boolean, report: (progress: number, message?: string, total?: number) => Promise<void>}}
+ */
+export function createProgressReporter({ extra, progressToken } = {}) {
+  const token = progressToken ?? extra?._meta?.progressToken;
+  const send = typeof extra?.sendNotification === "function" ? extra.sendNotification.bind(extra) : null;
+
+  if (token === undefined || token === null || !send) {
+    return { enabled: false, report: async () => {} };
+  }
+
+  let last = -1;
+
+  return {
+    enabled: true,
+
+    /**
+     * Report progress. Never rejects.
+     *
+     * `progress` counts units done. When the total is unknown the spec allows a
+     * bare increasing number, which is why `total` is optional everywhere.
+     */
+    async report(progress, message, total) {
+      const value = Number.isFinite(progress) ? progress : 0;
+      // The spec requires progress to increase on every notification. Skipping a
+      // repeat keeps a host's percentage bar monotonic without adding work.
+      if (value <= last) return;
+      last = value;
+
+      try {
+        await send({
+          method: "notifications/progress",
+          params: {
+            progressToken: token,
+            progress: value,
+            ...(Number.isFinite(total) ? { total } : {}),
+            ...(message ? { message } : {}),
+          },
+        });
+      } catch {
+        // A dropped notification is not worth losing a completed run over.
+      }
+    },
+  };
+}
+
+/**
+ * Adapt a progress reporter to the callback shape the handlers take.
+ *
+ * Handlers stay transport-free by receiving a plain `onProgress({progress,
+ * message, total})` function; this is the only place that knows about the
+ * protocol, so a handler test can pass a plain function and assert the sequence.
+ */
+export function handlerProgress(reporter) {
+  if (!reporter?.enabled) return undefined;
+  return ({ progress, message, total } = {}) =>
+    reporter.report(progress ?? 0, message, total);
+}