xlsx-for-ai 2.19.0 → 2.20.0

package/lib/discover.js

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * Dynamic tool catalog discovery.
+ *
+ * At MCP server startup we ask the hosted API "what tools do you support?" so
+ * new server-side tools appear in users' agents WITHOUT us re-publishing the
+ * npm package or re-signing the .mcpb. The thin client stays thin; the catalog
+ * lives where the tools live.
+ *
+ * Endpoint: GET ${apiBase}/api/v1/tools/list
+ *   -> { tools: [{ name, description, inputSchema, ... }, ...], version? }
+ *
+ * Behaviour:
+ *   - Fetch with a short timeout (3s — startup-blocking, must not hang an agent).
+ *   - On success: cache to ~/.xlsx-for-ai/tools-cache.json with TTL.
+ *   - On failure (404, network, timeout): use the cache if fresh; else use the
+ *     baked-in static fallback the caller passes in.
+ *   - The local fallback is the floor, NEVER the ceiling. Server > cache > static.
+ *
+ * Why dynamic: today every new server-side tool requires a TOOLS array edit +
+ * version bump + npm publish + (post-Phase 4.5) .mcpb rebuild + Anthropic
+ * directory re-review. With dynamic discovery the only release vehicle is the
+ * server deploy. See ~/xlsx-for-ai-internal/ROADMAP.md Phase 4.5.
+ */
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+
+const { apiBase } = require('./client');
+const { configPath } = require('./config');
+
+const DISCOVER_TIMEOUT_MS = 3_000;
+const CACHE_TTL_MS        = 24 * 60 * 60 * 1000;  // 24h
+
+function cachePath() {
+  // Scope the cache by API base so switching between prod / staging / a custom
+  // XLSX_FOR_AI_API doesn't reuse a catalog from a different host. Co-located
+  // with config.json so XFA_CONFIG_DIR override flows through for tests.
+  const baseHash = crypto.createHash('sha256').update(apiBase()).digest('hex').slice(0, 16);
+  return path.join(path.dirname(configPath()), `tools-cache-${baseHash}.json`);
+}
+
+function readCache() {
+  try {
+    const raw = fs.readFileSync(cachePath(), 'utf8');
+    const obj = JSON.parse(raw);
+    if (!obj || !Array.isArray(obj.tools) || typeof obj.fetched_at !== 'number') return null;
+    return obj;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeCache(tools) {
+  try {
+    const finalPath = cachePath();
+    const dir = path.dirname(finalPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const payload = { fetched_at: Date.now(), tools };
+    // Atomic write: temp file in the same dir + rename. Avoids torn writes
+    // visible to a concurrent reader (e.g., two MCP server processes starting
+    // at once on the same host).
+    const tmpPath = `${finalPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmpPath, finalPath);
+  } catch (_) {
+    // Cache write failures are non-fatal — the next startup just re-fetches.
+  }
+}
+
+function isCacheFresh(entry) {
+  if (!entry || typeof entry.fetched_at !== 'number') return false;
+  const now = Date.now();
+  // Future timestamps are never "fresh" — clock skew or tampering would
+  // otherwise pin a cache forever (negative age < TTL is always true).
+  if (entry.fetched_at > now) return false;
+  return (now - entry.fetched_at) < CACHE_TTL_MS;
+}
+
+async function fetchRemoteCatalog() {
+  const url = apiBase() + '/api/v1/tools/list';
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DISCOVER_TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) {
+    const e = new Error(`tools/list returned HTTP ${res.status}`);
+    e.status = res.status;
+    throw e;
+  }
+  const body = await res.json();
+  if (!body || !Array.isArray(body.tools)) {
+    throw new Error('tools/list response missing tools array');
+  }
+  return body.tools;
+}
+
+/**
+ * mergeTools: server catalog wins on name collision; baked-in tools fill gaps.
+ * Order: every remote tool first (preserving server order), then any baked-in
+ * tool whose name isn't in the remote set. This way the most up-to-date
+ * description always wins, but we never lose a tool the client knows how to
+ * dispatch even if the server temporarily forgets it.
+ */
+function mergeTools(remote, baked) {
+  const out = [];
+  const seen = new Set();
+  for (const t of remote) {
+    if (!t || typeof t.name !== 'string') continue;
+    if (seen.has(t.name)) continue;  // dedupe within remote too — first wins
+    out.push(t);
+    seen.add(t.name);
+  }
+  for (const t of baked) {
+    if (!t || typeof t.name !== 'string') continue;  // tolerate malformed baked entries
+    if (seen.has(t.name)) continue;
+    out.push(t);
+    seen.add(t.name);
+  }
+  return out;
+}
+
+/**
+ * Resolve the tool catalog the MCP server should expose.
+ *
+ * @param {Array} bakedFallback - the static TOOLS array embedded in the package
+ * @returns {Promise<{tools: Array, source: string}>}
+ *   source ∈ 'remote' | 'cache' | 'cache-stale' | 'static'
+ */
+async function resolveCatalog(bakedFallback) {
+  // 1. Try remote. On success, cache and merge.
+  try {
+    const remote = await fetchRemoteCatalog();
+    writeCache(remote);
+    return { tools: mergeTools(remote, bakedFallback), source: 'remote' };
+  } catch (err) {
+    // fall through
+  }
+
+  // 2. Fresh cache wins over baked.
+  const cache = readCache();
+  if (isCacheFresh(cache)) {
+    return { tools: mergeTools(cache.tools, bakedFallback), source: 'cache' };
+  }
+
+  // 3. Stale cache STILL wins over baked. The cache represents what the
+  //    server said last time we could reach it; that's by definition more
+  //    authoritative than what was hardcoded into this client version. The
+  //    baked-in TOOLS still get merged in as the floor — mergeTools dedupes
+  //    by name with cache entries winning, so users never lose a tool that
+  //    used to be available even if the server temporarily forgets it.
+  if (cache) {
+    return { tools: mergeTools(cache.tools, bakedFallback), source: 'cache-stale' };
+  }
+
+  // 4. Last resort: the baked-in fallback.
+  return { tools: bakedFallback, source: 'static' };
+}
+
+module.exports = {
+  resolveCatalog,
+  // exported for tests
+  _internal: { mergeTools, readCache, writeCache, cachePath, fetchRemoteCatalog },
+};

package/lib/register.js

@@ -8,6 +8,12 @@
  *
  * Writes result to config and returns { client_id, api_key }.
  * Idempotent: if config already has api_key, returns it immediately.
+ *
+ * CI gate: when running in a CI environment (CI=true, GITHUB_ACTIONS=true,
+ * or XLSX_FOR_AI_CI=1) we skip registration entirely. This stops automated
+ * smoke tests + clean-install verifications from polluting the production
+ * client_id pool with synthetic per-publish UUIDs that don't represent
+ * real human users.
  */
 
 const os = require('os');
@@ -19,7 +25,33 @@ function platform() {
   return `${process.platform}-${process.arch}`;
 }
 
+// Detect common CI signals. Bias is toward FALSE POSITIVES on the CI side
+// (a real user running with CI=true in their shell will get the same skip).
+// Those cases are vanishingly rare, and the cost of a missed CI gate is much
+// higher: polluted analytics + 1M MAU dilution.
+function isCiEnvironment() {
+  if (process.env.XLSX_FOR_AI_CI === '1') return true;
+  // GitHub Actions auto-sets CI=true AND GITHUB_ACTIONS=true. Other major
+  // providers also set CI=true (CircleCI, GitLab, Travis, Azure Pipelines,
+  // BuildKite, Drone, Jenkins via plugin).
+  if (process.env.CI === 'true' || process.env.CI === '1') return true;
+  if (process.env.GITHUB_ACTIONS === 'true') return true;
+  return false;
+}
+
 async function ensureRegistered() {
+  if (isCiEnvironment()) {
+    // Return a sentinel handle. api_key prefix 'xfa_ci_' is invalid format,
+    // so any tool call would 401 with a clear "Invalid API key" rather than
+    // silently using a leaked real key. CI smoke tests that only call
+    // --version short-circuit before reaching this anyway.
+    return {
+      client_id: '00000000-0000-0000-0000-000000000000',
+      api_key: 'xfa_ci_skip_registration',
+      ci_skipped: true,
+    };
+  }
+
   const cfg = readConfig();
   if (cfg && cfg.api_key && cfg.client_id) {
     return { client_id: cfg.client_id, api_key: cfg.api_key };
@@ -34,4 +66,4 @@ async function ensureRegistered() {
   return { client_id: data.client_id, api_key: data.api_key };
 }
 
-module.exports = { ensureRegistered };
+module.exports = { ensureRegistered, isCiEnvironment };

package/mcp.js

@@ -16,6 +16,7 @@ const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontext
 const { ensureRegistered } = require('./lib/register');
 const { callTool }         = require('./lib/client');
 const { fallbackRead }     = require('./lib/fallback-read');
+const { resolveCatalog }   = require('./lib/discover');
 const fs                   = require('fs');
 const fsPromises           = require('fs/promises');
 const path                 = require('path');
@@ -1061,16 +1062,33 @@ async function dispatchTool(name, args) {
 async function main() {
   await ensureRegistered();
 
+  // Dynamic tool catalog: query the hosted API once at startup so new
+  // server-side tools appear without re-publishing this npm package.
+  // resolveCatalog returns the baked-in TOOLS as last-resort fallback so
+  // we never fail-open on a transient network blip. See lib/discover.js.
+  let catalog;
+  try {
+    catalog = await resolveCatalog(TOOLS);
+  } catch (_) {
+    catalog = { tools: TOOLS, source: 'static-fallback' };
+  }
+  const liveTools = catalog.tools;
+
   const server = new Server(
     { name: 'xlsx-for-ai', version: require('./package.json').version },
     { capabilities: { tools: {} } }
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: liveTools }));
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    const tool = TOOLS.find((t) => t.name === name);
+    // Accept any tool the live catalog advertises. dispatchTool has a
+    // generic single-file relay path (see end of dispatchTool) that handles
+    // any unknown tool name by forwarding {file_b64, options} to the server,
+    // so dynamically-discovered tools "just work" as long as their server
+    // contract matches that shape.
+    const tool = liveTools.find((t) => t.name === name);
     if (!tool) {
       return {
         content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "The MCP server that makes LLMs reliable on real-world Excel spreadsheets. Thin npm client over a hosted API — read, write, diff, redact, and supervise .xlsx files from any MCP-aware agent.",
   "main": "index.js",
   "bin": {
@@ -16,6 +16,7 @@
     "lib/config.js",
     "lib/register.js",
     "lib/fallback-read.js",
+    "lib/discover.js",
     "README.md",
     "SECURITY.md",
     "LICENSE"