@nexusbloom/mcp-server 1.0.3 → 2.0.2

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

@@ -0,0 +1,378 @@
+/**
+ * Response rendering — the part of the server an agent actually reads.
+ *
+ * Design rules, in priority order:
+ *
+ * 1. **A tool that cannot be called is a defect.** Every schema response states
+ *    the exact arguments to pass, in a copy-pasteable form. An agent should
+ *    never have to assemble a call by reading a JSON Schema.
+ * 2. **Errors carry a next action.** "Tool not found" is a dead end; "no tool
+ *    named `env-validatr`. Did you mean: env-validator" is recoverable.
+ * 3. **Output first.** The result leads, with framing kept to two lines. Agents
+ *    parse the payload, not prose.
+ * 4. **Machine-readable is always attached.** The text block is optimised for
+ *    reading; a structured block carries the same data for extraction.
+ */
+
+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.
+ *
+ * Always a text block, because that is what a model reads. A resource block is
+ * appended when there is structured data, so an agent that prefers extraction
+ * over prose gets an exact payload instead of parsing markdown.
+ */
+export function respond(payload) {
+  // 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",
+      resource: {
+        uri: "data:application/json,",
+        mimeType: "application/json",
+        text: safeStringify(payload.data),
+      },
+    });
+  }
+  return { content };
+}
+
+/** Error response. Never throws — the agent gets a value it can branch on. */
+export function respondError(err) {
+  const message = err?.message || String(err) || "Unknown error.";
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+    structuredContent:
+      typeof err?.toJSON === "function"
+        ? err.toJSON()
+        : { success: false, error: message, code: err?.code || ErrorCode.API_ERROR, retryable: false },
+  };
+}
+
+/**
+ * How many required parameters a tool has, or -1 when it has no schema at all.
+ *
+ * The three-way result matters: "no parameters" and "parameters I can't see" are
+ * different situations for an agent, and conflating them would present an
+ * unknown schema as a tool that takes nothing.
+ */
+export function requiredCount(tool) {
+  const schema = tool?.input_schema;
+  const required = Array.isArray(schema?.required) ? schema.required.length : 0;
+  if (required > 0) return required;
+
+  // No required fields, but the schema may simply be absent — normaliseTool
+  // records which, so a tool with no published schema is not mislabelled as a
+  // tool that takes nothing.
+  return tool?.hasSchema === false ? -1 : 0;
+}
+
+/**
+ * The catalogue.
+ *
+ * With 30+ tools a flat dump is unusable in a context window, so this lists a
+ * compact one-line-per-tool summary and points at `search` for anything narrower.
+ */
+export function renderToolList(tools, { total } = {}) {
+  const count = total ?? tools.length;
+  if (count === 0) {
+    return {
+      text:
+        `# NexusBloom Tools\n\nNo tools are currently published.\n\n` +
+        `This usually means the API is unreachable or the catalogue is empty. ` +
+        `Check that NEXUSBLOOM_API_URL points at a working deployment.`,
+      data: { tools: [], count: 0 },
+    };
+  }
+
+  const lines = tools.map((t) => {
+    const req = requiredCount(t);    const input =
+      req > 0 ? `${req} required` : req === 0 ? "no required" : "schema unknown";
+    const tags = t.tags?.length ? ` · ${t.tags.slice(0, 3).join(", ")}` : "";
+    return `- **${t.name}** (\`${t.slug}\`) — ${t.short_description || "No description"} · ${input}${tags}`;
+  });
+
+  const text =
+    `# NexusBloom Tools\n\n` +
+    `${count} tool${count === 1 ? "" : "s"} available.\n\n${lines.join("\n")}\n\n` +
+    `---\n` +
+    `Next steps:\n` +
+    `• Need something specific? Call \`nexusbloom\` with \`{"command":"search","query":"what you need"}\` — it ranks by relevance.\n` +
+    `• Before running a tool, call \`{"command":"schema","slug":"<slug>"}\` to get its exact parameters.\n` +
+    `• To run: call the tool by its slug directly, e.g. \`{"name":"${tools[0].slug}","arguments":{…}}\`.`;
+
+  return { text, data: { tools, count } };
+}
+
+/**
+ * Search results.
+ *
+ * Explains the query when nothing matched — an empty list with no reason is
+ * indistinguishable from a broken server.
+ */
+export function renderSearchResults(query, tools, catalogueSize, categories = []) {
+  if (tools.length === 0) {
+    // "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` +
+        `${catalogueSize} tools are published, none matching that query. Try:\n` +
+        `• Fewer or more general words — e.g. "validate" rather than "validate my dotenv file in production"` +
+        `${categoryHint}\n` +
+        `• \`{"command":"list"}\` to see everything.`,
+      data: { query, tools: [], count: 0 },
+    };
+  }
+
+  const lines = tools.map(
+    (t) => `- **${t.name}** (\`${t.slug}\`) — ${t.short_description || "No description"}`,
+  );
+
+  const text =
+    `# Tools matching "${query}"\n\n` +
+    `${tools.length} of ${catalogueSize} tools.\n\n${lines.join("\n")}\n\n` +
+    `Call \`{"command":"schema","slug":"<slug>"}\` for parameters, or invoke the tool directly by slug.`;
+
+  return { text, data: { query, tools, count: tools.length } };
+}
+
+/**
+ * A tool's full contract.
+ *
+ * The example invocation at the end is the load-bearing part: it is valid JSON
+ * containing every required parameter with a placeholder, so an agent can call
+ * it back by changing only the values.
+ */
+export function renderSchema(rawSchema, tools = []) {
+  // Defensive normalisation: a caller may hand over a bare object rather than a
+  // normalised tool, and a missing name must read as a fallback, never as the
+  // literal string "undefined".
+  const schema = normaliseTool({ slug: "tool", ...rawSchema }) || normaliseTool({ slug: "tool" });
+
+  const params = describeParameters(schema.input_schema);
+  const required = params.filter((p) => p.required);
+
+  const paramLines = params.length
+    ? params
+        .map((p) => {
+          const detail = p.description ? ` — ${p.description}` : "";
+          return `- \`${p.name}\` (${p.summary || "any"})${detail}`;
+        })
+        .join("\n")
+    : "_This tool takes no parameters._";
+
+  const exampleArgs = buildExampleArgs(schema);
+
+  let example;
+  if (params.length === 0) {
+    example = `Call it with no arguments:\n\`\`\`json\n{"name": "${schema.slug}", "arguments": {}}\n\`\`\``;
+  } else if (required.length === 0) {
+    example =
+      `Only optional parameters exist, so \`{}\` is valid:\n` +
+      `\`\`\`json\n{"name": "${schema.slug}", "arguments": {}}\n\`\`\``;
+  } else {
+    example =
+      `Replace the placeholder values, then call:\n` +
+      `\`\`\`json\n{"name": "${schema.slug}", "arguments": ${JSON.stringify(exampleArgs, null, 2)}}\n\`\`\``;
+  }
+
+  const outputNote = schema.output_schema
+    ? `\n**Returns:** shaped per \`output_schema\` (${describeOutputShape(schema.output_schema)}).`
+    : "";
+
+  const priceNote =
+    schema.price_type && schema.price_type !== "free"
+      ? `\n**Pricing:** ${schema.price_type} — this tool may consume API quota.`
+      : "";
+
+  const related = suggestRelated(tools, schema);
+
+  const meta = [
+    `**Slug:** \`${schema.slug}\``,
+    `**Category:** ${schema.category}`,
+    `**Runtime:** ${schema.runtime}`,
+    schema.short_description ? `**Description:** ${schema.short_description}` : null,
+    schema.tags?.length ? `**Tags:** ${schema.tags.join(", ")}` : null,
+  ].filter(Boolean);
+
+  const text =
+    `# ${schema.icon} ${schema.name}\n\n` +
+    `${meta.join("\n")}\n${outputNote}${priceNote}\n` +
+    `\n## Parameters\n\n${paramLines}\n` +
+    (required.length ? `\nRequired: ${required.map((r) => `\`${r.name}\``).join(", ")}\n` : "") +
+    `\n## How to call it\n\n${example}` +
+    (related ? `\n\n## Related\n\n${related}` : "");
+
+  return { text, data: schema };
+}
+
+/** Describe an output schema's top-level shape in one clause. */
+function describeOutputShape(schema) {
+  const props = schema?.properties || {};
+  const keys = Object.keys(props);
+  if (keys.length === 0) return "no documented fields";
+  if (keys.length <= 4) return keys.map((k) => `\`${k}\``).join(", ");
+  return `${keys.slice(0, 4).map((k) => `\`${k}\``).join(", ")} +${keys.length - 4} more`;
+}
+
+/** Other tools sharing tags or category, so an agent can compose. */
+function suggestRelated(tools, schema) {
+  const tags = new Set(schema.tags || []);
+  const others = tools.filter((t) => t.slug !== schema.slug);
+  const byTag = others.filter((t) => (t.tags || []).some((tag) => tags.has(tag)));
+  const pool = (byTag.length ? byTag : others.filter((t) => t.category === schema.category))
+    .slice(0, 4);
+  if (!pool.length) return null;
+  return pool.map((t) => `- \`${t.slug}\` — ${t.short_description || t.name}`).join("\n");
+}
+
+/**
+ * Build a valid example argument object from a schema.
+ *
+ * Required parameters get a placeholder derived from their declared type — a
+ * string gets "string", a number gets 0, and so on — because a placeholder the
+ * agent can recognise and replace is worth more than one it has to guess the
+ * type of. Returns null when the tool requires nothing.
+ */
+export function buildExampleArgs(schema) {
+  const inputSchema = schema?.input_schema;
+  const properties = inputSchema?.properties || {};
+  const required = inputSchema?.required || [];
+  if (required.length === 0) return {};
+
+  const args = {};
+  for (const key of required) {
+    const prop = properties[key] || {};
+    args[key] = placeholderFor(prop);
+  }
+  return args;
+}
+
+function placeholderFor(prop) {
+  if (prop.enum?.length) return prop.enum[0];
+  const t = Array.isArray(prop.type) ? prop.type[0] : prop.type;
+  switch (t) {
+    case "string":
+      return prop.format === "date-time" ? "2026-01-01T00:00:00Z" : "string";
+    case "integer":
+      return 0;
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "array":
+      return [];
+    case "object":
+      return {};
+    default:
+      return null;
+  }
+}
+
+/**
+ * A successful execution result.
+ *
+ * The payload is fenced as JSON and unindented-by-default is avoided: agents
+ * 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", rateLimit } = {}) {
+  const json = safeStringify(data);
+  const meta = [`Tool: \`${slug}\``, `Execution: ${execution}`];
+  if (typeof durationMs === "number") meta.push(`Duration: ${durationMs}ms`);
+
+  // 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,
+  };
+}
+
+/** A failure that still succeeded as a call — a tool returning `{error:…}`. */
+export function renderToolReportedError(slug, data) {
+  const message =
+    data?.error || data?.message || "The tool reported an error.";
+  const code = data?.code ? ` (${data.code})` : "";
+  return {
+    text:
+      `# ${slug} reported an error${code}\n\n${message}\n\n` +
+      `This is the tool's own response, not a transport failure. The tool ran; check its parameters and try again.`,
+    data,
+  };
+}
+
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Startup diagnostics. Always stderr — never part of an MCP response. */
+export function renderConnectivityReport({ connected, roots, apiBase, anonymous, errors }) {
+  const lines = [];
+  if (connected) {
+    lines.push(`NexusBloom MCP server connected to ${connected}`);
+  } else {
+    lines.push("WARNING: could not reach the NexusBloom API. Starting in degraded mode.");
+    lines.push("Tool discovery and execution will fail until this is fixed.");
+    lines.push("");
+    lines.push("Checked:");
+    for (const r of roots) lines.push(`  - ${r}/tools`);
+    if (errors?.length) {
+      lines.push("");
+      lines.push("Errors:");
+      for (const e of errors) lines.push(`  - ${e}`);
+    }
+    lines.push("");
+    lines.push(
+      `To fix: set NEXUSBLOOM_API_URL to a reachable deployment ` +
+        `(currently "${apiBase}"), or check the API is deployed.`,
+    );
+  }
+  if (anonymous) {
+    lines.push("");
+    lines.push("No NEXUSBLOOM_API_KEY set — running anonymously under the free-tier rate limit.");
+    lines.push("Set NEXUSBLOOM_API_KEY for authenticated execution and higher limits.");
+  }
+  lines.push(`API base: ${apiBase}`);
+  return lines.join("\n");
+}
+
+export { ErrorCode };

package/src/server.js

@@ -0,0 +1,83 @@
+/**
+ * MCP SDK adapter.
+ *
+ * Deliberately thin: it translates JSON-RPC into calls on the handler set and
+ * nothing else. All behaviour lives in handlers.js where it can be tested
+ * without a transport, so this file is the only place the SDK is imported.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { buildToolList, createHandlers } from "./handlers.js";
+
+export const SERVER_NAME = "nexusbloom-mcp";
+export const SERVER_VERSION = "2.0.0";
+
+/**
+ * Wire a handler set onto an MCP Server.
+ *
+ * @param {object} deps { client, cache, config }
+ * @param {object} [deps.handlers]  Prebuilt handler set. Supplying one is the
+ *   seam that lets the error-containment path be tested directly.
+ * @returns {{server: Server, handlers: object}}
+ */
+export function createServer({ client, cache, config, handlers: provided }) {
+  const handlers = provided ?? createHandlers({ client, cache, config });
+  const listTools = provided ? buildToolList(cache) : handlers.listTools;
+
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => listTools());
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name: toolName, arguments: args } = request.params ?? {};
+
+    // No handler may throw: an exception here becomes a JSON-RPC protocol error,
+    // which a model cannot recover from, whereas an isError result is a normal
+    // tool outcome it can reason about.
+    try {
+      if (!toolName) {
+        return {
+          content: [{ type: "text", text: "No tool name was provided in the request." }],
+          isError: true,
+        };
+      }
+      return toolName === "nexusbloom"
+        ? await handlers.meta(args ?? {})
+        : await handlers.callDirect(toolName, args ?? {});
+    } catch (err) {
+      return handlers.handleError ? handlers.handleError(err) : fallbackError(err);
+    }
+  });
+
+  return { server, handlers };
+}
+
+/**
+ * Last-resort error shape.
+ *
+ * `createHandlers` always supplies `handleError`, so this only runs if a future
+ * caller wires up a partial handler set. It exists because an uncaught throw at
+ * this boundary becomes a JSON-RPC protocol error, which a model cannot recover
+ * from — strictly worse than a value it can read.
+ */
+export function fallbackError(err) {
+  const message = err?.message || "Unknown error.";
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+    structuredContent: {
+      success: false,
+      error: message,
+      code: err?.code || "API_ERROR",
+      retryable: err?.retryable ?? false,
+    },
+  };
+}