@nexusbloom/mcp-server 2.0.0 → 2.1.0

package/src/prompts.js

@@ -0,0 +1,282 @@
+/**
+ * MCP Prompts — workflow recipes a host can offer the user as one-click starts.
+ *
+ * A prompt here is not a canned instruction. Each one is assembled against the
+ * live catalogue, so `use-tool` carries *this* deployment's parameter names and a
+ * call that is already valid, and `find-tool` carries the tools that actually
+ * exist rather than a description of tools that might. That is the difference
+ * between a prompt that saves the user a turn and one that just adds words to
+ * their context.
+ *
+ * Kept SDK-free, like handlers.js and resources.js: `prompts/list` and
+ * `prompts/get` are plain async functions, and server.js is the only place the
+ * protocol lives.
+ */
+
+import { searchTools, suggest } from "./discovery.js";
+import { ErrorCode, NexusBloomError } from "./errors.js";
+import { buildExampleArgs, formatParameterList } from "./render.js";
+import { CATALOGUE_URI, toolUri } from "./resources.js";
+
+/** How many candidates a prompt embeds. Past this it is a catalogue dump. */
+const MAX_CANDIDATES = 8;
+
+/**
+ * The advertised prompts.
+ *
+ * Four, in the order a user meets them: find the tool, use the tool, plan a
+ * multi-step task, recover from a failure.
+ */
+export const PROMPT_DEFINITIONS = [
+  {
+    name: "find-tool",
+    title: "Find a NexusBloom tool",
+    description: "Locate the tools that can accomplish a stated goal, ranked by intent.",
+    arguments: [{ name: "goal", description: "What you want to accomplish, in plain language.", required: true }],
+  },
+  {
+    name: "use-tool",
+    title: "Use a specific NexusBloom tool",
+    description: "Get the exact parameters, a valid example call, and the recovery paths for one tool.",
+    arguments: [{ name: "slug", description: "Tool slug, e.g. env-validator.", required: true }],
+  },
+  {
+    name: "plan-batch",
+    title: "Plan a multi-tool task",
+    description: "Break a task into NexusBloom runs and shape them into one batched call.",
+    arguments: [{ name: "task", description: "The task to accomplish, in plain language.", required: true }],
+  },
+  {
+    name: "recover",
+    title: "Recover from a NexusBloom failure",
+    description: "Explain what a failure means and what to do next.",
+    arguments: [
+      { name: "error", description: "The error message or code you received.", required: false },
+      { name: "slug", description: "The tool you were calling, if any.", required: false },
+    ],
+  },
+];
+
+/**
+ * Assemble the prompt handlers over a manifest cache.
+ *
+ * @param {object} deps
+ * @param {import("./manifests.js").ManifestCache} deps.cache
+ * @returns {{listPrompts: Function, getPrompt: Function, names: string[]}}
+ */
+export function createPrompts({ cache }) {
+  async function listPrompts() {
+    return { prompts: PROMPT_DEFINITIONS };
+  }
+
+  async function getPrompt(params) {
+    const name = params?.name;
+    const args = params?.arguments ?? {};
+
+    switch (name) {
+      case "find-tool":
+        return text("Tools matching your goal, with a valid call for the best one", await findToolPrompt(requireArg(args, "goal", name), cache));
+      case "use-tool":
+        return text("One tool's exact parameters and a valid call", await useToolPrompt(requireArg(args, "slug", name), cache));
+      case "plan-batch":
+        return text("A batched plan for a multi-tool task", await planBatchPrompt(requireArg(args, "task", name), cache));
+      case "recover":
+        return text("What a failure means and what to do next", await recoverPrompt(args, cache));
+      default:
+        throw new NexusBloomError(
+          `Unknown prompt "${name ?? ""}". Available: ${PROMPT_DEFINITIONS.map((p) => p.name).join(", ")}.`,
+          ErrorCode.NOT_FOUND,
+        );
+    }
+  }
+
+  return { listPrompts, getPrompt, names: PROMPT_DEFINITIONS.map((p) => p.name) };
+}
+
+/**
+ * Wrap body text as a single user message.
+ *
+ * `user`, not `assistant`: a prompt is something the host hands to the model as
+ * the human's request, and getting the role wrong makes a host either suppress it
+ * or render it as the model's own prior output.
+ */
+function text(description, body) {
+  return { description, messages: [{ role: "user", content: { type: "text", text: body } }] };
+}
+
+/** A required argument, with the prompt name in the error so the host can show it. */
+function requireArg(args, key, prompt) {
+  const value = (args?.[key] ?? "").trim();
+  if (!value) {
+    throw new NexusBloomError(
+      `The "${prompt}" prompt needs a "${key}" argument.`,
+      ErrorCode.INVALID_ARGS,
+    );
+  }
+  return value;
+}
+
+/** One line per candidate, reusing the description an agent would see in a list. */
+function candidateLines(tools) {
+  return tools
+    .map((t) => {
+      const required = t.input_schema?.required || [];
+      const shape = required.length
+        ? `${required.length} required of ${Object.keys(t.input_schema?.properties || {}).length} params`
+        : "no required params";
+      return `- \`${t.slug}\` — ${t.short_description || "No description"} (${shape})`;
+    })
+    .join("\n");
+}
+
+async function findToolPrompt(goal, cache) {
+  const tools = await cache.tools();
+  const ranked = searchTools(tools, goal, { limit: MAX_CANDIDATES, includeAll: false });
+
+  const body = ranked.length
+    ? `Ranked by how well they match "${goal}":\n\n${candidateLines(ranked)}`
+    : `Nothing in the catalogue scored against "${goal}". The catalogue holds ${tools.length} tools; ` +
+      `try broader wording (drop the tool-specific noun), or read ${CATALOGUE_URI} and pick from the list.`;
+
+  return `Find the NexusBloom tool that accomplishes this goal, then use it.
+
+**Goal:** ${goal}
+
+${body}
+
+Do this:
+1. Pick the best match above. If two are plausible, read both manifests before choosing.
+2. Read the winner's full manifest at \`${toolUri("<slug>")}\` — it has the exact parameter names and a valid example.
+3. Call the tool directly by slug with your own values.
+4. If a candidate looks wrong, do not guess a new slug. Run \`{"command":"search","query":"…"}\` with different wording.
+
+Catalogue: ${CATALOGUE_URI}`;
+}
+
+async function useToolPrompt(slug, cache) {
+  const tools = await cache.tools();
+  const match = exactMatch(tools, slug);
+
+  if (!match) {
+    // Same recovery the tool path gives, so a user who picked the wrong prompt
+    // lands on the same next step.
+    const near = suggest(tools, slug).map((t) => t.slug);
+    return `No tool named "${slug}" is published.${near.length ? ` Did you mean: ${near.join(", ")}?` : ""}
+
+The catalogue holds ${tools.length} tools. Read ${CATALOGUE_URI} for the full list, or call the
+\`nexusbloom\` meta-tool with \`{"command":"search","query":"<what you need>"}\` to rank by intent.
+
+Then call the tool you choose directly by slug.`;
+  }
+
+  const required = match.input_schema?.required || [];
+  const example = buildExampleArgs(match);
+
+  return `Use the \`${match.slug}\` tool.
+
+**${match.name}** — ${match.short_description || "No description"}
+${match.category && match.category !== "uncategorized" ? `Category: ${match.category}\n` : ""}${match.tags?.length ? `Tags: ${match.tags.join(", ")}\n` : ""}
+${required.length === 0 ? "Takes no required parameters." : `Required: ${required.join(", ")}`}
+
+Parameters:
+${formatParameterList(match.input_schema)}
+
+Valid call — replace the example values, keep the shape:
+\`\`\`json
+{ "name": "${match.slug}", "arguments": ${JSON.stringify(example, null, 2)} }
+\`\`\`
+
+${match.output_schema ? `Expected output shape:\n\`\`\`json\n${JSON.stringify(match.output_schema, null, 2)}\n\`\`\`\n` : ""}If a call fails, read the error rather than retrying it: a validation failure names the
+offending field, an unknown slug suggests the right one, and a timeout is marked
+\`retryable\`. Full manifest: ${toolUri(match.slug)}`;
+}
+
+async function planBatchPrompt(task, cache) {
+  const tools = await cache.tools();
+  const candidates = searchTools(tools, task, { limit: MAX_CANDIDATES, includeAll: false });
+  const relevant = candidates.length ? candidates : tools.slice(0, MAX_CANDIDATES);
+
+  return `Plan and run this task with NexusBloom, batching what belongs together.
+
+**Task:** ${task}
+
+Likely participants:
+${candidateLines(relevant)}
+
+How to plan it:
+1. Decide what the task actually requires. A task that one tool covers should be a direct call — batching one run only adds framing.
+2. Read each chosen tool's manifest at \`${toolUri("<slug>")}\` and collect its required parameters *before* running anything.
+3. Put the runs in one call, in dependency order, when two or more tools contribute:
+
+\`\`\`json
+{ "command": "batch", "runs": [
+  { "slug": "<slug>", "params": { … } },
+  { "slug": "<slug>", "params": { … } }
+] }
+\`\`\`
+
+4. Read the tally first. Failures are listed above successes, and each is independent — fix those inputs and re-run only those slugs.
+
+Two rules that are not obvious:
+- A batch is validated as a whole before anything runs, so an unresolvable slug or a missing required
+  field costs zero quota and rejects the batch. Get the arguments right first.
+- Maximum 10 runs per batch. More than that and anonymous callers hit the 30 requests/minute cap.
+
+Catalogue: ${CATALOGUE_URI}`;
+}
+
+async function recoverPrompt({ error, slug }, cache) {
+  const parts = [`A NexusBloom call failed. Work out why before retrying — most failures need a different call, not the same one again.`];
+
+  if (error) parts.push(`**Reported:** ${error}`);
+
+  if (slug) {
+    const tools = await cache.tools();
+    const match = exactMatch(tools, slug);
+    if (match) {
+      const example = buildExampleArgs(match);
+      const required = match.input_schema?.required || [];
+      parts.push(
+        `**Tool:** \`${match.slug}\`\n\nIts exact parameters:\n${formatParameterList(match.input_schema)}\n\n` +
+          `Valid call shape:\n\`\`\`json\n{ "name": "${match.slug}", "arguments": ${JSON.stringify(example, null, 2)} }\n\`\`\`` +
+          (required.length
+            ? `\n\nEvery one of these is required: ${required.join(", ")}.`
+            : "\n\nThis tool has no required parameters, so a failure here is about the value, not a missing field."),
+      );
+    } else {
+      const near = suggest(tools, slug).map((t) => t.slug);
+      parts.push(
+        `**Tool:** \`${slug}\` is not in the catalogue.` +
+          (near.length ? ` Closest: ${near.join(", ")}.` : "") +
+          ` Read ${CATALOGUE_URI} or search by intent.`,
+      );
+    }
+  }
+
+  parts.push(
+    `## What each code means
+
+| Code | Meaning | What to do |
+|---|---|---|
+| \`TOOL_NOT_FOUND\` | The slug is not published, or an abbreviation matched several tools. | Use the candidate the error named, or \`{"command":"search","query":"…"}\`. |
+| \`VALIDATION_FAILED\` | Input did not match the tool's schema. | Fix the named field. The message lists every missing one. Do not retry unchanged. |
+| \`TIMEOUT\` | The API did not answer in time. | \`retryable\`. Retry once; if it times out again, the payload is probably too large. |
+| \`RATE_LIMITED\` | 30 requests/minute, anonymous only. | Pace down. Fewer, larger calls: batch rather than looping. |
+| \`UNAUTHORIZED\` | A key is set but invalid. | Check \`NEXUSBLOOM_API_KEY\`. |
+| \`API_ERROR\` | The API failed. | \`retryable\`. If it persists, the deployment is down — say so rather than looping. |
+
+## The rules that save the most time
+
+- Never guess a slug. Search by intent, or read ${CATALOGUE_URI}.
+- A tool-reported \`{"success":false}\` is the tool's own answer, not a transport failure — the call worked.
+- Read \`{"command":"schema","slug":"…"}\` before retrying a validation failure; do not re-derive the schema from memory.`,
+  );
+
+  return parts.join("\n\n");
+}
+
+/** Exact slug match only. A prompt is a deliberate choice; do not auto-resolve it. */
+function exactMatch(tools, slug) {
+  const wanted = (slug || "").trim().toLowerCase();
+  return tools.find((t) => t.slug.toLowerCase() === wanted) || null;
+}

package/src/render.js

@@ -17,6 +17,7 @@
 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.
@@ -26,7 +27,9 @@ import { normaliseTool } from "./manifests.js";
  * over prose gets an exact payload instead of parsing markdown.
  */
 export function respond(payload) {
-  const content = [{ type: "text", text: payload.text }];
+  // 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",
@@ -116,9 +119,10 @@ export function renderToolList(tools, { total } = {}) {
  */
 export function renderSearchResults(query, tools, catalogueSize, categories = []) {
   if (tools.length === 0) {
-    const categoryHint = categories.length
-      ? `\n• A category name: ${categories.slice(0, 8).join(", ")}`
-      : "";
+    // "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` +
@@ -155,18 +159,10 @@ export function renderSchema(rawSchema, tools = []) {
   // literal string "undefined".
   const schema = normaliseTool({ slug: "tool", ...rawSchema }) || normaliseTool({ slug: "tool" });
 
+  const paramLines = formatParameterList(schema.input_schema);
   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;
@@ -212,6 +208,24 @@ export function renderSchema(rawSchema, tools = []) {
   return { text, data: schema };
 }
 
+/**
+ * Parameter bullet lines for an input schema.
+ *
+ * Exported because the `schema` response and the `use-tool` prompt both have to
+ * describe a tool's parameters, and two formatters would drift — a prompt that
+ * omits a `minLength` the tool actually enforces is worse than no prompt.
+ */
+export function formatParameterList(inputSchema) {
+  const params = describeParameters(inputSchema);
+  if (!params.length) return "_This tool takes no parameters._";
+  return params
+    .map((p) => {
+      const detail = p.description ? ` — ${p.description}` : "";
+      return `- \`${p.name}\` (${p.summary || "any"})${detail}`;
+    })
+    .join("\n");
+}
+
 /** Describe an output schema's top-level shape in one clause. */
 function describeOutputShape(schema) {
   const props = schema?.properties || {};
@@ -282,14 +296,145 @@ function placeholderFor(prop) {
  * 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" } = {}) {
+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`);
 
-  return {
+  // 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,
+  };
+}
+
+/**
+ * The recorded run log.
+ *
+ * Results are omitted here: this is an index for deciding which two runs to
+ * 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 } = {}) {
+  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 },
+    };
+  }
+
+  const lines = runs.map((r) => {
+    const state = r.ok ? "ok" : `FAILED (${r.code || "error"})`;
+    const ms = typeof r.durationMs === "number" ? ` · ${r.durationMs}ms` : "";
+    return `- \`${r.id}\` ${r.tool} · ${state}${ms}${r.truncated ? " · result truncated" : ""}`;
+  });
+
+  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` +
+    `---\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 } };
+}
+
+/** One run in full, with its result. */
+export function renderRun(run) {
+  const head =
+    `# Run ${run.id} — ${run.tool}\n\n` +
+    [
+      `Status: ${run.ok ? "ok" : `FAILED (${run.code || "error"})`}`,
+      `At: ${run.at}`,
+      run.durationMs !== null ? `Duration: ${run.durationMs}ms` : null,
+      run.batch ? "Part of a batch" : null,
+    ]
+      .filter(Boolean)
+      .join(" · ");
+
+  const body = run.ok
+    ? "```json\n" + safeStringify(run.result) + "\n```"
+    : `${run.error}${run.retryable ? "\n\nThis failure is marked retryable." : "\n\nThis failure is not retryable — change the call before trying again."}`;
+
+  const input = `Input (credential-shaped values are redacted):\n\`\`\`json\n${safeStringify(run.params)}\n\`\`\``;
+
+  return {
+    text: `${head}\n\n${input}\n\n${body}`,
+    data: run,
+  };
+}
+
+/**
+ * A comparison of two runs.
+ *
+ * Leads with the verdict, then the inputs, then the field-level changes: the
+ * first question is "did anything change at all", and an agent that has to read
+ * forty diff lines to answer that will skim them and get it wrong.
+ */
+export function renderDiff({ from, to, identical, inputsChanged, changes, truncated }) {
+  const verdict = identical
+    ? "Identical — the two runs produced the same result."
+    : `${changes.length} difference${changes.length === 1 ? "" : "s"}.`;
+
+  const lines = changes.map((c) => {
+    if (c.type === "added") return `- \`${c.path}\` — added: ${safeStringify(c.to)}`;
+    if (c.type === "removed") return `- \`${c.path}\` — removed: ${safeStringify(c.from)}`;
+    return `- \`${c.path}\` — changed: ${safeStringify(c.from)} → ${safeStringify(c.to)}`;
+  });
+
+  const sections = [
+    `# Diff: ${from.id} → ${to.id}\n\n${verdict}`,
+    `**From:** \`${from.id}\` ${from.tool} · ${from.ok ? "ok" : "failed"}${from.durationMs !== null ? ` · ${from.durationMs}ms` : ""}\n` +
+      `**To:** \`${to.id}\` ${to.tool} · ${to.ok ? "ok" : "failed"}${to.durationMs !== null ? ` · ${to.durationMs}ms` : ""}`,
+  ];
+
+  if (inputsChanged) {
+    sections.push(
+      `**Inputs differ.** A result that changed because its input changed is not a regression — check the inputs before concluding the tool changed behaviour.`,
+    );
+  }
+
+  if (truncated) {
+    sections.push(
+      `> One payload was truncated at the ${8_000}-character cap, so differences beyond that point are not reported.`,
+    );
+  }
+
+  sections.push(
+    identical ? "No field-level differences." : `## Changes\n\n${lines.join("\n")}`,
+  );
+
+  return {
+    text: sections.join("\n\n"),
+    data: { from, to, identical, inputsChanged, changes, ...(truncated ? { truncated: true } : {}) },
   };
 }
 
@@ -306,6 +451,80 @@ export function renderToolReportedError(slug, data) {
   };
 }
 
+/**
+ * A batch of runs.
+ *
+ * Laid out so the failures come first: in a batch, the interesting output is
+ * whichever item broke, and burying that under five successful JSON blobs is how
+ * a bug gets missed. Each result keeps its own payload, so a caller that needs
+ * everything still has it — the ordering is for the reader, the data block is for
+ * the machine.
+ */
+export function renderBatch({ runs, results, durationMs } = {}) {
+  const items = results || [];
+  const ok = items.filter((r) => r.success);
+  const failed = items.filter((r) => !r.success);
+
+  const header = [
+    `# Batch: ${ok.length}/${items.length} succeeded`,
+    `Runs: ${items.length} · Failed: ${failed.length}` +
+      (typeof durationMs === "number" ? ` · Duration: ${durationMs}ms` : ""),
+  ].join("\n\n");
+
+  const sections = [];
+
+  if (failed.length) {
+    sections.push(
+      `## Failed\n\n` +
+        failed
+          .map(
+            (r) =>
+              `- **${r.slug}** — ${r.error}` +
+              (r.code ? ` (\`${r.code}\`)` : "") +
+              (r.retryable ? " · retryable" : ""),
+          )
+          .join("\n"),
+    );
+  }
+
+  if (ok.length) {
+    sections.push(
+      `## Succeeded\n\n` +
+        ok
+          .map(
+            (r) =>
+              `### ${r.slug}\n\n` +
+              (typeof r.durationMs === "number" ? `\`${r.durationMs}ms\`\n\n` : "") +
+              "```json\n" +
+              safeStringify(r.data) +
+              "\n```",
+          )
+          .join("\n\n"),
+    );
+  }
+
+  if (!items.length) {
+    return {
+      text: `${header}\n\nNothing ran.`,
+      data: { results: [], succeeded: 0, failed: 0 },
+    };
+  }
+
+  const next = failed.length
+    ? `\n\n---\nEach failure above is independent: the other runs completed. Fix the listed inputs and re-run only those slugs.`
+    : "";
+
+  return {
+    text: `${header}\n\n${sections.join("\n\n")}${next}`,
+    data: {
+      success: failed.length === 0,
+      succeeded: ok.length,
+      failed: failed.length,
+      results: items,
+    },
+  };
+}
+
 function safeStringify(value) {
   try {
     return JSON.stringify(value, null, 2);