xlsx-for-ai 2.19.1 → 2.21.0

package/README.md

@@ -189,6 +189,12 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | `xlsx_form_controls` | Interactive widgets — checkboxes, buttons, drop-downs, spinners, scroll bars, list boxes — with linked cell + bounds. |
 | `xlsx_macros` | VBA macro presence + module-name heuristics + safety advice (does NOT extract source by policy). |
 
+### Integrations
+
+| Tool | What it does |
+|---|---|
+| `xlsx_post_slack` | Post a workbook to a Slack channel as a file attachment with an optional message. BYOA — the agent supplies the user's Slack bot token (`xoxb-…`); the token is forwarded to Slack and never persisted. Uses Slack's external upload flow. |
+
 Tool responses include a citation footer and a `_meta` block (tool name, version, tier, request ID, `powered_by`). Both pass through verbatim; nothing is stripped.
 
 ---

package/lib/client.js

@@ -12,6 +12,7 @@
  */
 
 const { readConfig } = require('./config');
+const { version: CLIENT_VERSION } = require('../package.json');
 
 const DEFAULT_API = 'https://api.xlsx-for-ai.dev';
 const TIMEOUT_MS  = 30_000;
@@ -32,7 +33,10 @@ async function fetchWithTimeout(url, init) {
 
 async function post(path, body, opts = {}) {
   const url = apiBase() + path;
-  const headers = { 'Content-Type': 'application/json' };
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-Client-Version': CLIENT_VERSION,
+  };
 
   if (opts.auth !== false) {
     const cfg = readConfig();

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/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');
@@ -826,6 +827,28 @@ const TOOLS = [
       required: ['file_path'],
     },
   },
+
+  {
+    name: 'xlsx_post_slack',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message. BYOA — the agent must pass the user\'s Slack bot token (xoxb-…). The token is forwarded to Slack and never stored server-side.\n' +
+      'Posts via Slack\'s 3-step external upload flow (files.getUploadURLExternal → upload → files.completeUploadExternal), which is the only sanctioned path as of 2024+.\n\n' +
+      'USE WHEN: the user asks "post this workbook to #channel," "share this with the team in Slack," or any other outbound-file-to-Slack request. The agent has just produced or modified a workbook and wants to deliver it. ' +
+      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'DO NOT USE WHEN: the file lives in a Slack channel and you want to READ it (that\'s the inbound Manual-Mode-Detector pattern, not this). Or when there is no Slack bot token available — the user must have installed a Slack app with files:write scope.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to post.' },
+        channel: { type: 'string', description: 'Slack channel ID (C…/G…) the file should land in. Channel names like #general are NOT accepted — resolve to a channel ID first.' },
+        slack_token: { type: 'string', description: 'Slack bot token (xoxb-…). Forwarded to Slack; never persisted by us.' },
+        message: { type: 'string', description: 'Optional: message to post alongside the file (Slack\'s initial_comment).' },
+        filename: { type: 'string', description: 'Optional: filename Slack will display. Defaults to the basename of file_path.' },
+      },
+      required: ['file_path', 'channel', 'slack_token'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1039,6 +1062,20 @@ async function dispatchTool(name, args) {
     });
   }
 
+  // xlsx_post_slack: outbound file-to-Slack. Top-level fields, not the
+  // standard {file_b64, options} shape — channel + slack_token + message
+  // + filename live alongside file_b64 in the server route's body schema.
+  if (name === 'xlsx_post_slack') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      channel: args.channel,
+      slack_token: args.slack_token,
+    };
+    if (args.message !== undefined) body.message = args.message;
+    body.filename = args.filename || path.basename(args.file_path);
+    return callTool('xlsx_post_slack', body);
+  }
+
   // All other tools (list_sheets, schema, hyperlinks, conditional_formats,
   // styles, etc.) — single-file relay. Forward any common option keys the
   // routes accept so we don't silently drop them. New keys added here as
@@ -1061,16 +1098,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.1",
+  "version": "2.21.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"