@nexusbloom/mcp-server 1.0.3 → 2.0.2

package/src/manifests.js

@@ -0,0 +1,247 @@
+/**
+ * Manifest normalisation and caching.
+ *
+ * The API's tool rows are not identical to the manifest contract: `description`
+ * and `short_description` are the same value, `tags` may arrive as a nested
+ * array from Postgres, and community tools have a `category` that built-ins do
+ * not. Everything downstream should be able to assume one shape.
+ */
+
+import { NexusBloomError, ErrorCode } from "./errors.js";
+
+/** Empty but valid — a schema saying "takes nothing" is not the same as null. */
+export function emptyInputSchema() {
+  return { type: "object", properties: {}, required: [] };
+}
+
+/**
+ * Flatten and clean a Postgres text[] column.
+ *
+ * Postgres returns `{{a,b},{c}}` for a `text[][]` column, so a naive read gives
+ * nested arrays that stringify as "a,b". One level of flattening covers every
+ * shape seen in the data.
+ */
+export function normaliseTags(tags) {
+  if (!tags) return [];
+  const flat = (Array.isArray(tags) ? tags.flat(Infinity) : [tags])
+    .filter((t) => typeof t === "string")
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean);
+  return [...new Set(flat)];
+}
+
+/**
+ * Coerce one API row into the canonical manifest shape.
+ *
+ * Returns null for anything without a usable slug: a tool that cannot be named
+ * cannot be called, and letting it through would surface as a tool the agent
+ * sees in the list but can never invoke.
+ */
+export function normaliseTool(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const slug = typeof raw.slug === "string" ? raw.slug.trim() : "";
+  if (!slug) return null;
+
+  const description = (raw.short_description || raw.description || "").trim();
+
+  return {
+    slug,
+    name: (raw.name || slug).trim(),
+    short_description: description,
+    // Kept alongside because MCP's ListTools description is the agent's only
+    // disambiguator when two tools have similar names.
+    description,
+    category: raw.category || raw.tool_type || "uncategorized",
+    runtime: raw.runtime || "both",
+    version: raw.version || "1.0.0",
+    icon: raw.icon || "🔧",
+    type: ["builtin", "community", "local"].includes(raw.type) ? raw.type : "tool",
+    price_type: raw.price_type || "free",
+    pricing: raw.pricing || null,
+    timeout_ms: typeof raw.timeout_ms === "number" ? raw.timeout_ms : null,
+    tags: normaliseTags(raw.tags),
+    input_schema: normaliseSchema(raw.input_schema),
+    output_schema: normaliseSchema(raw.output_schema, { allowNull: true }),
+    // Distinguishes "published with no schema" from "genuinely takes no
+    // parameters". Normalisation erases the difference — both become an empty
+    // object — but an agent needs to know which one it is, because the first
+    // means call `schema` before trying and the second means just call it.
+    hasSchema: isSchemaPresent(raw.input_schema),
+  };
+}
+
+/**
+ * Was a schema actually declared by the publisher?
+ *
+ * Distinct from "does it have properties": a tool may legitimately declare
+ * `{type:"object", properties:{}, required:[]}` to mean it takes nothing, which
+ * is different from having no `input_schema` at all. Only the latter is unknown.
+ */
+function isSchemaPresent(schema) {
+  return Boolean(schema) && typeof schema === "object" && !Array.isArray(schema);
+}
+
+/**
+ * Coerce a stored schema into one a strict MCP client will accept.
+ *
+ * Schemas in the database predate the current contract, so some are missing
+ * `type: "object"` or carry a `required` that is not an array. Forwarding those
+ * verbatim makes the host reject the whole tool list.
+ */
+export function normaliseSchema(schema, { allowNull = false } = {}) {
+  if (schema === null || schema === undefined) {
+    return allowNull ? null : emptyInputSchema();
+  }
+  if (typeof schema !== "object" || Array.isArray(schema)) {
+    return allowNull ? null : emptyInputSchema();
+  }
+  if (schema.type !== "object") {
+    // A schema missing `type: "object"` is rejected by strict MCP clients, so
+    // normalise rather than forward it.
+    return {
+      ...schema,
+      type: "object",
+      properties: schema.properties && typeof schema.properties === "object" ? schema.properties : {},
+      required: Array.isArray(schema.required) ? schema.required : [],
+    };
+  }
+  return {
+    ...schema,
+    properties: schema.properties && typeof schema.properties === "object" ? schema.properties : {},
+    required: Array.isArray(schema.required) ? schema.required : [],
+  };
+}
+
+/**
+ * Unwrap the several shapes an API list endpoint may return.
+ *
+ * The response has been `{tools:[…]}`, `{data:{tools:[…]}}` and a bare array at
+ * different points in its history; clients pinning an old version see all three
+ * depending on deployment.
+ */
+export function unwrapToolsList(body) {
+  const candidates = [
+    body,
+    body?.tools,
+    body?.data,
+    body?.data?.tools,
+    body?.results,
+  ];
+  for (const c of candidates) {
+    if (Array.isArray(c)) return c.filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Unwrap a manifest out of `{success,data:{manifest}}`, `{manifest}` or bare.
+ *
+ * Returns null for an object that carries no recognisable manifest. Without the
+ * last check, a `{success:true,data:{}}` response unwraps to `{}` — truthy, so
+ * the caller would fabricate a tool from an empty object and report a schema
+ * that the publisher never declared.
+ */
+export function unwrapManifest(body) {
+  const candidates = [body?.data?.manifest, body?.manifest, body?.data, body];
+  for (const m of candidates) {
+    if (m && typeof m === "object" && !Array.isArray(m) && hasManifestFields(m)) return m;
+  }
+  return null;
+}
+
+/** Any of the keys that make an object recognisable as a tool manifest. */
+function hasManifestFields(o) {
+  return (
+    "slug" in o ||
+    "input_schema" in o ||
+    "output_schema" in o ||
+    "short_description" in o ||
+    "tool_type" in o
+  );
+}
+
+/**
+ * TTL cache for the tool list.
+ *
+ * The list is re-fetched on every TTL expiry rather than on a timer, so an idle
+ * server makes no requests at all. A failed refresh keeps serving the stale list
+ * rather than emptying it — an agent discovering zero tools because one blip
+ * occurred is worse than an agent seeing slightly old metadata.
+ */
+export class ManifestCache {
+  constructor(client, { ttlMs, now = () => Date.now() } = {}) {
+    this.client = client;
+    this.ttlMs = ttlMs;
+    this.now = now;
+    this._tools = null;
+    this._cachedAt = 0;
+    this._inflight = null;
+  }
+
+  /** True when a cached list exists and has not expired. */
+  isFresh() {
+    return this._tools !== null && this.now() - this._cachedAt < this.ttlMs;
+  }
+
+  /**
+   * Return the tool list, refreshing if stale.
+   *
+   * Concurrent callers share one in-flight request; without that, N agents
+   * starting at once produce N identical catalogue fetches.
+   */
+  async tools({ force = false } = {}) {
+    if (!force && this.isFresh()) return this._tools;
+    if (this._inflight) return this._inflight;
+
+    this._inflight = this._refresh().finally(() => {
+      this._inflight = null;
+    });
+    return this._inflight;
+  }
+
+  async _refresh() {
+    try {
+      const body = await this.client.request("/tools");
+      const tools = unwrapToolsList(body).map(normaliseTool).filter(Boolean);
+
+      // An empty list from a live API is almost always a failure upstream, and
+      // overwriting a good cache with it would strand every agent. Keep the old
+      // value and let the caller see an empty result with a clear reason.
+      if (tools.length === 0 && this._tools) {
+        this._cachedAt = this.now();
+        return this._tools;
+      }
+
+      this._tools = tools;
+      this._cachedAt = this.now();
+      return tools;
+    } catch (err) {
+      if (this._tools) {
+        this._cachedAt = this.now();
+        return this._tools;
+      }
+      throw err instanceof NexusBloomError
+        ? err
+        : new NexusBloomError(err.message, ErrorCode.API_ERROR);
+    }
+  }
+
+  /** Fetch one tool's full manifest, bypassing the list cache. */
+  async manifest(slug) {
+    const body = await this.client.request(`/run/${encodeURIComponent(slug)}`);
+    const manifest = unwrapManifest(body);
+    if (!manifest) {
+      throw new NexusBloomError(
+        `Tool "${slug}" returned no manifest from the API.`,
+        ErrorCode.NOT_FOUND,
+      );
+    }
+    return normaliseTool(manifest) || normaliseTool({ slug, ...manifest });
+  }
+
+  /** Drop cached state; used by tests and the `refresh` meta-command. */
+  clear() {
+    this._tools = null;
+    this._cachedAt = 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;
+}