@nexusbloom/mcp-server 2.1.0 → 2.1.1

package/README.md

@@ -52,6 +52,16 @@ anything else there corrupts the protocol.
 Every published tool is advertised as an MCP tool **named by its slug**, with its
 real JSON Schema — so it can be called directly:
 
+> **One caveat on slugs.** A slug has to match MCP's tool-name grammar
+> (`[A-Za-z0-9_-]{1,64}`) to be advertised. A catalogue slug that does not — a
+> space, a slash, non-ASCII, or more than 64 characters — is *withheld from the
+> tool list* and reported once on stderr, because a strict host validates every
+> name in that array and rejects the whole response over one bad entry. That
+> would cost an agent every tool rather than one. A withheld tool is still
+> reachable through `{"command":"run"}` and `nexusbloom://catalogue`; it is only
+> not directly callable. `npm run catalogue-check` verifies a catalogue against
+> the grammar.
+
 ```jsonc
 { "name": "env-validator", "arguments": { "env_content": "DEBUG=true" } }
 ```
@@ -66,7 +76,7 @@ which tool it wants:
 | `{"command":"schema","slug":"…"}` | Exact parameters, plus a ready-to-send example invocation. |
 | `{"command":"run","slug":"…","params":{…}}` | Execute a tool. |
 | `{"command":"batch","runs":[{"slug":"…","params":{…}},…]}` | Execute up to 10 tools in one call. |
-| `{"command":"history"}` | What this session has run, newest first. |
+| `{"command":"history"}` | What this **server process** has run, newest first. |
 | `{"command":"history","show":"<id>"}` | One run in full: input, result, timing. |
 | `{"command":"diff","from":"<id>","to":"<id>"}` | Compare two runs field by field. |
 
@@ -201,6 +211,16 @@ Three deliberate constraints:
 - **In memory, never on disk.** Run payloads are user data and frequently
   secrets. A log on disk would be an unencrypted store nobody asked for, and
   losing it on restart costs nothing the tool call did not.
+- **Scoped to the process, not the conversation.** Most hosts keep the stdio
+  process alive across turns, so history spans every conversation turn the
+  process has served — it is not reset between them. Every history response says
+  so, and carries the process start time, because an agent that finds a run it
+  cannot account for needs somewhere to stop guessing. Observed in a real
+  session: an agent correctly reported that an unexplained earlier run had
+  different input, then invented a story about who had changed it and when,
+  and escalated it into a security incident. The facts were right; the cause
+  was fiction. Naming the boundary is what makes "this predates me" a
+  checkable statement.
 - **Bounded.** 50 runs, each payload capped at 8,000 characters. Truncation is
   recorded, and a diff says so — a truncated payload reporting "no differences"
   would be the worst possible failure mode here.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "2.1.0",
-  "description": "MCP server for NexusBloom \u2014 agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
+  "version": "2.1.1",
+  "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",
   "bin": {
@@ -40,6 +40,7 @@
     "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",
+    "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"
   }
 }

package/src/handlers.js

@@ -18,7 +18,7 @@ import {
   suggest,
 } from "./discovery.js";
 import { asNexusBloomError, ErrorCode, NexusBloomError } from "./errors.js";
-import { ManifestCache, normaliseTool } from "./manifests.js";
+import { ManifestCache, normaliseTool, partitionAdvertisable } from "./manifests.js";
 import {
   renderBatch,
   renderConnectivityReport,
@@ -298,7 +298,7 @@ export function createHandlers({ client, cache, config, history: providedHistory
       }
       const limit = Number.isInteger(args?.limit) && args.limit > 0 ? Math.min(args.limit, 50) : 10;
       const all = history.list();
-      return respond(renderHistory(history.recent(limit), { total: all.length }));
+      return respond(renderHistory(history.recent(limit), { total: all.length, scope: history.scope() }));
     }
 
     if (command === "diff") {
@@ -449,7 +449,19 @@ export function createHandlers({ client, cache, config, history: providedHistory
   }
 
   return {
-    listTools: buildToolList(cache),
+    // Withheld tools are reported once, on stderr, and not behind a debug flag:
+    // a slug the catalogue cannot express as an MCP tool name is a data problem
+    // somebody has to fix, and silence leaves the tool quietly unreachable.
+    listTools: buildToolList(cache, {
+      onWithheld(withheld) {
+        for (const w of withheld) {
+          process.stderr.write(
+            `[catalogue] "${w.slug}" is not advertised as an MCP tool — ${w.reason}. ` +
+              'It is still reachable via {"command":"run"} and nexusbloom://catalogue.\n',
+          );
+        }
+      },
+    }),
     meta,
     batch: runBatch,
     history,
@@ -569,7 +581,7 @@ function enrichNotFound(err, slug, tools) {
  * meta-tool is advertised too — it is how an agent recovers when a direct call
  * is not what it wanted.
  */
-export function buildToolList(cache) {
+export function buildToolList(cache, { onWithheld } = {}) {
   return async function listTools() {
     // A catalogue failure must not fail the whole request. If the API is
     // unreachable, a host that receives a JSON-RPC error considers the *server*
@@ -582,7 +594,16 @@ export function buildToolList(cache) {
       tools = [];
     }
 
-    const entries = tools.map((t) => ({
+    // A slug that is not a legal MCP tool name is held back rather than
+    // emitted. A strict host validates every name in this array and rejects the
+    // entire response over one bad entry, so a single odd slug in the catalogue
+    // would cost the agent every tool — not just that one. The meta-tool still
+    // reaches the withheld tools, and the reason is surfaced rather than
+    // swallowed, so the catalogue can be fixed at source.
+    const { advertisable, withheld } = partitionAdvertisable(tools);
+    if (withheld.length) onWithheld?.(withheld);
+
+    const entries = advertisable.map((t) => ({
       name: t.slug,
       description: buildToolDescription(t),
       inputSchema: t.input_schema,
@@ -597,7 +618,7 @@ export function buildToolList(cache) {
         '- {"command":"list"} — every published tool, one line each\n' +
         '- {"command":"schema","slug":"<slug>"} — exact parameters plus a ready-to-send example\n' +
         '- {"command":"batch","runs":[{"slug":"<slug>","params":{…}},…]} — run up to 10 tools in one call\n' +
-        '- {"command":"history"} / {"command":"history","show":"<id>"} — what this session has run\n' +
+        '- {"command":"history"} / {"command":"history","show":"<id>"} — what this server process has run\n' +
         '- {"command":"diff","from":"<id>","to":"<id>"} — compare two runs field by field\n\n' +
         "Any published tool is also callable directly by its slug, with its own " +
         "parameters as arguments — this tool is for when you do not yet know which one to use.\n\n" +
@@ -613,7 +634,7 @@ export function buildToolList(cache) {
             description:
               "list: all tools. search: find by intent. schema: a tool's parameters. " +
               "run: execute one tool. batch: execute up to 10 tools in one call. " +
-              "history: what this session has run. diff: compare two recorded runs.",
+              "history: what this server process has run, and since when. diff: compare two recorded runs.",
           },
           slug: {
             type: "string",

package/src/history.js

@@ -61,6 +61,37 @@ export class RunHistory {
     this.now = now;
     this.runs = [];
     this._nextId = 1;
+    // When this process started holding history. Present so an agent can tell
+    // "a run this process saw" from "a run from before I was talking" — see
+    // the note on scope below.
+    this.startedAt = new Date(this.now()).toISOString();
+  }
+
+  /**
+   * What "history" actually covers, for callers to surface verbatim.
+   *
+   * This is deliberately not called a session. A host that keeps the stdio
+   * process alive across turns — which is most of them — will hand the same
+   * process several separate conversations, and history spans all of them.
+   *
+   * Observed in a real agent session: the agent found an `r1` it could not
+   * account for, correctly reported that its input differed from its own, and
+   * then invented a causal story about who changed what and when — including
+   * an urgent security conclusion — because nothing in the output said where
+   * the boundary was. The facts were right and the cause was fiction.
+   *
+   * Naming the scope is what stops that: an agent can say "this run predates my
+   * involvement in this process", which is checkable, instead of inventing why.
+   */
+  scope() {
+    return {
+      scope: "server-process",
+      startedAt: this.startedAt,
+      note:
+        "In-memory only. Covers every run since this server process started, " +
+        "which may span multiple conversation turns if your host keeps the " +
+        "process alive. Never written to disk.",
+    };
   }
 
   /**

package/src/manifests.js

@@ -37,6 +37,50 @@ export function normaliseTags(tags) {
  * cannot be called, and letting it through would surface as a tool the agent
  * sees in the list but can never invoke.
  */
+/**
+ * The MCP tool-name grammar.
+ *
+ * A published slug is whatever the catalogue happens to contain, and nothing
+ * upstream constrains it to this. Emitting an illegal name in `tools/list` is
+ * not a cosmetic problem: a strict host validates every name in the array and
+ * rejects the *whole response* over one bad entry, which leaves the agent with
+ * no tools at all rather than one fewer. So illegal slugs are held back from
+ * the tool list and reported instead — see `partitionAdvertisable`.
+ */
+export const MCP_TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+
+/**
+ * Split a catalogue into tools that can be advertised as MCP tools and tools
+ * whose slug cannot be.
+ *
+ * The held-back tools stay fully usable through the meta-tool and the catalogue
+ * resource — they are only prevented from poisoning the tool list for
+ * everything else. That is the difference between "this tool is awkward to
+ * address" and "this tool does not exist".
+ *
+ * @param {object[]} tools normalised tools
+ * @returns {{advertisable: object[], withheld: {slug: string, reason: string}[]}}
+ */
+export function partitionAdvertisable(tools) {
+  const advertisable = [];
+  const withheld = [];
+
+  for (const tool of tools) {
+    const slug = tool?.slug ?? "";
+    if (MCP_TOOL_NAME.test(slug)) {
+      advertisable.push(tool);
+      continue;
+    }
+    let reason;
+    if (!slug) reason = "slug is empty";
+    else if (slug.length > 64) reason = `slug is ${slug.length} characters, the MCP maximum is 64`;
+    else reason = `slug contains characters MCP does not allow in a tool name: ${JSON.stringify(slug)}`;
+    withheld.push({ slug: String(slug), reason });
+  }
+
+  return { advertisable, withheld };
+}
+
 export function normaliseTool(raw) {
   if (!raw || typeof raw !== "object") return null;
   const slug = typeof raw.slug === "string" ? raw.slug.trim() : "";

package/src/render.js

@@ -340,13 +340,22 @@ export function renderResult(slug, data, { durationMs, execution = "remote", rat
  * compare, and inlining fifty payloads would cost more context than the diff the
  * reader actually came for. `history show` carries the payload for one run.
  */
-export function renderHistory(runs, { total } = {}) {
+export function renderHistory(runs, { total, scope } = {}) {
+  // The scope line is load-bearing, not decoration. Without it an agent that
+  // finds a run it cannot account for has no way to tell "this process saw it"
+  // from "it happened before I was involved", and will fill the gap with a
+  // guess. Naming the boundary lets it say "this predates me" and stop there.
+  const scopeLine = scope
+    ? `\nScope: ${scope.scope}, started ${scope.startedAt}. ${scope.note}\n`
+    : "";
+
   if (!runs.length) {
     return {
       text:
-        `# Run history\n\nNo runs recorded in this session.\n\n` +
-        `History lives in memory only: it starts empty on every server start and is never written to disk.`,
-      data: { runs: [], count: 0 },
+        `# Run history\n\nNo runs recorded since this server started.` +
+        scopeLine +
+        `\nHistory is never written to disk.`,
+      data: { runs: [], count: 0, ...(scope ? { scope } : {}) },
     };
   }
 
@@ -358,13 +367,14 @@ export function renderHistory(runs, { total } = {}) {
 
   const text =
     `# Run history\n\n` +
-    `${runs.length} of ${total ?? runs.length} recorded run${runs.length === 1 ? "" : "s"}, newest first.\n\n` +
-    `${lines.join("\n")}\n\n` +
+    `${runs.length} of ${total ?? runs.length} recorded run${runs.length === 1 ? "" : "s"}, newest first.` +
+    scopeLine +
+    `\n${lines.join("\n")}\n\n` +
     `---\n` +
     `Compare two runs with \`{"command":"diff","from":"<id>","to":"<id>"}\`. ` +
     `\`-1\` is the most recent run, \`-2\` the one before it.`;
 
-  return { text, data: { runs, count: runs.length } };
+  return { text, data: { runs, count: runs.length, ...(scope ? { scope } : {}) } };
 }
 
 /** One run in full, with its result. */

package/src/resources.js

@@ -62,7 +62,8 @@ export function createResources({ cache, config, history } = {}) {
           uri: HISTORY_URI,
           name: "Run history",
           description:
-            "What this session has run, newest first: run id, tool, status, duration. " +
+            "What this server process has run, newest first: run id, tool, status, duration, " +
+            "plus the process start time so the boundary is explicit. " +
             "In memory only — never written to disk.",
           mimeType: JSON_MIME,
         },
@@ -137,7 +138,10 @@ export function createResources({ cache, config, history } = {}) {
   function readHistory(log) {
     if (!log) return { runs: [], count: 0, note: "No run log is attached to this resource set." };
     const runs = log.recent(50).map((r) => summariseRun(r));
-    return { runs, count: runs.length };
+    // Same scope block as `{"command":"history"}` — a host pulling this as a
+    // resource has no more idea when the process started than one calling the
+    // command does.
+    return { runs, count: runs.length, scope: log.scope() };
   }
 
   /**
@@ -265,7 +269,7 @@ Meta commands:
 - \`{"command":"schema","slug":"<slug>"}\` — parameters plus a ready-to-send example
 - \`{"command":"run","slug":"<slug>","params":{…}}\` — execute
 - \`{"command":"batch","runs":[…]}\` — up to 10 runs in one call
-- \`{"command":"history"}\` / \`{"command":"history","show":"<id>"}\` — what this session ran
+- \`{"command":"history"}\` / \`{"command":"history","show":"<id>"}\` — what this server process ran
 - \`{"command":"diff","from":"<id>","to":"<id>"}\` — compare two runs, field by field
 
 And when several tools belong to one task, run them in a single turn: