@nexusbloom/mcp-server 1.0.3 → 2.0.2

package/src/errors.js

@@ -0,0 +1,107 @@
+/**
+ * Errors — one class, codes agents can branch on.
+ *
+ * v1 threw bare `new Error(err.error)`, discarding the API's `code`. An agent
+ * that hit a validation failure and a rate limit got two different HTTP statuses
+ * flattened into the same untyped string, so it had to parse prose to decide
+ * whether to retry. `NexusBloomError` keeps the code all the way to the MCP
+ * response.
+ */
+
+/** Codes the server itself produces, independent of what the API said. */
+export const ErrorCode = {
+  TIMEOUT: "TIMEOUT",
+  NETWORK: "NETWORK",
+  NOT_FOUND: "TOOL_NOT_FOUND",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  RATE_LIMITED: "RATE_LIMITED",
+  INVALID_ARGS: "INVALID_ARGS",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  API_ERROR: "API_ERROR",
+  CONFIG: "CONFIG_ERROR",
+};
+
+/**
+ * Map an HTTP status to a code, used only when the response body carries none.
+ *
+ * The API already returns codes through `_middleware.js`; this is the fallback
+ * for a proxy or CDN error page that never reaches the handler.
+ */
+export function codeForStatus(status) {
+  if (status === 401 || status === 403) return ErrorCode.UNAUTHORIZED;
+  if (status === 404) return ErrorCode.NOT_FOUND;
+  if (status === 429) return ErrorCode.RATE_LIMITED;
+  if (status === 400) return ErrorCode.VALIDATION_FAILED;
+  return ErrorCode.API_ERROR;
+}
+
+export class NexusBloomError extends Error {
+  /**
+   * @param {string} message    Human-readable, safe to show an agent.
+   * @param {string} code       Stable identifier; see ErrorCode.
+   * @param {object} [opts]
+   * @param {number} [opts.status]  HTTP status, when there was one.
+   * @param {*}      [opts.details] Extra structured context (field errors, etc).
+   * @param {boolean}[opts.retryable] Whether retrying could plausibly succeed.
+   */
+  constructor(message, code, opts = {}) {
+    super(message);
+    this.name = "NexusBloomError";
+    this.code = code || ErrorCode.API_ERROR;
+    this.status = opts.status ?? null;
+    this.details = opts.details ?? null;
+    this.retryable = opts.retryable ?? isRetryableCode(this.code, opts.status);
+  }
+
+  /** Shape embedded in the MCP text response. */
+  toJSON() {
+    return {
+      success: false,
+      error: this.message,
+      code: this.code,
+      ...(this.status ? { status: this.status } : {}),
+      ...(this.details ? { details: this.details } : {}),
+      retryable: this.retryable,
+    };
+  }
+}
+
+/**
+ * Retry only what is worth retrying.
+ *
+ * A 400 will fail identically forever; a timeout or a 429 might not. Agents act
+ * on this flag, so getting it wrong causes either an infinite retry loop or a
+ * premature give-up.
+ */
+function isRetryableCode(code, status) {
+  if (code === ErrorCode.TIMEOUT || code === ErrorCode.NETWORK) return true;
+  if (code === ErrorCode.RATE_LIMITED) return true;
+  // 5xx is a server fault that may not repeat.
+  return typeof status === "number" && status >= 500 && status < 600;
+}
+
+/**
+ * Wrap an arbitrary thrown value as a NexusBloomError.
+ *
+ * `fetch` rejects with a TypeError for DNS failure, connection refused and TLS
+ * errors alike, all of which read as "fetch failed" — useless to an agent. The
+ * cause is unwrapped so the distinction survives.
+ */
+export function asNexusBloomError(err) {
+  if (err instanceof NexusBloomError) return err;
+
+  if (err?.name === "AbortError" || err?.name === "TimeoutError") {
+    return new NexusBloomError(
+      `Request timed out. The NexusBloom API did not respond in time.`,
+      ErrorCode.TIMEOUT,
+      { retryable: true },
+    );
+  }
+
+  const detail = err?.cause?.message || err?.message || String(err);
+  return new NexusBloomError(
+    `Could not reach the NexusBloom API: ${detail}. Check NEXUSBLOOM_API_URL and network connectivity.`,
+    ErrorCode.NETWORK,
+    { retryable: true },
+  );
+}

package/src/handlers.js

@@ -0,0 +1,431 @@
+/**
+ * Request handlers — every behaviour of the server, with no MCP SDK import.
+ *
+ * Keeping this layer free of the SDK is what makes the suite meaningful: the
+ * handlers are plain async functions returning plain objects, so a test drives
+ * them directly with a stubbed client and asserts on the exact bytes an agent
+ * would receive. The SDK wiring in server.js is then a thin adapter over
+ * something already verified.
+ */
+
+import { ApiClient } from "./client.js";
+import { loadConfig } from "./config.js";
+import {
+  describeParameters,
+  groupByCategory,
+  resolveSlugStrict,
+  searchTools,
+  suggest,
+} from "./discovery.js";
+import { asNexusBloomError, ErrorCode, NexusBloomError } from "./errors.js";
+import { ManifestCache, normaliseTool } from "./manifests.js";
+import {
+  renderConnectivityReport,
+  renderResult,
+  respond,
+  respondError,
+  renderSchema,
+  renderSearchResults,
+  renderToolList,
+  renderToolReportedError,
+} from "./render.js";
+import { assertValidInput, coerceParams } from "./validate.js";
+
+/**
+ * Assemble a handler set over a client and a manifest cache.
+ *
+ * @param {object} deps
+ * @param {ApiClient}      deps.client
+ * @param {ManifestCache}  deps.cache
+ * @param {object}         deps.config
+ */
+export function createHandlers({ client, cache, config }) {
+  /**
+   * Look up a tool by exact slug or unambiguous abbreviation.
+   *
+   * Uses the strict resolver, so execution never silently runs a different tool
+   * than the agent named.
+   */
+  async function findTool(slug, { refresh = false } = {}) {
+    const tools = await cache.tools({ force: refresh });
+    return { tools, ...resolveSlugStrict(tools, slug) };
+  }
+
+  /**
+   * Execute a tool by slug.
+   *
+   * The sequence matters: resolve, then validate against the manifest, then
+   * call. Validating first means a bad call costs no quota and returns an error
+   * naming the offending field.
+   */
+  async function execute(slug, rawParams, opts = {}) {
+    if (!slug || typeof slug !== "string" || !slug.trim()) {
+      throw new NexusBloomError(
+        "A tool slug is required. Call `nexusbloom` with command \"list\" to see available tools.",
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+
+    const params = coerceParams(rawParams, slug);
+
+    let tools = [];
+    let tool = null;
+    let ambiguous = [];
+
+    try {
+      const found = await findTool(slug.trim(), opts);
+      tools = found.tools;
+      tool = found.tool;
+      ambiguous = found.ambiguous;
+    } catch {
+      // A catalogue failure must not block execution. /api/tools and /api/run
+      // are separate endpoints, and the API is authoritative about which slugs
+      // exist — so fall through and let the run call decide. If that fails too,
+      // its error is the more informative one to show.
+    }
+
+    if (!tool) {
+      // No list available at all — let the API be the judge.
+      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 }))
+          .catch((err) => {
+            throw enrichNotFound(err, slug.trim(), []);
+          });
+        return { ...result, tool: slug.trim(), execution: "remote" };
+      }
+
+      throw notFoundError(slug.trim(), tools, ambiguous);
+    }
+
+    // Best-effort schema for validation; a manifest fetch failure is not fatal
+    // because the API validates authoritatively anyway.
+    let inputSchema = tool.input_schema;
+    try {
+      const manifest = await cache.manifest(tool.slug);
+      inputSchema = manifest.input_schema || inputSchema;
+    } catch {
+      /* keep the list schema */
+    }
+
+    assertValidInput(params, inputSchema, tool.slug);
+
+    const startedAt = Date.now();
+    // 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" },
+    });
+    const durationMs = Date.now() - startedAt;
+
+    return {
+      success: true,
+      data: body?.data ?? body,
+      tool: tool.slug,
+      execution: "remote",
+      durationMs,
+      rateLimit: client.rateLimit ?? null,
+    };
+  }
+
+  /** Meta-tool: discover, inspect, or run. */
+  async function meta(args) {
+    const command = args?.command;
+
+    if (!command) {
+      throw new NexusBloomError(
+        `Missing "command". Use one of: ${META_COMMANDS.join(", ")}.`,
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+    if (!META_COMMANDS.includes(command)) {
+      throw new NexusBloomError(
+        `Unknown command "${command}". Use one of: ${META_COMMANDS.join(", ")}.`,
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+
+    if (command === "list") {
+      const tools = await cache.tools({ force: args?.refresh === true });
+      return respond(renderToolList(tools));
+    }
+
+    if (command === "search") {
+      const query = (args?.query || "").trim();
+      if (!query) {
+        throw new NexusBloomError(
+          `Missing "query" for search. Example: {"command":"search","query":"validate env file"}.`,
+          ErrorCode.INVALID_ARGS,
+        );
+      }
+      const tools = await cache.tools();
+      const limit = Number.isInteger(args?.limit) && args.limit > 0 ? Math.min(args.limit, 50) : 10;
+      const results = searchTools(tools, query, { limit, includeAll: false });
+      const categories = groupByCategory(tools).map((g) => g.category);
+      return respond(renderSearchResults(query, results, tools.length, categories));
+    }
+
+    if (command === "schema") {
+      const slug = (args?.slug || "").trim();
+      if (!slug) {
+        throw new NexusBloomError(
+          `Missing "slug" for schema. Call {"command":"list"} or {"command":"search","query":"…"} first.`,
+          ErrorCode.INVALID_ARGS,
+        );
+      }
+      const { tools, tool, ambiguous } = await findTool(slug);
+      if (!tool) throw notFoundError(slug, tools, ambiguous);
+
+      // The list carries a schema now that the API ships them; fall back to a
+      // dedicated fetch only when it does not.
+      let schema = tool;
+      if (!tool.input_schema || Object.keys(tool.input_schema.properties || {}).length === 0) {
+        try {
+          schema = await cache.manifest(tool.slug);
+        } catch {
+          /* use the list schema */
+        }
+      }
+      return respond(renderSchema(schema, tools));
+    }
+
+    // run
+    const slug = (args?.slug || "").trim();
+    if (!slug) {
+      throw new NexusBloomError(
+        `Missing "slug" for run. Call {"command":"list"} or {"command":"search","query":"…"} first.`,
+        ErrorCode.INVALID_ARGS,
+      );
+    }
+    const result = await execute(slug, args?.params ?? {});
+    return respondResult(result);
+  }
+
+  /** Direct invocation by tool slug. */
+  async function callDirect(name, args) {
+    const result = await execute(name, args ?? {});
+    return respondResult(result);
+  }
+
+  /** Wrap a successful execution, distinguishing a tool-reported error. */
+  function respondResult(result) {
+    const data = result.data;
+    if (data && typeof data === "object" && (data.success === false || (data.error && !data.data))) {
+      return respond(renderToolReportedError(result.tool, data));
+    }
+    return respond(renderResult(result.tool, data, result));
+  }
+
+  return {
+    listTools: buildToolList(cache),
+    meta,
+    callDirect,
+    execute,
+    findTool,
+    handleError: respondError,
+  };
+}
+
+/** The meta-tool's accepted commands, used in errors and tests. */
+export const META_COMMANDS = ["list", "search", "schema", "run"];
+
+/**
+ * Build a not-found error that tells the agent what to do next.
+ *
+ * The suggestions come from edit distance *and* scored search, so both a typo
+ * (`env-validatr`) and a vague reference (`environment checker`) recover.
+ */
+export function notFoundError(slug, tools, ambiguous = []) {
+  const near = [...new Set([...ambiguous.map((t) => t.slug), ...suggest(tools, slug).map((t) => t.slug)])];
+  const searched = searchTools(tools, slug, { limit: 3, includeAll: false });
+
+  const parts = [`No tool named "${slug}" is published.`];
+  if (searched.length) {
+    parts.push(`Closest matches: ${searched.map((t) => t.slug).join(", ")}.`);
+  } else if (near.length) {
+    parts.push(`Did you mean: ${near.join(", ")}?`);
+  }
+  parts.push(`Call {"command":"search","query":"<what you need>"} to find a tool by intent.`);
+
+  return new NexusBloomError(parts.join(" "), ErrorCode.NOT_FOUND, {
+    details: {
+      suggestions: searched.length ? searched.map((t) => t.slug) : near.slice(0, 3),
+      catalogueSize: tools.length,
+    },
+  });
+}
+
+/** Add suggestions to a not-found error that came from the API. */
+function enrichNotFound(err, slug, tools) {
+  if (err?.code !== ErrorCode.NOT_FOUND) return err;
+  const suggestions = tools.length ? suggest(tools, slug).map((t) => t.slug) : [];
+  const hint = suggestions.length ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+  return new NexusBloomError(`${err.message}${hint}`, ErrorCode.NOT_FOUND, {
+    status: err.status,
+    details: { suggestions },
+  });
+}
+
+/**
+ * The advertised tool list.
+ *
+ * One entry per tool, named by its slug so an agent can call it directly. The
+ * meta-tool is advertised too — it is how an agent recovers when a direct call
+ * is not what it wanted.
+ */
+export function buildToolList(cache) {
+  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*
+    // broken and may refuse to retry; returning the meta-tool alone lets the
+    // agent discover that the API is down and report it, which is recoverable.
+    let tools = [];
+    try {
+      tools = await cache.tools();
+    } catch {
+      tools = [];
+    }
+
+    const entries = tools.map((t) => ({
+      name: t.slug,
+      description: buildToolDescription(t),
+      inputSchema: t.input_schema,
+    }));
+
+    entries.push({
+      name: "nexusbloom",
+      description:
+        "Discover and inspect NexusBloom tools without knowing their names.\n\n" +
+        "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' +
+        "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.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            enum: META_COMMANDS,
+            description:
+              "list: all tools. search: find by intent. schema: a tool's parameters. run: execute a tool.",
+          },
+          slug: {
+            type: "string",
+            description: "Tool slug. Required for 'schema' and 'run'.",
+          },
+          query: {
+            type: "string",
+            description:
+              "What you want to do, in plain language. Used by 'search'. " +
+              'Example: "check a cron expression is valid".',
+          },
+          params: {
+            type: "object",
+            description: "Input parameters for 'run', matching the tool's input schema.",
+          },
+          limit: {
+            type: "integer",
+            description: "Maximum results for 'search'. Default 10.",
+            minimum: 1,
+            maximum: 50,
+          },
+          refresh: {
+            type: "boolean",
+            description: "Bypass the cached tool list for 'list'. Default false.",
+          },
+        },
+        required: ["command"],
+        additionalProperties: false,
+      },
+    });
+
+    return { tools: entries };
+  };
+}
+
+/**
+ * One line that lets an agent decide *whether* to call a tool.
+ *
+ * Includes the required-argument count because "how hard is this to call" is
+ * part of the decision, and a tool needing five arguments is a different
+ * commitment from one needing none.
+ */
+export function buildToolDescription(tool) {
+  // Built by appending to one string rather than joining an array: the leading
+  // clause already carries its own separator, so a join would leave a double
+  // space before the description.
+  let desc = tool.name ? `${tool.name}: ` : "";
+  desc += tool.short_description || "No description";
+  if (tool.category && tool.category !== "uncategorized") desc += ` [${tool.category}]`;
+
+  const props = Object.keys(tool.input_schema?.properties || {});
+  const required = (tool.input_schema?.required || []).length;
+
+  if (tool.hasSchema === false) desc += " (schema not published — call schema before running)";
+  else if (required === 0 && props.length === 0) desc += " (takes no arguments)";
+  else if (required === 0) desc += ` (all ${props.length} params optional)`;
+  else desc += ` (${required} required of ${props.length} params)`;
+
+  if (tool.tags?.length) desc += ` Tags: ${tool.tags.slice(0, 4).join(", ")}.`;
+  return desc;
+}
+
+/**
+ * Probe the API and report what was reachable.
+ *
+ * Never throws and never blocks startup on failure: an unreachable API degrades
+ * the server to a clear error on each request rather than preventing it from
+ * starting at all, which is what v1's unguarded probe did.
+ */
+export async function checkConnectivity(client, roots, config, deps = {}) {
+  const fetchImpl = deps.fetchImpl || client.fetchImpl;
+  const timeoutMs = Math.min(config.timeoutMs, deps.timeoutMs ?? 5_000);
+  const errors = [];
+  let connected = null;
+
+  for (const root of roots) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(`${root}/tools`, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        signal: controller.signal,
+      });
+      // 429 means the endpoint exists and is rate-limiting us, which is a
+      // successful connectivity check.
+      if (res.ok || res.status === 429) {
+        connected = root;
+        break;
+      }
+      errors.push(`${root}/tools → HTTP ${res.status}`);
+    } catch (err) {
+      errors.push(`${root}/tools → ${err?.message || "unreachable"}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {
+    connected,
+    roots,
+    apiBase: config.apiBase,
+    anonymous: config.anonymous,
+    errors,
+    report: renderConnectivityReport({
+      connected,
+      roots,
+      apiBase: config.apiBase,
+      anonymous: config.anonymous,
+      errors,
+    }),
+  };
+}
+
+export { ApiClient, loadConfig, ManifestCache, normaliseTool, asNexusBloomError, describeParameters };