@nexusbloom/mcp-server 1.0.3 → 2.0.0

package/src/client.js

@@ -0,0 +1,156 @@
+/**
+ * HTTP client — the single egress point.
+ *
+ * Every request goes through here so that timeouts, auth headers, error
+ * decoding and diagnostics are applied uniformly. v1 had three separate `fetch`
+ * call sites and one of them (`main()`'s connectivity probe) sent no auth
+ * header and no timeout, so an unreachable API hung startup indefinitely
+ * instead of falling through to degraded mode.
+ */
+
+import { asNexusBloomError, codeForStatus, ErrorCode, NexusBloomError } from "./errors.js";
+
+/**
+ * JSON logging to stderr.
+ *
+ * stdout is the MCP stdio transport: any byte written there that is not a
+ * JSON-RPC frame desynchronises the protocol and the client disconnects. This
+ * is the only sanctioned way to emit diagnostics.
+ */
+export function makeLogger(debug) {
+  return (...args) => {
+    if (!debug) return;
+    process.stderr.write(`[nexusbloom-mcp] ${args.map(String).join(" ")}\n`);
+  };
+}
+
+export class ApiClient {
+  /**
+   * @param {object} config  From loadConfig().
+   * @param {object} [deps]
+   * @param {typeof fetch} [deps.fetchImpl]  Injected in tests; never real network.
+   * @param {Function}     [deps.now]        Clock, injected so TTL is testable.
+   */
+  constructor(config, deps = {}) {
+    this.config = config;
+    this.log = makeLogger(config.debug);
+    this.fetchImpl = deps.fetchImpl || globalThis.fetch;
+    this.now = deps.now || Date.now;
+
+    // Guards a hung request in environments where the AbortSignal timeout does
+    // 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();
+  }
+
+  /**
+   * Perform one request and decode JSON.
+   *
+   * @param {string} path       Appended to the API base, e.g. "/tools".
+   * @param {object} [opts]
+   * @param {string} [opts.method]
+   * @param {*}      [opts.body]     Serialised as JSON when present.
+   * @param {boolean}[opts.auth]     Send the API key. Default true.
+   * @returns {Promise<*>} Decoded body.
+   * @throws {NexusBloomError} Always, for any failure mode.
+   */
+  async request(path, opts = {}) {
+    const { method = "GET", body, auth = true } = opts;
+    const url = `${this.config.apiBase}${path}`;
+
+    const headers = { Accept: "application/json" };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (auth && this.config.apiKey) headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+
+    // 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);
+    this._inFlight.add(controller);
+
+    const onExternalAbort = () => controller.abort();
+    if (opts.signal) {
+      if (opts.signal.aborted) controller.abort();
+      else opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+    }
+
+    this.log(`${method} ${url}`);
+
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      throw asNexusBloomError(err);
+    } finally {
+      clearTimeout(timer);
+      this._inFlight.delete(controller);
+      if (opts.signal) opts.signal.removeEventListener?.("abort", onExternalAbort);
+    }
+
+    return this._decode(res, { url, method });
+  }
+
+  /**
+   * Turn a Response into a decoded body or a typed error.
+   *
+   * The API's own `code` wins over the status-derived guess — it distinguishes
+   * a 400 caused by a bad slug from one caused by a schema violation, and that
+   * is exactly the distinction an agent needs to pick its next move.
+   */
+  async _decode(res, ctx) {
+    const text = await res.text().catch(() => "");
+
+    let parsed = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = null;
+      }
+    }
+
+    if (!res.ok) {
+      const apiMessage =
+        parsed?.error || parsed?.message || parsed?.data?.error || text?.slice(0, 300);
+      const code = parsed?.code || codeForStatus(res.status);
+
+      const message = apiMessage?.trim()
+        ? `${apiMessage}`
+        : `API returned ${res.status} for ${ctx.method} ${ctx.url}`;
+
+      throw new NexusBloomError(message, code, {
+        status: res.status,
+        // The API returns `fields` on schema failures; keep it so an agent can
+        // repair exactly the bad keys instead of re-reading the whole schema.
+        details: parsed?.details ?? parsed?.fields ?? null,
+      });
+    }
+
+    if (parsed === null) {
+      throw new NexusBloomError(
+        `API returned a non-JSON response (${res.status}) for ${ctx.method} ${ctx.url}`,
+        ErrorCode.API_ERROR,
+        { status: res.status },
+      );
+    }
+
+    return parsed;
+  }
+
+  /**
+   * Abort every in-flight request; used on shutdown.
+   *
+   * `AbortController.abort()` does not throw, and a controller whose request
+   * already settled is a no-op, so there is nothing to guard against here.
+   */
+  abortAll() {
+    for (const controller of this._inFlight) controller.abort();
+    this._inFlight.clear();
+  }
+}

package/src/config.js

@@ -0,0 +1,117 @@
+/**
+ * Configuration — resolved once, injected everywhere.
+ *
+ * The v1 server read `process.env` at module top level, which meant the tests
+ * could not exercise any branch: importing the module froze the configuration
+ * before a test had a chance to change it. Everything here is a function of an
+ * explicit env object so tests can construct any configuration they want.
+ */
+
+/**
+ * The API base differs from the CLI's on purpose, and historically by accident.
+ *
+ * The CLI stores `https://www.nexusbloom.dev` and appends `/api/...`. v1 stored
+ * `https://nexusbloom.dev/api` and appended `/tools`. Both forms are accepted
+ * here: `apiRoot()` normalises whatever the operator supplied into a base that
+ * already ends in `/api`, so every call site can just say `${root}/tools`.
+ *
+ * Non-www is the default because it is what the platform serves, but the `www`
+ * host is tried as a fallback by `candidateRoots()` — the two redirect
+ * differently in some networks and neither is reliably better.
+ */
+export const DEFAULT_API_HOST = "https://nexusbloom.dev";
+
+/** Requests that outlive this are reported as a timeout, not a hang. */
+export const DEFAULT_TIMEOUT_MS = 15_000;
+
+/** Long enough to absorb a burst, short enough that a stale list self-heals. */
+export const DEFAULT_CACHE_TTL_MS = 60_000;
+
+/**
+ * Normalise an operator-supplied base into something ending in `/api`.
+ *
+ * Accepts, and returns for each:
+ *   (nothing)                    → https://nexusbloom.dev/api
+ *   https://nexusbloom.dev       → https://nexusbloom.dev/api
+ *   https://nexusbloom.dev/      → https://nexusbloom.dev/api
+ *   https://nexusbloom.dev/api   → https://nexusbloom.dev/api
+ *   https://nexusbloom.dev/api/  → https://nexusbloom.dev/api
+ *   http://localhost:3000        → http://localhost:3000/api
+ */
+export function normaliseApiBase(input) {
+  const raw = (input || "").trim();
+  if (!raw) return `${DEFAULT_API_HOST}/api`;
+
+  let base = raw.replace(/\/+$/, "");
+  if (!base) return `${DEFAULT_API_HOST}/api`;
+  if (!/^https?:\/\//i.test(base)) base = `https://${base}`;
+
+  // A base that already carries the prefix is left alone, so both the host form
+  // and the full form converge on one string and callers never double it up.
+  if (!/\/api$/i.test(base)) base = `${base}/api`;
+  return base;
+}
+
+/**
+ * Every base worth trying, in preference order.
+ *
+ * Used only by the startup connectivity probe. Retrying the alternate host is
+ * what makes the server survive a `www`/non-`www` split in the operator's DNS.
+ */
+export function candidateRoots(env = {}) {
+  const primary = normaliseApiBase(env.NEXUSBLOOM_API_URL);
+
+  // Swap only the host's www prefix. Anything else (a port, a non-public host)
+  // has no meaningful alternate, so it is left alone rather than producing a
+  // second nonsense candidate.
+  const withoutApi = primary.replace(/\/api$/, "");
+  const bare = withoutApi.replace(/^https?:\/\//i, "");
+  const labels = bare.split(".");
+
+  // Only an apex domain (name.tld, optionally www-prefixed) has a meaningful
+  // www twin. A localhost, a port, or a subdomain such as api.example.com does
+  // not — prepending www to those invents a host that cannot resolve.
+  const isWww = labels[0] === "www";
+  const apexLabels = isWww ? labels.slice(1) : labels;
+  if (apexLabels.length !== 2 || /:\d+$/.test(bare) || bare === "localhost") {
+    return [primary];
+  }
+
+  const alternateHost = isWww ? apexLabels.join(".") : `www.${apexLabels.join(".")}`;
+  const scheme = withoutApi.match(/^(https?):\/\//i)?.[1] || "https";
+  const alternate = `${scheme}://${alternateHost}/api`;
+
+  return alternate === primary ? [primary] : [primary, alternate];
+}
+
+/**
+ * Build the immutable config object.
+ *
+ * Returns a fresh object every call — tests depend on there being no shared
+ * mutable module state to reset between cases.
+ */
+export function loadConfig(env = process.env) {
+  const apiKey = (env.NEXUSBLOOM_API_KEY || "").trim();
+
+  // Opt-in diagnostic logging. Always on stderr: stdout is the MCP transport and
+  // a single stray byte there corrupts the JSON-RPC framing.
+  const debug = /^(1|true|yes)$/i.test(env.NEXUSBLOOM_MCP_DEBUG || "");
+
+  const timeoutRaw = Number.parseInt(env.NEXUSBLOOM_MCP_TIMEOUT_MS || "", 10);
+  const timeoutMs =
+    Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : DEFAULT_TIMEOUT_MS;
+
+  const ttlRaw = Number.parseInt(env.NEXUSBLOOM_MCP_CACHE_TTL_MS || "", 10);
+  const cacheTtlMs =
+    Number.isFinite(ttlRaw) && ttlRaw >= 0 ? ttlRaw : DEFAULT_CACHE_TTL_MS;
+
+  return {
+    apiKey,
+    apiBase: normaliseApiBase(env.NEXUSBLOOM_API_URL),
+    timeoutMs,
+    cacheTtlMs,
+    debug,
+    /** True when no key was supplied, which changes how limits are described. */
+    anonymous: apiKey === "",
+  };
+}

package/src/discovery.js

@@ -0,0 +1,326 @@
+/**
+ * Tool discovery — making 30 tools findable by an agent that only has a prose
+ * goal like "validate my environment file".
+ *
+ * An agent's problem is not that the catalogue is large; it is that slugs are
+ * opaque. `env-validator` tells an agent nothing about what to pass it. Ranking
+ * surfaces likely candidates first, and `suggest()` gives a wrong-slug error a
+ * recovery path instead of a dead end.
+ *
+ * Scoring is deliberately lexical, not embedding-based: it must run in a stdio
+ * process with no network, no model and no vector store, be deterministic, and
+ * return identical output for identical input so tests can assert on it. The
+ * fields below are chosen because they are what the manifest actually carries.
+ */
+
+const STOP_WORDS = new Set([
+  "a", "an", "the", "my", "our", "your", "to", "for", "of", "in", "on", "with",
+  "and", "or", "is", "are", "be", "it", "that", "this", "from", "by", "at",
+  "me", "i", "we", "you", "can", "do", "does", "need", "want", "please", "help",
+]);
+
+/** Tokenise a phrase into comparable terms. */
+export function tokenise(text) {
+  if (typeof text !== "string") return [];
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/i)
+    .filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+}
+
+/**
+ * The search text for one tool: everything a user might plausibly type.
+ *
+ * Input field names are included because agents search by what they want to
+ * *supply* ("the tool that takes a regex pattern"), not only by what it does.
+ */
+function haystack(tool) {
+  return [
+    tool.slug,
+    tool.slug.replace(/-/g, " "),
+    tool.name,
+    tool.short_description,
+    tool.category,
+    ...(tool.tags || []),
+    ...Object.keys(tool.input_schema?.properties || {}),
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+/**
+ * Score one tool against search terms. Higher is better; 0 means no match.
+ *
+ * Weights encode where a match is more trustworthy: the slug is authored, the
+ * description is authored, the tags are authored, and input field names are
+ * structural. A slug match therefore outranks a description match of the same
+ * term.
+ */
+export function scoreTool(tool, terms) {
+  if (!terms.length) return 0;
+
+  const slug = (tool.slug || "").toLowerCase();
+  const name = (tool.name || "").toLowerCase();
+  const desc = (tool.short_description || "").toLowerCase();
+  const tags = (tool.tags || []).map((t) => t.toLowerCase());
+  const fields = Object.keys(tool.input_schema?.properties || {}).map((f) => f.toLowerCase());
+  const all = haystack(tool).toLowerCase();
+
+  let score = 0;
+  for (const term of terms) {
+    let best = 0;
+
+    // Exact slug token, e.g. "cron" in "cron-expression-builder".
+    if (slug === term) best = Math.max(best, 100);
+    else if (slug.split("-").includes(term)) best = Math.max(best, 45);
+    else if (slug.includes(term)) best = Math.max(best, 30);
+
+    if (name.split(/\s+/).includes(term)) best = Math.max(best, 35);
+    else if (name.includes(term)) best = Math.max(best, 20);
+
+    if (tags.includes(term)) best = Math.max(best, 30);
+    else if (tags.some((t) => t.includes(term))) best = Math.max(best, 15);
+
+    if (fields.includes(term)) best = Math.max(best, 25);
+    else if (fields.some((f) => f.includes(term))) best = Math.max(best, 12);
+
+    if (desc.includes(term)) best = Math.max(best, 18);
+    if (all.includes(term)) best = Math.max(best, 8);
+
+    // Morphological variants. Slugs are terse by convention, so an agent
+    // searching "environment" should still reach "env-validator", and
+    // "validation" should reach "validate". Weighted below a real match so an
+    // exact hit always outranks a stemmed one.
+    if (best === 0 && sharesStem(term, slug, name, tags, desc)) {
+      best = Math.max(best, 14);
+    }
+
+    // Every term must land somewhere: an AND of ORs. Without this a tool
+    // matching one common word outranks one matching the whole query.
+    if (best === 0) return 0;
+    score += best;
+  }
+  return score;
+}
+
+/** Minimum shared prefix before a stem comparison counts as evidence. */
+const STEM_MIN = 4;
+
+/**
+ * Do a term and any vocabulary word share a meaningful prefix?
+ *
+ * "environment" and "env" share three characters, which is below the threshold,
+ * so the match comes from `all.includes` via the longer direction — this checks
+ * the other way too, so "env" finds "environment". A three-character floor keeps
+ * "e" from matching everything.
+ */
+function sharesStem(term, slug, name, tags, desc) {
+  const words = `${slug} ${name} ${tags.join(" ")} ${desc}`.split(/[^a-z0-9]+/i).filter(Boolean);
+  const t = term.toLowerCase();
+  for (const w of words) {
+    if (w.length < 3 || t.length < 3) continue;
+    const shared = w.startsWith(t) || t.startsWith(w) ? Math.min(w.length, t.length) : 0;
+    if (shared >= STEM_MIN) return true;
+    // Slug segments like "env" inside "env-validator" are whole words, and a
+    // longer term containing them is a morphological variant.
+    if (t.length >= STEM_MIN && w.length >= 3 && (t.includes(w) || w.includes(t))) return true;
+  }
+  return false;
+}
+
+/**
+ * Rank tools against a query.
+ *
+ * @param {object[]} tools
+ * @param {string}   query
+ * @param {object}   [opts]
+ * @param {number}   [opts.limit]     Max results. Default 10.
+ * @param {boolean}  [opts.includeAll] Return everything, unscored, when query is empty.
+ */
+export function searchTools(tools, query, opts = {}) {
+  const { limit = 10, includeAll = true } = opts;
+  const terms = tokenise(query);
+
+  if (terms.length === 0) {
+    return includeAll ? tools.slice(0, limit) : [];
+  }
+
+  return tools
+    .map((tool) => ({ tool, score: scoreTool(tool, terms) }))
+    .filter((r) => r.score > 0)
+    // Ties broken by slug so ordering is stable across runs and processes.
+    .sort((a, b) => b.score - a.score || a.tool.slug.localeCompare(b.tool.slug))
+    .slice(0, limit)
+    .map((r) => r.tool);
+}
+
+/**
+ * Resolve a slug for **execution**.
+ *
+ * Deliberately stricter than `resolveSlug`: only an exact slug or an
+ * unambiguous prefix is accepted. Fuzzy recovery — edit distance, scored search —
+ * is available when *describing* a tool, where guessing costs nothing, but
+ * running `env-validatr` and silently executing `env-validator` could hand an
+ * agent a result from a tool it never chose. Here a near miss becomes an error
+ * carrying the suggestion instead.
+ */
+export function resolveSlugStrict(tools, query) {
+  const q = (query || "").trim().toLowerCase();
+  if (!q) return { tool: null, ambiguous: [] };
+
+  const exact = tools.find((t) => t.slug.toLowerCase() === q);
+  if (exact) return { tool: exact, ambiguous: [] };
+
+  const prefix = tools.filter((t) => t.slug.toLowerCase().startsWith(q));
+  if (prefix.length === 1) return { tool: prefix[0], ambiguous: [] };
+  if (prefix.length > 1) return { tool: null, ambiguous: prefix.slice(0, 5) };
+
+  // Abbreviation that is not a slug prefix but a unique token match, e.g. "env"
+  // for "env-validator" is a prefix, but "validator" is not. Accept only when
+  // exactly one tool claims it.
+  const searched = searchTools(tools, q, { limit: 2, includeAll: false });
+  if (searched.length === 1) return { tool: searched[0], ambiguous: [] };
+
+  return { tool: null, ambiguous: searched.slice(0, 5) };
+}
+
+/**
+ * Resolve a possibly-abbreviated or partial slug to a real tool.
+ *
+ * Exact slug wins. Otherwise the shortest tool whose slug starts with the
+ * fragment is returned, which is what makes `nxb`'s abbreviations work here
+ * too — an agent that read one slug in a previous turn should be able to
+ * abbreviate it in the next.
+ *
+ * @returns {{tool: object|null, ambiguous: object[]}}
+ *   `ambiguous` is non-empty when the fragment matches several tools closely;
+ *   the caller should ask rather than guess.
+ */
+export function resolveSlug(tools, query) {
+  const q = (query || "").trim().toLowerCase();
+  if (!q) return { tool: null, ambiguous: [] };
+
+  const exact = tools.find((t) => t.slug.toLowerCase() === q);
+  if (exact) return { tool: exact, ambiguous: [] };
+
+  // Prefix match. A truncated prefix that fits several tools is genuinely
+  // ambiguous, and guessing would silently run the wrong tool — so it is
+  // reported instead. ("cron-v" resolves; "cron-" does not.)
+  const prefix = tools.filter((t) => t.slug.toLowerCase().startsWith(q));
+  if (prefix.length === 1) return { tool: prefix[0], ambiguous: [] };
+  if (prefix.length > 1) return { tool: null, ambiguous: prefix.slice(0, 5) };
+
+  // Scored search, so a prose reference or a morphological variant lands.
+  const searched = searchTools(tools, q, { limit: 5, includeAll: false });
+  if (searched.length === 1) return { tool: searched[0], ambiguous: [] };
+
+  // Typo recovery. `env-validatr` has no matching term at all, so the search
+  // above finds nothing; edit distance is the only signal that can help.
+  // A strictly closer candidate is treated as the answer — "env-validatr" is
+  // one edit from "env-validator" and five from "cron-validator", so the
+  // runner-up is noise rather than a genuine ambiguity.
+  const ranked = rankByDistance(tools, q, 5);
+  if (ranked.length > 0 && (ranked.length === 1 || ranked[0].distance < ranked[1].distance)) {
+    return { tool: ranked[0].tool, ambiguous: [] };
+  }
+  if (ranked.length > 1) {
+    return { tool: null, ambiguous: ranked.slice(0, 5).map((r) => r.tool) };
+  }
+
+  return { tool: null, ambiguous: searched.slice(0, 5) };
+}
+
+/**
+ * Tools ordered by edit distance to a query, nearest first.
+ *
+ * Exported separately from `suggest` because resolution needs the distances to
+ * reason about ties, while an error message only needs the names.
+ */
+export function rankByDistance(tools, query, limit = 3) {
+  const q = (query || "").trim().toLowerCase();
+  if (!q) return [];
+
+  return tools
+    .map((tool) => ({ tool, distance: levenshtein(q, tool.slug.toLowerCase()) }))
+    .filter((r) => r.distance <= Math.max(2, Math.ceil(r.tool.slug.length / 3)))
+    .sort((a, b) => a.distance - b.distance || a.tool.slug.localeCompare(b.tool.slug))
+    .slice(0, limit);
+}
+
+/**
+ * Near-miss suggestions for an error message.
+ *
+ * Ordered by edit distance against the slug, so the closest few are offered
+ * rather than an arbitrary slice of the catalogue.
+ */
+export function suggest(tools, query, limit = 3) {
+  return rankByDistance(tools, query, limit).map((r) => r.tool);
+}
+
+/** Levenshtein distance, two-row variant. */
+export function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let curr = new Array(b.length + 1);
+
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+/**
+ * Group tools by category, for a browsable overview.
+ *
+ * Sorted by group size descending so the largest, most useful categories lead.
+ */
+export function groupByCategory(tools) {
+  const map = new Map();
+  for (const tool of tools) {
+    const key = tool.category || "uncategorized";
+    if (!map.has(key)) map.set(key, []);
+    map.get(key).push(tool);
+  }
+  return [...map.entries()]
+    .map(([category, items]) => ({ category, tools: items }))
+    .sort((a, b) => b.tools.length - a.tools.length || a.category.localeCompare(b.category));
+}
+
+/**
+ * Summarise a tool's input contract in one line each, for a schema response.
+ *
+ * Reuses core's `describeSchema` so the wording matches the CLI and VS Code
+ * extension exactly — one rule, three surfaces.
+ */
+export function describeParameters(inputSchema) {
+  const properties = inputSchema?.properties || {};
+  const required = new Set(inputSchema?.required || []);
+
+  return Object.entries(properties).map(([key, prop]) => {
+    const bits = [];
+    bits.push(typeWord(prop));
+    if (required.has(key)) bits.push("required");
+    if (prop?.enum) bits.push(`one of: ${prop.enum.map((v) => JSON.stringify(v)).join(", ")}`);
+    if (prop?.default !== undefined) bits.push(`default: ${JSON.stringify(prop.default)}`);
+    if (typeof prop?.minLength === "number") bits.push(`minLength: ${prop.minLength}`);
+    if (typeof prop?.maxLength === "number") bits.push(`maxLength: ${prop.maxLength}`);
+    if (typeof prop?.minimum === "number") bits.push(`minimum: ${prop.minimum}`);
+    if (typeof prop?.maximum === "number") bits.push(`maximum: ${prop.maximum}`);
+    if (typeof prop?.pattern === "string") bits.push(`pattern: ${prop.pattern}`);
+    return { name: key, summary: bits.join(", "), description: prop?.description || "", required: required.has(key) };
+  });
+}
+
+function typeWord(prop) {
+  if (!prop?.type) return "any";
+  if (Array.isArray(prop.type)) return prop.type.join(" | ");
+  return prop.type;
+}