@nexusbloom/mcp-server 2.0.0 → 2.1.0

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.
@@ -64,6 +65,154 @@ 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 session 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.
+- **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
 
@@ -107,19 +256,4 @@ server that explains itself on each request, not a process that exits or a host
 that concludes the server is broken. A failed catalogue refresh keeps serving the
 last good list rather than emptying it.
 
-## Development
-
-```bash
-npm test              # unit + integration, no network
-npm run test:coverage # with coverage
-npm run lint
-```
-
-The suite has **417 tests** at **100% line coverage** of `src/`. It includes
-end-to-end tests that drive the real server as a child process over stdio, using
-scripted miniature agents that discover, choose, read a schema and execute — the
-same loop a model runs, asserted on whether the *task* succeeded.
 
-No test touches the network: `NEXUSBLOOM_API_URL` is pointed at an unroutable
-`.invalid` host and every HTTP client is injected, so the suite cannot pass
-while production is broken, and cannot fail because production is down.

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,7 +1,7 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "2.0.0",
-  "description": "MCP server for NexusBloom — agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
+  "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.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -34,7 +34,12 @@
     "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",
     "lint": "node --check index.js && for f in src/*.js; do node --check \"$f\" || exit 1; done"
   }
 }

package/src/client.js

@@ -41,6 +41,15 @@ export class ApiClient {
     // not fire (some fetch polyfills). Whichever rejects first wins; the loser
     // is an unhandled rejection we must not let crash the process.
     this._inFlight = new Set();
+
+    /**
+     * Most recent rate-limit state reported by the API, as
+     * `{remaining, limit, reset}`. Anonymous execution is capped per minute, so
+     * an agent benefits from seeing its own budget rather than discovering it
+     * as a 429.
+     * @type {{remaining: number|null, limit: number|null, reset: string|null}|null}
+     */
+    this.rateLimit = null;
   }
 
   /**
@@ -61,12 +70,13 @@ export class ApiClient {
     const headers = { Accept: "application/json" };
     if (body !== undefined) headers["Content-Type"] = "application/json";
     if (auth && this.config.apiKey) headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    Object.assign(headers, opts.headers || {});
 
     // Own controller so an external signal can cancel too, and so the timer is
     // always cleared — a leaked timer keeps the event loop alive and the MCP
     // server never exits cleanly.
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? this.config.timeoutMs);
     this._inFlight.add(controller);
 
     const onExternalAbort = () => controller.abort();
@@ -106,6 +116,23 @@ export class ApiClient {
   async _decode(res, ctx) {
     const text = await res.text().catch(() => "");
 
+    // Capture quota state before any early return. The API advertises these for
+    // CORS exposure but nothing consumed them, so agents hit 429 blind.
+    // `Number(null)` is 0, so an absent header must be rejected explicitly —
+    // otherwise a client with full quota would be told it has none left.
+    const numHeader = (name) => {
+      const raw = res.headers?.get?.(name);
+      if (raw === null || raw === undefined || raw === "") return null;
+      const n = Number(raw);
+      return Number.isFinite(n) ? n : null;
+    };
+
+    this.rateLimit = {
+      remaining: numHeader("x-ratelimit-remaining"),
+      limit: numHeader("x-ratelimit-limit"),
+      reset: res.headers?.get?.("x-ratelimit-reset") ?? null,
+    };
+
     let parsed = null;
     if (text) {
       try {

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,