@nexusbloom/mcp-server 2.0.2 → 2.1.0

package/src/resources.js

@@ -0,0 +1,318 @@
+/**
+ * MCP Resources — read-only catalogue views an agent can pull without a tool call.
+ *
+ * Tools and resources answer different questions. A tool *does* something and
+ * costs a round trip; a resource *is* something the agent can read once and
+ * reason over. The catalogue is exactly the latter: 31 manifests, every schema,
+ * searchable offline — a host that supports resources can answer "what exists?"
+ * without spending a call, and a model can hold the whole surface in context
+ * instead of discovering it one slug at a time.
+ *
+ * Like handlers.js, this file imports no SDK: the handlers return plain objects
+ * and the transport adapter in server.js is the only place the protocol lives.
+ */
+
+import { groupByCategory, resolveSlugStrict } from "./discovery.js";
+import { NexusBloomError, ErrorCode } from "./errors.js";
+import { summariseRun } from "./history.js";
+import { notFoundError } from "./handlers.js";
+import { requiredCount, buildExampleArgs } from "./render.js";
+
+/** The scheme every resource lives under. */
+export const RESOURCE_SCHEME = "nexusbloom";
+
+/** The three read paths, as constants so tests and the guide cannot drift. */
+export const GUIDE_URI = "nexusbloom://guide";
+export const CATALOGUE_URI = "nexusbloom://catalogue";
+export const TOOL_URI_PREFIX = "nexusbloom://tools/";
+export const TOOL_URI_TEMPLATE = "nexusbloom://tools/{slug}";
+export const HISTORY_URI = "nexusbloom://history";
+
+/** MIME types. JSON for data an agent parses, markdown for prose a model reads. */
+const JSON_MIME = "application/json";
+const MD_MIME = "text/markdown";
+
+/**
+ * Assemble the resource handlers over a manifest cache.
+ *
+ * @param {object} deps
+ * @param {import("./manifests.js").ManifestCache} deps.cache
+ * @param {object} [deps.config]
+ * @returns {{listResources: Function, listResourceTemplates: Function, readResource: Function}}
+ */
+export function createResources({ cache, config, history } = {}) {
+  /**
+   * The static resources.
+   *
+   * Deliberately tiny. The catalogue is the only dynamic read, and a list of 31
+   * per-tool entries would just be the catalogue again with more tokens.
+   */
+  async function listResources() {
+    return {
+      resources: [
+        {
+          uri: GUIDE_URI,
+          name: "NexusBloom usage guide",
+          description:
+            "How to discover, inspect and run NexusBloom tools: meta commands, resource URIs, " +
+            "rate limits, and how results are rendered.",
+          mimeType: MD_MIME,
+        },
+        {
+          uri: HISTORY_URI,
+          name: "Run history",
+          description:
+            "What this session has run, newest first: run id, tool, status, duration. " +
+            "In memory only — never written to disk.",
+          mimeType: JSON_MIME,
+        },
+        {
+          uri: CATALOGUE_URI,
+          name: "Tool catalogue",
+          description:
+            "Every published tool as JSON: slug, description, category, tags, parameter counts, " +
+            "and the resource URI carrying its full manifest.",
+          mimeType: JSON_MIME,
+        },
+      ],
+    };
+  }
+
+  /** Per-tool manifests are one template, not N resources. */
+  async function listResourceTemplates() {
+    return {
+      resourceTemplates: [
+        {
+          uriTemplate: TOOL_URI_TEMPLATE,
+          name: "Tool manifest",
+          description:
+            "The full manifest for one tool: input and output JSON Schema, tags, pricing, " +
+            "and a ready-to-send example argument object.",
+          mimeType: JSON_MIME,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Read one resource by URI.
+   *
+   * Unlike tool calls there is no `isError` channel here, so a bad URI has to
+   * raise: a JSON-RPC error the host can surface, rather than a resource whose
+   * body silently says "not found" and which an agent would quote as fact.
+   */
+  async function readResource(params) {
+    const uri = typeof params === "string" ? params : params?.uri;
+    if (typeof uri !== "string" || !uri.trim()) {
+      throw new NexusBloomError(
+        `A resource URI is required. Available: ${GUIDE_URI}, ${CATALOGUE_URI}, ${TOOL_URI_TEMPLATE}.`,
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+    const wanted = uri.trim();
+
+    if (wanted === GUIDE_URI) return textResource(GUIDE_URI, renderGuide(config), MD_MIME);
+    if (wanted === HISTORY_URI) return jsonResource(HISTORY_URI, readHistory(history));
+    if (wanted === CATALOGUE_URI) return jsonResource(CATALOGUE_URI, await readCatalogue());
+
+    if (wanted.startsWith(TOOL_URI_PREFIX)) {
+      const slug = decodeURIComponent(wanted.slice(TOOL_URI_PREFIX.length));
+      return jsonResource(wanted, await readToolManifest(slug));
+    }
+
+    throw new NexusBloomError(
+      `Unknown resource "${wanted}". Available: ${GUIDE_URI}, ${CATALOGUE_URI}, ${TOOL_URI_TEMPLATE}.`,
+      ErrorCode.NOT_FOUND,
+    );
+  }
+
+  /**
+   * The recorded runs, newest first.
+   *
+   * Summaries only — the payloads are reachable per run through the meta-tool's
+   * `history show`, and a host reading this resource wants an index, not a
+   * transcript. Returns an empty list rather than throwing when history is off or
+   * empty: "nothing ran yet" is an answer, not a failure.
+   */
+  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 };
+  }
+
+  /**
+   * The whole catalogue, lean.
+   *
+   * Full schemas are excluded on purpose: this resource exists to be read into
+   * context in one go, and 31 manifests inline would blow the budget before the
+   * agent has chosen a tool. Each entry carries the URI that holds the detail.
+   */
+  async function readCatalogue() {
+    const tools = await cache.tools();
+    return {
+      count: tools.length,
+      categories: groupByCategory(tools).map((g) => g.category),
+      tools: tools.map((t) => ({
+        slug: t.slug,
+        name: t.name,
+        description: t.short_description,
+        category: t.category,
+        tags: t.tags,
+        runtime: t.runtime,
+        price_type: t.price_type,
+        required_params: requiredCount(t),
+        total_params: Object.keys(t.input_schema?.properties || {}).length,
+        has_schema: t.hasSchema,
+        manifest: toolUri(t.slug),
+      })),
+    };
+  }
+
+  /**
+   * One tool's full manifest.
+   *
+   * Resolution is strict, so an abbreviation that could mean two tools errors
+   * with both candidates rather than reading whichever sorted first.
+   */
+  async function readToolManifest(slug) {
+    const wanted = (slug || "").trim();
+    if (!wanted) {
+      throw new NexusBloomError(
+        `${TOOL_URI_PREFIX} needs a slug, e.g. ${toolUri("env-validator")}.`,
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+
+    const tools = await cache.tools();
+    const { tool, ambiguous } = resolveSlugStrict(tools, wanted);
+
+    if (!tool) {
+      // Reuse the tool-call message so an agent that guesses a slug from either
+      // path gets the same recovery instructions.
+      throw notFoundError(wanted, tools, ambiguous);
+    }
+
+    // A published schema is authoritative; fetch the manifest only when the list
+    // entry has none, which is the pre-reconciliation shape.
+    let manifest = tool;
+    if (!tool.hasSchema) {
+      try {
+        manifest = await cache.manifest(tool.slug);
+      } catch {
+        /* fall back to the list entry; hasSchema:false already says why */
+      }
+    }
+
+    return {
+      ...manifest,
+      call: { tool: manifest.slug, arguments: buildExampleArgs(manifest) },
+      manifest: toolUri(manifest.slug),
+    };
+  }
+
+  return { listResources, listResourceTemplates, readResource };
+}
+
+/** The resource URI for one tool. */
+export function toolUri(slug) {
+  return `${TOOL_URI_PREFIX}${encodeURIComponent(slug)}`;
+}
+
+/** Wrap a value as a JSON resource body. */
+function jsonResource(uri, value) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: JSON_MIME,
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+/** Wrap prose as a text resource body. */
+function textResource(uri, text, mimeType = "text/plain") {
+  return { contents: [{ uri, mimeType, text }] };
+}
+
+/**
+ * The usage guide.
+ *
+ * Written as prose rather than a JSON blob because the audience is a model
+ * choosing how to spend its next call. It names the recovery paths — the thing
+ * that actually prevents an agent from guessing slugs and failing.
+ */
+export function renderGuide(config = {}) {
+  const api = config?.apiBase || "the configured API base";
+  const key = config?.apiKey ? "authenticated" : "anonymous (30 requests/minute)";
+
+  return `# NexusBloom MCP
+
+NexusBloom publishes 30+ browser and Node tools behind one API. This server lets an
+agent discover them by intent, read their exact schemas, and run them.
+
+## Three ways to find a tool
+
+1. **Read the catalogue** — \`${CATALOGUE_URI}\` — every tool, one line each.
+2. **Read a manifest** — \`${TOOL_URI_TEMPLATE}\`, e.g. \`${toolUri("env-validator")}\` — full JSON Schema plus a ready example.
+3. **Call the meta tool** — \`nexusbloom\` — when you know the intent but not the slug.
+
+Meta commands:
+
+- \`{"command":"search","query":"validate environment file"}\` — rank tools by intent
+- \`{"command":"list"}\` — every tool, one line each
+- \`{"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":"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:
+
+- \`{"command":"batch","runs":[{"slug":"<slug>","params":{…}},…]}\` — up to 10 runs in one call
+
+Every slug in a batch is resolved and validated **before** the first run, so a typo
+costs no quota and the whole batch is rejected rather than half-run. Once running,
+each entry is independent: one tool failing does not discard the results that
+succeeded, and the response lists failures first.
+
+Any published tool is also callable **directly by its slug**, with its own parameters
+as arguments. Prefer the direct call once you know the name; the meta tool exists for
+recovery.
+
+## When a call fails
+
+- **Unknown slug** — the error lists close matches. Try one, or \`search\` by intent.
+- **Schema mismatch** — call \`schema\` and read the actual parameter names.
+- **Abbreviation ambiguous** — the error names both candidates. Use the full slug.
+
+## Results
+
+Tool output is rendered for the host: text results are marked for the assistant,
+visual results for the user. A result the server cannot classify is returned as raw
+JSON rather than guessed at, so nothing is silently reshaped.
+
+## Resources
+
+| URI | Contents |
+| --- | --- |
+| \`${GUIDE_URI}\` | This guide. |
+| \`${CATALOGUE_URI}\` | Every published tool, one entry each, with a manifest URI. |
+| \`${TOOL_URI_TEMPLATE}\` | One tool's full manifest, e.g. \`${toolUri("env-validator")}\`. |
+
+## Prompts
+
+If your host offers prompts, four are available: \`find-tool\` (rank tools by intent),
+\`use-tool\` (one tool's exact parameters and a valid call), \`plan-batch\` (shape a
+multi-tool task into one batched call), and \`recover\` (what an error code means and
+what to do next).
+
+## Limits
+
+- This session is ${key}.
+- Requests go to ${api}.
+- Per-call timeouts come from \`NEXUSBLOOM_MCP_TIMEOUT_MS\` (default 15s).
+- Anonymous callers are capped at 30 requests/minute; authenticated callers are not.
+`;
+}

package/src/server.js

@@ -6,16 +6,47 @@
  * without a transport, so this file is the only place the SDK is imported.
  */
 
+import { createRequire } from "node:module";
+
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
 import {
   CallToolRequestSchema,
+  ErrorCode as McpErrorCode,
   ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
 import { buildToolList, createHandlers } from "./handlers.js";
+import { RunHistory } from "./history.js";
+import { createProgressReporter, handlerProgress } from "./progress.js";
+import { createPrompts } from "./prompts.js";
+import { createResources } from "./resources.js";
+import { asNexusBloomError, ErrorCode } from "./errors.js";
 
 export const SERVER_NAME = "nexusbloom-mcp";
-export const SERVER_VERSION = "2.0.0";
+
+/**
+ * The version reported to hosts.
+ *
+ * Read from package.json rather than hardcoded: a hardcoded literal drifts the
+ * moment a release is cut, and a server that under-reports its own version
+ * makes bug reports from clients unmatchable to code.
+ */
+export const SERVER_VERSION = readPackageVersion();
+
+function readPackageVersion() {
+  try {
+    const require = createRequire(import.meta.url);
+    return require("../package.json").version;
+  } catch {
+    return "0.0.0-unknown";
+  }
+}
 
 /**
  * Wire a handler set onto an MCP Server.
@@ -25,20 +56,63 @@ export const SERVER_VERSION = "2.0.0";
  *   seam that lets the error-containment path be tested directly.
  * @returns {{server: Server, handlers: object}}
  */
-export function createServer({ client, cache, config, handlers: provided }) {
-  const handlers = provided ?? createHandlers({ client, cache, config });
+export function createServer({
+  client,
+  cache,
+  config,
+  handlers: provided,
+  resources: providedResources,
+  prompts: providedPrompts,
+}) {
+  // One log for the whole server: the handlers write it and the history resource
+  // reads it, so a resource showing an empty log while tools have run would be
+  // a lie. Created here rather than inside createHandlers so both get the same one.
+  const history = provided?.history ?? new RunHistory();
+  const handlers = provided ?? createHandlers({ client, cache, config, history });
   const listTools = provided ? buildToolList(cache) : handlers.listTools;
+  const resources = providedResources ?? createResources({ cache, config, history });
+  const prompts = providedPrompts ?? createPrompts({ cache });
 
   const server = new Server(
     { name: SERVER_NAME, version: SERVER_VERSION },
-    { capabilities: { tools: {} } },
+    { capabilities: { tools: {}, resources: {}, prompts: {} } },
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => listTools());
 
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.setRequestHandler(ListPromptsRequestSchema, async () => prompts.listPrompts());
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    // Same containment as resources: no isError channel, so a bad prompt name or
+    // a missing argument has to be a protocol error carrying the recovery.
+    try {
+      return await prompts.getPrompt(request.params ?? {});
+    } catch (err) {
+      throw toMcpError(err);
+    }
+  });
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => resources.listResources());
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => resources.listResourceTemplates());
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    // Resources have no isError channel, so a failure here is a protocol error.
+    // NexusBloomError carries the wording the agent needs; a bare TypeError here
+    // would reach the user as "request failed" with no route to recovery.
+    try {
+      return await resources.readResource(request.params ?? {});
+    } catch (err) {
+      throw toMcpError(err);
+    }
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const { name: toolName, arguments: args } = request.params ?? {};
 
+    // Progress is opt-in per request: a host that sends no progressToken has not
+    // asked for notifications, and sending them anyway is noise at best.
+    const reporter = createProgressReporter({ extra });
+    const onProgress = handlerProgress(reporter);
+
     // No handler may throw: an exception here becomes a JSON-RPC protocol error,
     // which a model cannot recover from, whereas an isError result is a normal
     // tool outcome it can reason about.
@@ -49,15 +123,40 @@ export function createServer({ client, cache, config, handlers: provided }) {
           isError: true,
         };
       }
+
+      // A named tool gets a "running…" tick so a slow call shows something. The
+      // batch command reports per item instead, so it is not double-counted.
+      if (onProgress && toolName !== "nexusbloom") {
+        await onProgress({ progress: 0, message: `Running ${toolName}…` });
+      }
+
       return toolName === "nexusbloom"
-        ? await handlers.meta(args ?? {})
+        ? await handlers.meta(args ?? {}, { onProgress })
         : await handlers.callDirect(toolName, args ?? {});
     } catch (err) {
       return handlers.handleError ? handlers.handleError(err) : fallbackError(err);
     }
   });
 
-  return { server, handlers };
+  return { server, handlers, resources, prompts, history };
+}
+
+/**
+ * Translate an internal error into a JSON-RPC error.
+ *
+ * Not-found and bad-argument map to InvalidParams because the agent sent
+ * something wrong and can fix it by reading the message; everything else is the
+ * server's fault and says so with InternalError.
+ */
+export function toMcpError(err) {
+  if (err instanceof McpError) return err;
+  const nxb = asNexusBloomError(err);
+  const agentFixable = nxb.code === ErrorCode.NOT_FOUND || nxb.code === ErrorCode.INVALID_ARGS;
+  return new McpError(
+    agentFixable ? McpErrorCode.InvalidParams : McpErrorCode.InternalError,
+    nxb.message,
+    { data: { code: nxb.code, retryable: nxb.retryable ?? false } },
+  );
 }
 
 /**

package/src/validate.js

@@ -81,7 +81,20 @@ export function assertValidInput(params, inputSchema, slug) {
  * as a bare string body.
  */
 export function coerceParams(params, slug) {
-  if (typeof params !== "string") return params ?? {};
+  if (params === undefined || params === null) return {};
+  if (typeof params !== "string") {
+    // Guard the non-object case here rather than letting it reach the schema
+    // validator, which would report a missing-field error for a payload that was
+    // never an object at all. A host sending `42` deserves to be told what it
+    // sent, not told which field of a number is absent.
+    if (typeof params !== "object" || Array.isArray(params)) {
+      throw new NexusBloomError(
+        `"params" for "${slug}" must be a JSON object, got ${Array.isArray(params) ? "an array" : typeof params}.`,
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+    return params;
+  }
   const trimmed = params.trim();
   if (!trimmed) return {};