@nexusbloom/mcp-server 2.1.1 → 2.1.2

package/README.md

@@ -258,6 +258,20 @@ Input is checked against the tool's own schema before anything is sent, so a
 malformed call costs no API quota and returns an error naming the exact field.
 The API remains authoritative — this only rejects what is provably wrong.
 
+## Developer scripts
+
+| Command | What it does |
+|---|---|
+| `npm run shell` | Interactive MCP client over real stdio. `shell:mock` starts a fake API for you. |
+| `npm run agent-demo` | Walks the path an LLM takes — discover, search, schema, run, batch, recover — with no model needed. `agent-demo:mock` starts its own mock. |
+| `npm run catalogue-check` | Every tool in the seed catalogue walked through the real server: advertise, describe, validate, run, batch, resolve as a resource. Exits non-zero on any failure, so it works as a CI gate. |
+| `npm run mock-api [port]` | The fake API on its own. Reuses a running one or explains what holds the port. |
+
+`agent-demo` checks the API is reachable before it starts. That is deliberate:
+when the mock is not running, every check otherwise fails with its own
+`ECONNREFUSED`, and ten identical failures read as a broken server rather than a
+missing dependency.
+
 ## Design notes
 
 **Execution never guesses.** Slugs resolve by exact match or unambiguous

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "2.1.1",
-  "description": "MCP server for NexusBloom — agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
+  "version": "2.1.2",
+  "description": "MCP server for NexusBloom \u2014 agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -34,13 +34,13 @@
     "test": "node --test --import ./test/setup.mjs test/*.test.js",
     "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 test/resources.test.js test/batch.test.js test/progress.test.js test/prompts.test.js test/history.test.js test/local.test.js",
     "shell": "node scripts/mcp-shell.mjs",
     "shell:mock": "node scripts/mcp-shell.mjs --mock",
     "mock-api": "node scripts/mock-api.mjs",
     "agent-demo": "node scripts/agent-demo.mjs",
-    "agent-demo:mock": "node scripts/agent-demo.mjs --url http://127.0.0.1:8787/api",
+    "agent-demo:mock": "node scripts/agent-demo.mjs --mock",
     "catalogue-check": "node scripts/full-catalogue-check.mjs",
-    "lint": "node --check index.js && for f in src/*.js; do node --check \"$f\" || exit 1; done"
+    "lint": "node --check index.js && for f in src/*.js; do node --check \"$f\" || exit 1; done",
+    "prepublishOnly": "npm run lint && npm test && npm run catalogue-check"
   }
 }

package/src/client.js

@@ -24,6 +24,49 @@ export function makeLogger(debug) {
   };
 }
 
+/**
+ * Turn whatever the API put in `error` into a message an agent can act on.
+ *
+ * The obvious version of this is `String(apiMessage).trim() || fallback`, but
+ * `String({})` is `"[object Object]"` — technically a string, useless as a
+ * diagnosis. Production returns structured errors (`error` as an object, an
+ * array, occasionally a number), and the previous code called `.trim()` on the
+ * raw value: optional chaining guards null and undefined, not "exists and is not
+ * a function". Every structured API error therefore died as
+ * `TypeError: apiMessage?.trim is not a function` — thrown from the error path,
+ * so it fired only once something was already broken, and it replaced the real
+ * status and code with a stack trace about the client's own bug.
+ *
+ * So: preserve structure as JSON, because `{"hint":"rate limited"}` tells an
+ * agent what `[object Object]` cannot, and never throw while reporting a
+ * failure.
+ *
+ * @param {unknown} candidate
+ * @param {Response} res
+ * @param {{method: string, url: string}} ctx
+ * @returns {string}
+ */
+export function describeApiError(candidate, res, ctx) {
+  const fallback = `API returned ${res.status} for ${ctx.method} ${ctx.url}`;
+
+  if (candidate === null || candidate === undefined) return fallback;
+
+  if (typeof candidate === "string") return candidate.trim() || fallback;
+
+  if (typeof candidate === "object") {
+    try {
+      const json = JSON.stringify(candidate);
+      return json && json !== "{}" && json !== "[]" ? json : fallback;
+    } catch {
+      // Circular, or a BigInt. The status line still identifies the failure.
+      return fallback;
+    }
+  }
+
+  // number, boolean, bigint, symbol, function — all fine as text.
+  return String(candidate) || fallback;
+}
+
 export class ApiClient {
   /**
    * @param {object} config  From loadConfig().
@@ -143,15 +186,13 @@ export class ApiClient {
     }
 
     if (!res.ok) {
-      const apiMessage =
-        parsed?.error || parsed?.message || parsed?.data?.error || text?.slice(0, 300);
-      const code = parsed?.code || codeForStatus(res.status);
-
-      const message = apiMessage?.trim()
-        ? `${apiMessage}`
-        : `API returned ${res.status} for ${ctx.method} ${ctx.url}`;
+      const message = describeApiError(
+        parsed?.error ?? parsed?.message ?? parsed?.data?.error ?? text?.slice(0, 300),
+        res,
+        ctx,
+      );
 
-      throw new NexusBloomError(message, code, {
+      throw new NexusBloomError(message, parsed?.code || codeForStatus(res.status), {
         status: res.status,
         // The API returns `fields` on schema failures; keep it so an agent can
         // repair exactly the bad keys instead of re-reading the whole schema.

package/src/preview.test.js

@@ -1,185 +0,0 @@
-/**
- * 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);
-});