@nexusbloom/mcp-server 1.0.3 → 2.0.2

package/README.md

@@ -0,0 +1,110 @@
+# @nexusbloom/mcp-server
+
+MCP (Model Context Protocol) server for [NexusBloom](https://nexusbloom.dev).
+
+An agent connects once and can then **discover tools by what it wants to do**,
+read their exact parameters, and run them. No local runtime, no credentials
+beyond the API, no state on disk.
+
+Built on [`@nexusbloom/core`](https://www.npmjs.com/package/@nexusbloom/core) —
+the same engine the CLI, the VS Code extension and the embed use, so a type rule
+or validation change lands once and every surface inherits it.
+
+## Install
+
+Add it to any MCP client that speaks stdio:
+
+```jsonc
+{
+  "mcpServers": {
+    "nexusbloom": {
+      "command": "npx",
+      "args": ["-y", "@nexusbloom/mcp-server"]
+    }
+  }
+}
+```
+
+Or run it directly:
+
+```bash
+npx @nexusbloom/mcp-server
+```
+
+## Configuration
+
+All variables are optional.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `NEXUSBLOOM_API_KEY` | *(none)* | API key. Without it the server runs anonymously under the free-tier rate limit. |
+| `NEXUSBLOOM_API_URL` | `https://nexusbloom.dev/api` | API base. Accepts the bare host or the full `/api` form. |
+| `NEXUSBLOOM_MCP_TIMEOUT_MS` | `15000` | Per-request timeout. |
+| `NEXUSBLOOM_MCP_CACHE_TTL_MS` | `60000` | Tool-list cache lifetime. `0` disables caching. |
+| `NEXUSBLOOM_MCP_DEBUG` | *(off)* | `1` logs requests to stderr. |
+
+Diagnostics always go to **stderr**; stdout is the MCP transport and writing
+anything else there corrupts the protocol.
+
+## What an agent sees
+
+Every published tool is advertised as an MCP tool **named by its slug**, with its
+real JSON Schema — so it can be called directly:
+
+```jsonc
+{ "name": "env-validator", "arguments": { "env_content": "DEBUG=true" } }
+```
+
+Alongside it is a `nexusbloom` meta-tool for when the agent does not yet know
+which tool it wants:
+
+| Command | What it does |
+|---|---|
+| `{"command":"search","query":"validate env file"}` | Rank tools by intent. Works on prose, not just slug fragments. |
+| `{"command":"list"}` | Every published tool, one line each. |
+| `{"command":"schema","slug":"…"}` | Exact parameters, plus a ready-to-send example invocation. |
+| `{"command":"run","slug":"…","params":{…}}` | Execute a tool. |
+
+### Errors are actionable
+
+Failures come back as an `isError` result with a stable `code` and a
+`retryable` flag, so an agent can decide whether to retry rather than parsing
+prose:
+
+```jsonc
+{
+  "success": false,
+  "error": "No tool named \"env-validatr\" is published. Closest matches: env-validator. …",
+  "code": "TOOL_NOT_FOUND",
+  "retryable": false
+}
+```
+
+A wrong slug suggests the right one. A missing argument names the field. A
+timeout is marked retryable; a validation failure is not.
+
+### Validation before the request
+
+Input is checked against the tool's own schema before anything is sent, so a
+malformed call costs no API quota and returns an error naming the exact field.
+The API remains authoritative — this only rejects what is provably wrong.
+
+## Design notes
+
+**Execution never guesses.** Slugs resolve by exact match or unambiguous
+abbreviation only. Asking for `env-validatr` is an error with a suggestion, not
+a silent run of `env-validator` — a wrong-but-successful result is worse than a
+wrong-but-obvious failure.
+
+**Search is lexical, not embedded.** Ranking runs with no network, no model and
+no vector store, is deterministic, and returns identical output for identical
+input. That makes it testable and fast enough to run on every call. It matches
+across slug, name, description, tags and input field names, with light
+morphological handling so "environment" reaches `env-validator`.
+
+**Failures degrade, they do not crash.** An unreachable API produces a working
+server that explains itself on each request, not a process that exits or a host
+that concludes the server is broken. A failed catalogue refresh keeps serving the
+last good list rather than emptying it.
+
+

package/index.js

@@ -1,422 +1,84 @@
 #!/usr/bin/env node
-
 /**
  * @nexusbloom/mcp-server
  *
- * MCP (Model Context Protocol) server for NexusBloom.
- * AI agents use a single tool to discover, inspect, and execute
- * any tool in the NexusBloom ecosystem.
- *
- * No Supabase credentials needed. Connects to the NexusBloom API.
+ * MCP server for NexusBloom. Agents discover tools by intent, read their exact
+ * parameters, and execute them — no credentials beyond the API, no local
+ * runtime, no state.
  *
  * Usage:
  *   npx @nexusbloom/mcp-server
  *
- * Environment variables (all optional):
- *   NEXUSBLOOM_API_KEY    — API key for authenticated tool execution
- *   NEXUSBLOOM_API_URL    — API base URL (default: https://nexusbloom.dev/api)
+ * Environment (all optional):
+ *   NEXUSBLOOM_API_KEY          API key for authenticated execution
+ *   NEXUSBLOOM_API_URL          API base (default: https://nexusbloom.dev/api)
+ *   NEXUSBLOOM_MCP_TIMEOUT_MS   Request timeout in ms (default: 15000)
+ *   NEXUSBLOOM_MCP_CACHE_TTL_MS Tool-list cache TTL in ms (default: 60000)
+ *   NEXUSBLOOM_MCP_DEBUG        "1" to log requests to stderr
+ *
+ * stdout is the MCP transport. All diagnostics go to stderr.
  */
 
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-
-// ---------------------------------------------------------------------------
-// Configuration
-// ---------------------------------------------------------------------------
 
-const API_KEY = process.env.NEXUSBLOOM_API_KEY || "";
-const API_URL = (process.env.NEXUSBLOOM_API_URL || "https://nexusbloom.dev/api").replace(/\/+$/, "");
-
-// Optional: if the API URL is a local dev server, allow insecure HTTPS
-const FETCH_OPTS = API_URL.includes("localhost") || API_URL.includes("127.0.0.1")
-  ? {}
-  : {};
-
-function apiHeaders() {
-  const headers = { "Content-Type": "application/json" };
-  if (API_KEY) headers["Authorization"] = `Bearer ${API_KEY}`;
-  return headers;
+import { ApiClient } from "./src/client.js";
+import { candidateRoots, loadConfig } from "./src/config.js";
+import { checkConnectivity } from "./src/handlers.js";
+import { ManifestCache } from "./src/manifests.js";
+import { createServer } from "./src/server.js";
+
+/** Compose every piece from a config, for both `main()` and tests. */
+export function createApp(config, deps = {}) {
+  const client = new ApiClient(config, deps);
+  const cache = new ManifestCache(client, { ttlMs: config.cacheTtlMs, now: deps.now });
+  const { server, handlers } = createServer({ client, cache, config });
+  return { client, cache, server, handlers, config };
 }
 
-// ---------------------------------------------------------------------------
-// Tool manifest cache
-// ---------------------------------------------------------------------------
-
-let toolsCache = null;
-let toolsCacheTime = 0;
-const CACHE_TTL = 30_000; // 30 seconds
-
-async function fetchTools() {
-  const now = Date.now();
-  if (toolsCache && now - toolsCacheTime < CACHE_TTL) return toolsCache;
-
-  try {
-    const res = await fetch(`${API_URL}/tools`, {
-      headers: apiHeaders(),
-      ...FETCH_OPTS,
-    });
-    if (!res.ok) {
-      console.error(`API returned ${res.status} for /tools`);
-      return toolsCache || [];
-    }
-    const json = await res.json();
-    const tools = (json.tools || json.data || json || []).filter(Boolean);
-
-    toolsCache = tools.map(t => ({
-      slug: t.slug,
-      name: t.name,
-      short_description: t.short_description || t.description || "",
-      tags: (t.tags || []).flat().filter(Boolean),
-      category: t.category || "Platform Tools",
-      icon: t.icon || "🔧",
-      version: t.version || "1.0.0",
-      type: "builtin",
-      input_schema: t.input_schema || null,
-    }));
-    toolsCacheTime = now;
-    return toolsCache;
-  } catch (err) {
-    console.error("Failed to fetch tools:", err.message);
-    return toolsCache || [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Fetch a single tool's schema
-// ---------------------------------------------------------------------------
-
-async function fetchToolSchema(slug) {
-  // Primary: fetch manifest from /api/run/{slug} (the reliable endpoint)
-  try {
-    const res = await fetch(`${API_URL}/run/${encodeURIComponent(slug)}`, {
-      headers: apiHeaders(),
-      ...FETCH_OPTS,
-    });
-    if (res.ok) {
-      // API returns { success: true, data: { manifest: { ... } } }
-      const body = await res.json();
-      const manifest = body.data?.manifest || body.manifest || body;
-      if (manifest && manifest.slug) {
-        return {
-          slug: manifest.slug,
-          name: manifest.name,
-          description: manifest.short_description || "",
-          tags: manifest.tags || [],
-          input_schema: manifest.input_schema || {},
-          output_schema: manifest.output_schema || {},
-          icon: manifest.icon || "🔧",
-          version: manifest.version || "1.0.0",
-          category: manifest.category || "Platform Tools",
-        };
-      }
-    }
-  } catch (err) {
-    console.error(`Failed to fetch manifest for ${slug}:`, err.message);
-  }
-
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Execute a tool
-// ---------------------------------------------------------------------------
-
-async function executeTool(slug, params) {
-  const res = await fetch(`${API_URL}/run/${encodeURIComponent(slug)}`, {
-    method: "POST",
-    headers: apiHeaders(),
-    body: JSON.stringify(params),
-    ...FETCH_OPTS,
-  });
-
-  if (!res.ok) {
-    const err = await res.json().catch(() => ({ error: res.statusText }));
-    throw new Error(err.error || `API returned ${res.status}`);
-  }
-
-  const json = await res.json();
-  return {
-    success: true,
-    data: json.data || json,
-    tool: slug,
-    execution: "live",
-  };
-}
-
-// ---------------------------------------------------------------------------
-// MCP Server
-// ---------------------------------------------------------------------------
-
-const server = new Server(
-  {
-    name: "nexusbloom-mcp",
-    version: "1.0.0",
-  },
-  {
-    capabilities: {
-      tools: {},
-    },
-  },
-);
-
-// ---- ListTools ----
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  const tools = await fetchTools();
-
-  const toolList = tools.map((t) => ({
-    name: t.slug,
-    description: `${t.name}: ${t.short_description || "No description"}${
-      t.category ? ` [${t.category}]` : ""
-    }`,
-    inputSchema: t.input_schema || {
-      type: "object",
-      properties: {},
-    },
-  }));
-
-  // Also expose the meta-tool for list/schema/run
-  toolList.push({
-    name: "nexusbloom",
-    description: `Meta-tool to list, inspect, or run any NexusBloom tool. Use this when you need to discover tools or get schema details.`,
-    inputSchema: {
-      type: "object",
-      properties: {
-        command: {
-          type: "string",
-          enum: ["list", "schema", "run"],
-          description:
-            "What to do: 'list' returns all available tools, 'schema' returns a tool's full input/output schema, 'run' executes a tool",
-        },
-        slug: {
-          type: "string",
-          description:
-            "Tool slug (required for 'schema' and 'run' commands). Use 'list' first to see available slugs.",
-        },
-        params: {
-          type: "object",
-          description:
-            "Input parameters matching the tool's input_schema (required for 'run' command). Use 'schema' first to see the expected format.",
-        },
-      },
-      required: ["command"],
-    },
-  });
-
-  return { tools: toolList };
-});
-
-// ---- CallTool ----
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name: toolName, arguments: args } = request.params;
-
-  // ── Direct tool execution by slug ──────────────────────────────
-  // AI agents can call any tool directly by its slug name.
-  // The tool's own input_schema defines the expected parameters.
-  // We verify the slug exists by checking against our tool list.
-  if (toolName !== "nexusbloom") {
-    const tools = await fetchTools();
-    const matched = tools.find((t) => t.slug === toolName);
-    if (!matched) {
-      return {
-        content: [{ type: "text", text: `Unknown tool: "${toolName}". Use the "nexusbloom" tool with command "list" to see available tools.` }],
-        isError: true,
-      };
-    }
-    try {
-      const result = await executeTool(toolName, args || {});
-      const formatted = JSON.stringify(result.data, null, 2);
-      return {
-        content: [
-          { type: "text", text: `# ${matched.name} (${toolName})\n\n\`\`\`json\n${formatted}\n\`\`\`` },
-          { type: "resource", resource: { text: formatted, uri: "data:application/json,", mimeType: "application/json" } },
-        ],
-      };
-    } catch (err) {
-      return { content: [{ type: "text", text: `Error executing "${toolName}": ${err.message}` }], isError: true };
-    }
-  }
-
-  // ── Legacy meta-tool: list/schema/run via sub-commands ─────────
-  const command = args?.command;
-
-  if (!command || !["list", "schema", "run"].includes(command)) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: "Invalid command. Use one of: 'list', 'schema', 'run'.",
-        },
-      ],
-      isError: true,
-    };
-  }
-
-  // ---- COMMAND: list ----
-  if (command === "list") {
-    const tools = await fetchTools();
-
-    const summary = tools
-      .map((t) => `• ${t.icon} **${t.name}** (\`${t.slug}\`) — ${t.short_description || "No description"} [${t.category}]`)
-      .join("\n");
-
-    return {
-      content: [
-        {
-          type: "text",
-          text: `# NexusBloom Tools\n\nAvailable tools: ${tools.length}\n\n${summary}\n\n---\nTo inspect a tool's schema, call with \`command: "schema"\` and its \`slug\`.\nTo run a tool, call with \`command: "run"\`, its \`slug\`, and matching \`params\`.`,
-        },
-        {
-          type: "resource",
-          resource: {
-            text: JSON.stringify(tools, null, 2),
-            uri: "data:application/json,",
-            mimeType: "application/json",
-          },
-        },
-      ],
-    };
-  }
-
-  // ---- COMMAND: schema ----
-  if (command === "schema") {
-    const slug = args?.slug;
-    if (!slug) {
-      return {
-        content: [{ type: "text", text: "Missing required parameter: 'slug'" }],
-        isError: true,
-      };
-    }
-
-    const schema = await fetchToolSchema(slug);
-    if (!schema) {
-      return {
-        content: [{ type: "text", text: `Tool "${slug}" not found. Use 'list' to see available tools.` }],
-        isError: true,
-      };
-    }
-
-    const inputProps = schema.input_schema?.properties || {};
-    const requiredFields = schema.input_schema?.required || [];
-    const paramDocs = Object.entries(inputProps)
-      .map(([key, prop]) => {
-        const req = requiredFields.includes(key) ? " (required)" : "";
-        const def = prop.default !== undefined ? ` (default: ${JSON.stringify(prop.default)})` : "";
-        const enum_ = prop.enum ? ` [${prop.enum.join(", ")}]` : "";
-        return `  • \`${key}\`: ${prop.type || "any"}${req}${def}${enum_} — ${prop.description || ""}`;
-      })
-      .join("\n");
-
-    return {
-      content: [
-        {
-          type: "text",
-          text: `# ${schema.icon} ${schema.name}\n\n**Slug:** \`${schema.slug}\`\n**Description:** ${schema.description}\n**Category:** ${schema.category || "Uncategorized"}\n**Version:** ${schema.version}\n\n## Input Parameters\n${paramDocs || "  _(no parameters)_"}\n\nTo run this tool, call with \`command: "run"\`, \`slug: "${schema.slug}"\`, and \`params\` matching the above schema.`,
-        },
-        {
-          type: "resource",
-          resource: {
-            text: JSON.stringify(schema, null, 2),
-            uri: "data:application/json,",
-            mimeType: "application/json",
-          },
-        },
-      ],
-    };
-  }
+/**
+ * Start the server.
+ *
+ * @returns {Promise<{close: () => Promise<void>}>}
+ */
+export async function main(env = process.env, deps = {}) {
+  const config = loadConfig(env);
+  const app = createApp(config, deps);
 
-  // ---- COMMAND: run ----
-  if (command === "run") {
-    const slug = args?.slug;
-    const params = args?.params || {};
+  // Probe before serving. A failure here is reported and then ignored: the
+  // server still starts, because a transient DNS blip should not require
+  // restarting an agent host.
+  const connectivity = await checkConnectivity(app.client, candidateRoots(env), config, deps);
+  process.stderr.write(`${connectivity.report}\n`);
 
-    if (!slug) {
-      return {
-        content: [{ type: "text", text: "Missing required parameter: 'slug'" }],
-        isError: true,
-      };
-    }
+  const transport = new StdioServerTransport();
 
+  // Close on the signals a host actually sends. Without this the process
+  // lingers after the parent exits and leaves orphan MCP servers behind.
+  const shutdown = async () => {
     try {
-      const result = await executeTool(slug, params);
-      return {
-        content: [
-          {
-            type: "text",
-            text: `# Tool Result: ${slug}\n\n**Execution:** ${result.execution}\n\`\`\`json\n${JSON.stringify(result.data, null, 2)}\n\`\`\``,
-          },
-          {
-            type: "resource",
-            resource: {
-              text: JSON.stringify(result, null, 2),
-              uri: "data:application/json,",
-              mimeType: "application/json",
-            },
-          },
-        ],
-      };
-    } catch (err) {
-      return {
-        content: [{ type: "text", text: `Error executing "${slug}": ${err.message}` }],
-        isError: true,
-      };
+      await app.server.close();
+    } catch {
+      /* already closing */
     }
-  }
-});
+    app.client.abortAll();
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
 
-// ---- Start ----
-async function main() {
-  try {
-    // Verify API connectivity — try multiple possible API URLs
-    const apiUrlCandidates = [
-      API_URL,
-      API_URL.replace("/api", ""), // base domain without /api
-    ];
+  await app.server.connect(transport);
+  process.stderr.write("NexusBloom MCP server running on stdio\n");
 
-    let connected = false;
-    for (const url of apiUrlCandidates) {
-      try {
-        const testUrl = url.includes("/api") ? `${url}/tools` : `${url}/api/tools`;
-        const res = await fetch(testUrl, { ...FETCH_OPTS });
-        if (res.ok || res.status === 429) {
-          console.error(`NexusBloom MCP server connected to ${url}`);
-          connected = true;
-          break;
-        } else if (res.status === 404) {
-          // Try without /tools path
-          const res2 = await fetch(url, { ...FETCH_OPTS });
-          if (res2.ok) {
-            console.error(`NexusBloom MCP server connected to ${url}`);
-            connected = true;
-            break;
-          }
-        }
-      } catch (_) {
-        // Continue to next candidate
-      }
-    }
+  return { ...app, transport, close: shutdown };
+}
 
-    if (!connected) {
-      console.error(
-        `WARNING: Could not reach NexusBloom API. ` +
-        `The MCP server will start in degraded mode — tool execution requires a working API.\n` +
-        `Checked endpoints:\n` +
-        apiUrlCandidates.map(u => `  - ${u.includes("/api") ? `${u}/tools` : `${u}/api/tools`}`).join("\n") + "\n" +
-        `To fix: ensure NEXUSBLOOM_API_URL is set correctly (default: https://nexusbloom.dev/api)\n` +
-        `Or deploy the platform API and verify the Vercel rewrite from your frontend project.`
-      );
-    }
+// Only run when executed directly, so importing this module in a test does not
+// hijack stdio.
+const invokedDirectly =
+  process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
 
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("NexusBloom MCP server running on stdio");
-  } catch (err) {
-    console.error("Fatal error:", err);
+if (invokedDirectly) {
+  main().catch((err) => {
+    process.stderr.write(`Fatal error starting MCP server: ${err?.stack || err}\n`);
     process.exit(1);
-  }
+  });
 }
-
-main();

package/package.json

@@ -1,16 +1,43 @@
 {
   "name": "@nexusbloom/mcp-server",
-  "version": "1.0.3",
-  "description": "MCP server for NexusBloom — AI agents discover and execute tools through a single interface. No Supabase credentials needed, just connect to our API.",
+  "version": "2.0.2",
+  "description": "MCP server for NexusBloom — agents discover tools by intent, read exact schemas, and execute them. Built on @nexusbloom/core.",
   "type": "module",
   "main": "index.js",
   "bin": {
     "nexusbloom-mcp": "index.js"
   },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
     "node": ">=18"
   },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agents",
+    "tools",
+    "nexusbloom"
+  ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.8.0"
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "@nexusbloom/core": "^1.0.0"
+  },
+  "scripts": {
+    "test": "node --test --import ./test/setup.mjs test/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage --import ./test/setup.mjs test/*.test.js",
+    "test:watch": "node --test --watch --import ./test/setup.mjs test/*.test.js",
+    "test:src-only": "node --test --import ./test/setup.mjs test/config.test.js test/errors.test.js test/manifests.test.js test/discovery.test.js test/client.test.js test/validate.test.js test/render.test.js test/cache.test.js test/handlers.test.js",
+    "shell": "node scripts/mcp-shell.mjs",
+    "shell:mock": "node scripts/mcp-shell.mjs --mock",
+    "mock-api": "node scripts/mock-api.mjs",
+    "lint": "node --check index.js && for f in src/*.js; do node --check \"$f\" || exit 1; done"
   }
 }