@nexusbloom/mcp-server 2.0.2 → 2.1.1

package/src/handlers.js

@@ -18,9 +18,13 @@ 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,
+  renderDiff,
+  renderHistory,
+  renderRun,
   renderResult,
   respond,
   respondError,
@@ -30,6 +34,29 @@ import {
   renderToolReportedError,
 } from "./render.js";
 import { assertValidInput, coerceParams } from "./validate.js";
+import { RunHistory, summariseRun } from "./history.js";
+import { runLocal } from "./local.js";
+
+/**
+ * Unwrap the `{ success, data }` envelope the API wraps run results in.
+ *
+ * The check is for key *presence*, not truthiness. `body?.data ?? body` looks
+ * equivalent and is not: a tool whose result is legitimately `null` — an
+ * empty match set, a validator that found nothing — came back as
+ * `{ success: true, data: null }`, and `??` treats that null as "absent" and
+ * hands the agent the entire envelope as its result. It then renders
+ * `{"success":true,"data":null}` where the answer should have been `null`, which
+ * is the kind of wrong-but-plausible output an agent will build a conclusion on.
+ *
+ * @param {any} body the parsed response body
+ * @returns {any} the payload, or the body unchanged when it is not enveloped
+ */
+export function unwrapData(body) {
+  if (body && typeof body === "object" && !Array.isArray(body) && "data" in body) {
+    return body.data;
+  }
+  return body;
+}
 
 /**
  * Assemble a handler set over a client and a manifest cache.
@@ -39,7 +66,10 @@ import { assertValidInput, coerceParams } from "./validate.js";
  * @param {ManifestCache}  deps.cache
  * @param {object}         deps.config
  */
-export function createHandlers({ client, cache, config }) {
+export function createHandlers({ client, cache, config, history: providedHistory }) {
+  // One log per handler set. Injected so a test can assert on a deterministic
+  // clock, and so a host that restarts the server does not inherit a stale log.
+  const history = providedHistory ?? new RunHistory();
   /**
    * Look up a tool by exact slug or unambiguous abbreviation.
    *
@@ -89,7 +119,7 @@ export function createHandlers({ client, cache, config }) {
       if (tools.length === 0) {
         const result = await client
           .request(`/run/${encodeURIComponent(slug.trim())}`, { method: "POST", body: params })
-          .then((body) => ({ success: true, data: body?.data ?? body }))
+          .then((body) => ({ success: true, data: unwrapData(body) }))
           .catch((err) => {
             throw enrichNotFound(err, slug.trim(), []);
           });
@@ -112,19 +142,80 @@ export function createHandlers({ client, cache, config }) {
     assertValidInput(params, inputSchema, tool.slug);
 
     const startedAt = Date.now();
+
+    // Local execution, when the operator has opted in. Decided before the request
+    // so a `local` run never touches /api/run at all, and an `auto` run falls
+    // through to the remote path below when no source is published.
+    const local = await runLocal({
+      client,
+      slug: tool.slug,
+      params,
+      mode: config?.execution ?? "remote",
+      config,
+      deps: opts.deps,
+    });
+
+    if (local.executed) {
+      const durationMs = Date.now() - startedAt;
+      history.record({
+        tool: tool.slug,
+        params,
+        data: local.data,
+        ok: true,
+        durationMs,
+        batch: Boolean(opts.batch),
+      });
+      return {
+        success: true,
+        data: local.data,
+        tool: tool.slug,
+        execution: "local",
+        durationMs,
+        rateLimit: null,
+      };
+    }
+
     // The run endpoint records usage itself, so attribution rides on a header
     // rather than a second tracking call — a separate POST would either be a
     // no-op anonymously or double-count once authenticated.
-    const body = await client.request(`/run/${encodeURIComponent(tool.slug)}`, {
-      method: "POST",
-      body: params,
-      headers: { "X-NexusBloom-Source": "mcp" },
-    });
+    let body;
+    try {
+      body = await client.request(`/run/${encodeURIComponent(tool.slug)}`, {
+        method: "POST",
+        body: params,
+        headers: { "X-NexusBloom-Source": "mcp" },
+      });
+    } catch (err) {
+      // Failures are recorded too: a log that only holds successes cannot explain
+      // why an agent is retrying, which is the main reason to keep one.
+      const nxb = asNexusBloomError(err);
+      history.record({
+        tool: tool.slug,
+        params,
+        ok: false,
+        durationMs: Date.now() - startedAt,
+        error: nxb.message,
+        code: nxb.code,
+        retryable: nxb.retryable ?? false,
+        batch: Boolean(opts.batch),
+      });
+      throw err;
+    }
     const durationMs = Date.now() - startedAt;
+    const data = unwrapData(body);
+
+    history.record({
+      tool: tool.slug,
+      params,
+      data,
+      ok: true,
+      durationMs,
+      batch: Boolean(opts.batch),
+    });
 
     return {
       success: true,
-      data: body?.data ?? body,
+      data,
       tool: tool.slug,
       execution: "remote",
       durationMs,
@@ -133,7 +224,7 @@ export function createHandlers({ client, cache, config }) {
   }
 
   /** Meta-tool: discover, inspect, or run. */
-  async function meta(args) {
+  async function meta(args, { onProgress } = {}) {
     const command = args?.command;
 
     if (!command) {
@@ -193,6 +284,36 @@ export function createHandlers({ client, cache, config }) {
       return respond(renderSchema(schema, tools));
     }
 
+    if (command === "batch") {
+      const batch = await runBatch(args?.runs, { onProgress });
+      return respond(renderBatch(batch));
+    }
+
+    if (command === "history") {
+      // `show` narrows to one run; otherwise this is an index of what ran.
+      if (args?.show) {
+        const run = history.find(args.show);
+        if (!run) throw unknownRun(history, args.show);
+        return respond(renderRun(run));
+      }
+      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, scope: history.scope() }));
+    }
+
+    if (command === "diff") {
+      const from = args?.from ?? "-2";
+      const to = args?.to ?? "-1";
+      if (!history.list().length) {
+        throw new NexusBloomError(
+          "No runs are recorded yet, so there is nothing to compare. Run a tool first — " +
+            'history is in memory only and starts empty on every server start.',
+          ErrorCode.INVALID_ARGS,
+        );
+      }
+      return respond(renderDiff(history.diff(from, to)));
+    }
+
     // run
     const slug = (args?.slug || "").trim();
     if (!slug) {
@@ -205,6 +326,113 @@ export function createHandlers({ client, cache, config }) {
     return respondResult(result);
   }
 
+  /**
+   * Run several tools in one call.
+   *
+   * Two properties make this worth having over N direct calls:
+   *
+   * 1. **Resolution happens up front.** Every slug is resolved and every schema
+   *    validated before the first run, so a typo in item four costs zero quota
+   *    rather than three runs. A batch is one intent, so a malformed batch is an
+   *    error, not eight partial results.
+   * 2. **Failures are isolated.** Once past resolution, each run is independent:
+   *    one tool erroring must not discard the seven results that worked, because
+   *    the whole point of batching is getting all of them in one turn.
+   */
+  async function runBatch(runs, { onProgress } = {}) {
+    const specs = normaliseBatchInput(runs);
+    const total = specs.length;
+
+    // Phase 1 — resolve and validate everything.
+    const tools = await cache.tools();
+    const planned = [];
+    const unknown = [];
+
+    for (const spec of specs) {
+      const { tool, ambiguous } = resolveSlugStrict(tools, spec.slug);
+      if (!tool) {
+        // An ambiguous prefix is a different mistake from a typo, and the
+        // recovery differs: candidates the agent must choose between, versus a
+        // near match it can just use. Both are recorded so one message can carry
+        // the right hint for each.
+        const candidates = [
+          ...new Set([
+            ...ambiguous.map((t) => t.slug),
+            ...suggest(tools, spec.slug).map((t) => t.slug),
+          ]),
+        ].slice(0, 3);
+        unknown.push({ slug: spec.slug, candidates });
+        continue;
+      }
+      planned.push({ spec, tool });
+    }
+
+    if (unknown.length) {
+      const parts = unknown.map(({ slug, candidates }) =>
+        candidates.length ? `"${slug}" → ${candidates.join(" or ")}` : `"${slug}" (no close match)`,
+      );
+      throw new NexusBloomError(
+        `Nothing in the batch ran. Unresolvable: ${parts.join("; ")}. ` +
+          `Call {"command":"search","query":"<what you need>"} or {"command":"list"}.`,
+        ErrorCode.INVALID_ARGS,
+        { details: { unknown: unknown.map((u) => u.slug) } },
+      );
+    }
+
+    // Coerce and validate before spending anything, matching the single-call path.
+    const validated = [];
+    for (const { spec, tool } of planned) {
+      const params = coerceParams(spec.params, tool.slug);
+      let inputSchema = tool.input_schema;
+      try {
+        const manifest = await cache.manifest(tool.slug);
+        inputSchema = manifest.input_schema || inputSchema;
+      } catch {
+        /* the list schema is good enough; the API is authoritative anyway */
+      }
+      assertValidInput(params, inputSchema, tool.slug);
+      validated.push({ slug: tool.slug, params });
+    }
+
+    // Phase 2 — run, isolating failures.
+    const startedAt = Date.now();
+    const results = [];
+
+    await onProgress?.({ progress: 0, total, message: `Running ${total} tool${total === 1 ? "" : "s"}…` });
+
+    for (const [index, run] of validated.entries()) {
+      try {
+        const result = await execute(run.slug, run.params, { batch: true });
+        const data = result.data;
+        const reported = data && typeof data === "object" && (data.success === false || (data.error && !data.data));
+        results.push({
+          slug: run.slug,
+          success: !reported,
+          data,
+          durationMs: result.durationMs,
+          ...(reported ? { error: data.error || data.message || "The tool reported an error.", code: data.code } : {}),
+        });
+      } catch (err) {
+        const nxb = asNexusBloomError(err);
+        results.push({
+          slug: run.slug,
+          success: false,
+          error: nxb.message,
+          code: nxb.code,
+          retryable: nxb.retryable ?? false,
+        });
+      }
+
+      await onProgress?.({
+        progress: index + 1,
+        total,
+        message: `Finished ${run.slug} (${index + 1}/${total})`,
+      });
+    }
+
+    return { runs: validated.length, results, durationMs: Date.now() - startedAt };
+  }
+
   /** Direct invocation by tool slug. */
   async function callDirect(name, args) {
     const result = await execute(name, args ?? {});
@@ -221,8 +449,22 @@ export function createHandlers({ client, cache, config }) {
   }
 
   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,
     callDirect,
     execute,
     findTool,
@@ -231,7 +473,69 @@ export function createHandlers({ client, cache, config }) {
 }
 
 /** The meta-tool's accepted commands, used in errors and tests. */
-export const META_COMMANDS = ["list", "search", "schema", "run"];
+export const META_COMMANDS = ["list", "search", "schema", "run", "batch", "history", "diff"];
+
+/**
+ * How many runs one batch may contain.
+ *
+ * Bounded because anonymous execution is capped at 30 requests/minute: a batch of
+ * fifty would spend the whole budget in one turn and 429 the user's next ten
+ * calls. Ten is enough for the real tasks (validate, lint, transform a set of
+ * files) and leaves headroom.
+ */
+export const MAX_BATCH_SIZE = 10;
+
+/**
+ * Validate the batch argument and return `{slug, params}` specs.
+ *
+ * A single malformed entry rejects the whole batch, because a batch is one
+ * intent — silently dropping item three would return a result set the caller
+ * cannot reconcile with what it asked for.
+ */
+export function normaliseBatchInput(runs) {
+  if (!Array.isArray(runs) || runs.length === 0) {
+    throw new NexusBloomError(
+      `Missing "runs" for batch. Example: ` +
+        `{"command":"batch","runs":[{"slug":"env-validator","params":{"env_content":"DEBUG=true"}}]}`,
+      ErrorCode.INVALID_ARGS,
+    );
+  }
+  if (runs.length > MAX_BATCH_SIZE) {
+    throw new NexusBloomError(
+      `A batch may contain at most ${MAX_BATCH_SIZE} runs; got ${runs.length}. ` +
+        `Split it — or run them as direct tool calls, which do not share this cap.`,
+      ErrorCode.INVALID_ARGS,
+    );
+  }
+
+  return runs.map((entry, i) => {
+    // `{slug}` alone is accepted; params defaults to {} for a no-argument tool.
+    const spec = typeof entry === "string" ? { slug: entry } : entry;
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+      throw new NexusBloomError(
+        `runs[${i}] must be an object like {"slug":"…","params":{…}}, or a slug string.`,
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+    const slug = typeof spec.slug === "string" ? spec.slug.trim() : "";
+    if (!slug) {
+      throw new NexusBloomError(`runs[${i}] is missing a "slug".`, ErrorCode.INVALID_ARGS);
+    }
+    return { slug, params: spec.params ?? {} };
+  });
+}
+
+/** A run reference that is not in the log, with the ids that are. */
+export function unknownRun(history, ref) {
+  const known = history.list().map((r) => r.id);
+  return new NexusBloomError(
+    `No run recorded for "${ref}". ` +
+      `Known run ids: ${known.join(", ") || "(none yet)"}. ` +
+      `Pass an id, or -1 for the most recent run.`,
+    ErrorCode.NOT_FOUND,
+    { details: { known } },
+  );
+}
 
 /**
  * Build a not-found error that tells the agent what to do next.
@@ -277,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*
@@ -290,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,
@@ -303,9 +616,15 @@ export function buildToolList(cache) {
         "Use this instead of guessing a slug:\n" +
         '- {"command":"search","query":"validate environment file"} — rank tools by intent\n' +
         '- {"command":"list"} — every published tool, one line each\n' +
-        '- {"command":"schema","slug":"<slug>"} — exact parameters plus a ready-to-send example\n\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 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.",
+        "parameters as arguments — this tool is for when you do not yet know which one to use.\n\n" +
+        "If your host supports MCP resources, the same information is readable without a " +
+        'call: "nexusbloom://catalogue" lists every tool, "nexusbloom://tools/{slug}" ' +
+        'carries one full manifest, and "nexusbloom://guide" explains the recovery paths.',
       inputSchema: {
         type: "object",
         properties: {
@@ -313,7 +632,9 @@ export function buildToolList(cache) {
             type: "string",
             enum: META_COMMANDS,
             description:
-              "list: all tools. search: find by intent. schema: a tool's parameters. run: execute a tool.",
+              "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 server process has run, and since when. diff: compare two recorded runs.",
           },
           slug: {
             type: "string",
@@ -329,6 +650,36 @@ export function buildToolList(cache) {
             type: "object",
             description: "Input parameters for 'run', matching the tool's input schema.",
           },
+          show: {
+            type: "string",
+            description:
+              "Run id for 'history' — a single run with its input and result. " +
+              '-1 is the most recent, -2 the one before it.',
+          },
+          from: {
+            type: "string",
+            description: "Run id or negative index for 'diff'. Default \"-2\".",
+          },
+          to: {
+            type: "string",
+            description: "Run id or negative index for 'diff'. Default \"-1\".",
+          },
+          runs: {
+            type: "array",
+            description:
+              "Up to 10 entries for 'batch', each {\"slug\":\"…\",\"params\":{…}}. " +
+              "A bare slug string is accepted for a tool that takes no arguments. " +
+              "All slugs are resolved and validated before anything runs, so a typo costs no quota.",
+            maxItems: MAX_BATCH_SIZE,
+            items: {
+              type: "object",
+              properties: {
+                slug: { type: "string", description: "Tool slug." },
+                params: { type: "object", description: "That tool's input parameters." },
+              },
+              required: ["slug"],
+            },
+          },
           limit: {
             type: "integer",
             description: "Maximum results for 'search'. Default 10.",