@nexusbloom/mcp-server 2.0.2 → 2.1.1

package/README.md

@@ -42,6 +42,7 @@ All variables are optional.
 | `NEXUSBLOOM_MCP_TIMEOUT_MS` | `15000` | Per-request timeout. |
 | `NEXUSBLOOM_MCP_CACHE_TTL_MS` | `60000` | Tool-list cache lifetime. `0` disables caching. |
 | `NEXUSBLOOM_MCP_DEBUG` | *(off)* | `1` logs requests to stderr. |
+| `NEXUSBLOOM_MCP_EXECUTION` | `remote` | `local` or `auto` to execute tool source on this machine. **Off by default on purpose** — see below. |
 
 Diagnostics always go to **stderr**; stdout is the MCP transport and writing
 anything else there corrupts the protocol.
@@ -51,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" } }
 ```
@@ -64,6 +75,164 @@ which tool it wants:
 | `{"command":"list"}` | Every published tool, one line each. |
 | `{"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 **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. |
+
+### Batching
+
+Several tools belonging to one task go in a single turn:
+
+```jsonc
+{ "command": "batch", "runs": [
+  { "slug": "env-validator",  "params": { "env_content": "DEBUG=true" } },
+  { "slug": "data-generator", "params": { "count": 2 } }
+] }
+```
+
+Two behaviours make it safe rather than merely fast:
+
+- **Validate everything first.** Every slug is resolved and every schema checked
+  before the first run. A typo in item four costs zero quota and rejects the
+  whole batch — a batch is one intent, so half of it is not a useful answer.
+- **Then isolate failures.** Past that point each run is independent. One tool
+  erroring does not discard the seven that worked; the response reports the
+  tally, lists failures first, and the structured block keeps every payload.
+
+Capped at 10 runs, because anonymous execution allows 30 requests/minute and one
+turn should not spend the budget the next ten calls need.
+
+### Progress notifications
+
+If the host sends a `progressToken` in `_meta`, the server emits
+`notifications/progress` while a batch runs — one tick per entry, plus an opening
+tick so the host is never silent. Progress is monotonic, and a failed
+notification never fails the call. A host that sends no token receives none:
+unsolicited progress is a protocol violation, not a nicety.
+
+### Resources — read the catalogue without spending a call
+
+Hosts that support MCP resources can pull the catalogue directly, which is how
+an agent holds the whole surface in context instead of discovering it one slug
+at a time:
+
+| URI | Contents |
+|---|---|
+| `nexusbloom://guide` | This usage guide as markdown: meta commands, recovery paths, limits. |
+| `nexusbloom://catalogue` | Every tool as JSON — slug, description, category, tags, parameter counts, `has_schema`, and the URI of its full manifest. |
+| `nexusbloom://tools/{slug}` | One tool's full manifest: input **and** output JSON Schema, plus `call: { tool, arguments }` — a ready-to-send example. |
+
+The catalogue deliberately omits full schemas; that is what the per-tool URI is
+for. A 31-manifest inline blob would exhaust the context budget before the agent
+had chosen anything.
+
+Slugs in resource URIs resolve by exact match or unambiguous abbreviation only,
+identically to tool calls, and an unknown slug produces a protocol error naming
+the close matches rather than an empty body an agent might quote as fact.
+
+### Prompts — one-click starts a host can offer
+
+Four prompts, each assembled against the live catalogue rather than canned, so
+the text a model receives names tools that actually exist and carries calls that
+already validate:
+
+| Prompt | Arguments | Gives the model |
+|---|---|---|
+| `find-tool` | `goal` | Tools matching the goal, ranked, with each one's parameter cost and the manifest URI. |
+| `use-tool` | `slug` | One tool's exact parameters, its `output_schema`, and a valid call to copy. |
+| `plan-batch` | `task` | Likely participants, the batch call shape, the 10-run cap, and the whole-batch validation rule. |
+| `recover` | `error`, `slug` | What each error code means, what to do about it, and the failed tool's real call shape. |
+
+`recover` exists because the common failure is not "the tool broke" — it is an
+agent retrying a validation failure unchanged, or guessing slugs. The prompt
+states the codes, marks which are retryable, and embeds the required fields of the
+tool that just failed.
+
+`use-tool` resolves slugs **exactly**, unlike tool calls. A prompt naming a tool
+is a deliberate user choice; silently running a different tool because a prefix
+happened to match would be the wrong answer to a request the user made explicitly.
+
+
+### Local execution (opt-in, and read this first)
+
+`NEXUSBLOOM_MCP_EXECUTION` chooses where tool code runs:
+
+| Mode | Behaviour |
+|---|---|
+| `remote` *(default)* | Always call the API. No tool source is ever fetched. |
+| `local` | Always execute the published source in a child process. A tool with no source is an error. |
+| `auto` | Execute locally when source exists, otherwise fall back to the API. |
+
+An unrecognised value falls back to `remote`, so a typo cannot silently switch on
+code execution.
+
+**The threat model.** Executing a tool locally means executing code that arrived
+over the network. The sandbox from `@nexusbloom/core` gives the tool its own
+process, a SIGKILL deadline, a heap cap, and no access to this process's stdout.
+It is **isolation, not a security sandbox**: that code still runs with your user
+permissions and can read files, open sockets, and spawn processes.
+
+That is why it is off by default. An MCP server is driven by whatever the model
+decides to ask for, so the default posture has to be the one where a surprising
+tool call cannot become arbitrary code execution on a developer's machine. Turn it
+on when you trust the catalogue — a self-hosted deployment publishing only your
+own tools — or to keep working while the API is unreachable (`auto`).
+
+Enabling it prints the same warning to stderr at startup, once, because the
+threat model belongs on the record at the moment it is switched on.
+
+**Credentials are stripped from the child.** The sandbox forks the tool with the
+parent's environment minus anything whose name looks like a credential —
+`NEXUSBLOOM_API_KEY`, `STRIPE_SECRET_KEY`, `AWS_SESSION_TOKEN`, `*_PASSWORD`,
+`*_AUTH`, and so on, matched by substring. Tool code has no legitimate reason to
+read your API key, and without this a published tool could simply read it and
+exfiltrate it — which turns "runs with your permissions" into "runs with your
+account". Ordinary variables (`PATH`, project config, anything you have set) pass
+through untouched, so tools that read their own configuration still work.
+
+### Run history and diff
+
+Every run this server performs is recorded, so an agent can see what already
+happened instead of guessing:
+
+- `{"command":"history"}` — an index: run id, tool, status, duration, newest first.
+- `{"command":"history","show":"r3"}` — one run with its input and its result.
+- `{"command":"diff","from":"-2","to":"-1"}` — two runs compared field by field. `-1`
+  is the most recent run, `-2` the one before it, so comparing consecutive runs
+  needs no lookup.
+
+A diff leads with the verdict and flags changed inputs, because a result that
+moved because its *input* moved is not a regression — conflating the two is how a
+diff gets dismissed as noise and then ignored when it mattered.
+
+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.
+- **Inputs redacted.** Any key matching `key`, `secret`, `token`, `password`,
+  `auth`, `cookie` or `session` — plus `passwd`, `passphrase` and `credential` —
+  is masked before storage, at any depth up to 6 levels, without preserving
+  length. Beyond that depth the value is replaced with `[deep]` rather than
+  inspected, so a deeply nested payload cannot smuggle a credential past the
+  walk.
+
+The index is also readable as `nexusbloom://history`, for hosts that would rather
+pull it than call for it.
 
 ### Errors are actionable
 

package/index.js

@@ -24,6 +24,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { ApiClient } from "./src/client.js";
 import { candidateRoots, loadConfig } from "./src/config.js";
 import { checkConnectivity } from "./src/handlers.js";
+import { localExecutionNotice } from "./src/local.js";
 import { ManifestCache } from "./src/manifests.js";
 import { createServer } from "./src/server.js";
 
@@ -50,6 +51,12 @@ export async function main(env = process.env, deps = {}) {
   const connectivity = await checkConnectivity(app.client, candidateRoots(env), config, deps);
   process.stderr.write(`${connectivity.report}\n`);
 
+  // Printed once, before serving, and only when the operator opted in. The
+  // threat model belongs on the record at the moment it is enabled, not in a
+  // README nobody re-reads when a host later behaves strangely.
+  const notice = localExecutionNotice(config.execution);
+  if (notice) process.stderr.write(notice);
+
   const transport = new StdioServerTransport();
 
   // Close on the signals a host actually sends. Without this the process
@@ -66,7 +73,12 @@ export async function main(env = process.env, deps = {}) {
   process.once("SIGTERM", shutdown);
 
   await app.server.connect(transport);
-  process.stderr.write("NexusBloom MCP server running on stdio\n");
+  // Name the capabilities explicitly: a user debugging a host that shows no
+  // tools is usually looking at whether the host negotiated them, and a
+  // capability list on stderr answers that in one line.
+  process.stderr.write(
+    "NexusBloom MCP server running on stdio (capabilities: tools, resources, prompts)\n",
+  );
 
   return { ...app, transport, close: shutdown };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "2.0.2",
+  "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",
@@ -34,10 +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: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",
+    "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/config.js

@@ -1,3 +1,5 @@
+import { resolveExecutionMode } from "./local.js";
+
 /**
  * Configuration — resolved once, injected everywhere.
  *
@@ -108,6 +110,9 @@ export function loadConfig(env = process.env) {
   return {
     apiKey,
     apiBase: normaliseApiBase(env.NEXUSBLOOM_API_URL),
+    // Where tool code runs: "remote" (default), "local", or "auto". See local.js
+    // for why this is not a preference but a trust decision.
+    execution: resolveExecutionMode(env.NEXUSBLOOM_MCP_EXECUTION),
     timeoutMs,
     cacheTtlMs,
     debug,