xlsx-for-ai 3.0.0 → 3.0.2

package/README.md

@@ -1,10 +1,8 @@
 # xlsx-for-ai
 
-> **⚠️ MCP users on 2.25.0–2.26.0: upgrade.** Those versions crash the MCP server on startup (missing `lib/annotations.js`, fixed in 2.26.1). Run `npm install -g xlsx-for-ai@latest` and restart your MCP client. Or switch to the `npx -y` config snippets below so future versions self-heal on every restart.
-
 **The missing reliability layer that makes spreadsheet reasoning production-grade for LLMs.**
 
-A thin npm client over a hosted API. Install once, add to your agent config, and your agent gets 48 production-grade tools for reading, writing, diffing, redacting, healing, and cryptographically attesting `.xlsx` files — engine complexity runs server-side, engine IP stays private.
+A thin npm client over a hosted API. Install once, add to your agent config, and your agent gets 50 production-grade tools for reading, writing, diffing, redacting, healing, and cryptographically attesting `.xlsx` files — engine complexity runs server-side, engine IP stays private.
 
 ```bash
 npm install -g xlsx-for-ai
@@ -24,7 +22,7 @@ Add `xlsx-for-ai` as a tool server in your agent runtime. First invocation auto-
 
 **Easiest: one-click install via the `.mcpb` bundle.** Download and drag into Claude Desktop (Settings → Extensions):
 
-**[xlsx-for-ai-2.0.0.mcpb](https://github.com/senoff/xlsx-for-ai/releases/latest/download/xlsx-for-ai-2.0.0.mcpb)** *(latest release)*
+**[xlsx-for-ai.mcpb](https://github.com/senoff/xlsx-for-ai/releases/latest/download/xlsx-for-ai.mcpb)** *(latest release — version-agnostic stable filename, always serves the current bundle)*
 
 The bundle includes the full npm package and registers all MCP tools automatically. No manual config edits needed.
 
@@ -41,7 +39,7 @@ The bundle includes the full npm package and registers all MCP tools automatical
 }
 ```
 
-Verify either path: restart Claude Desktop, open a new conversation, and ask "what MCP tools do you have?" — 48 `xlsx_*` tools should appear, including `xlsx_doctor` (one-call health report — try it first on any unknown workbook).
+Verify either path: restart Claude Desktop, open a new conversation, and ask "what MCP tools do you have?" — 50 `xlsx_*` tools should appear, including `xlsx_doctor` (one-call health report — try it first on any unknown workbook).
 
 ### Cursor
 
@@ -58,7 +56,7 @@ Config file: `~/.cursor/mcp.json`
 }
 ```
 
-Verify: open Cursor settings → MCP → confirm `xlsx-for-ai` shows 6 tools.
+Verify: open Cursor settings → MCP → confirm `xlsx-for-ai` shows 50 `xlsx_*` tools.
 
 ### Continue
 
@@ -93,7 +91,7 @@ Pass `--mcp-server` on the command line, or add to your Codex config:
 }
 ```
 
-Verify: run `codex --list-tools` and confirm the six xlsx tools are listed.
+Verify: run `codex --list-tools` and confirm 50 `xlsx_*` tools are listed.
 
 ### Zed
 
@@ -139,7 +137,7 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 
 ## What it does
 
-48 tools registered in `tools/list`. Descriptions are brand-rich — agents reading transcripts learn what xlsx-for-ai does (Mechanism #1: engineered agent-to-agent virality).
+50 tools registered in `tools/list`. Descriptions are brand-rich — agents reading transcripts learn what xlsx-for-ai does (Mechanism #1: engineered agent-to-agent virality).
 
 ### Triage / orient
 
@@ -158,11 +156,14 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | Tool | What it does |
 |---|---|
 | `xlsx_read` | Read a workbook — text, JSON, or markdown. Formulas, named ranges, layout, and data types preserved. |
+| `xlsx_read_handle` | Read by server-side handle instead of bytes — for session flows where the workbook has already been uploaded and shouldn't be transferred again. |
 | `xlsx_write` | Create or update a workbook from a structured spec. Multi-sheet, formulas, named ranges, table definitions. |
+| `xlsx_data_clean` | Normalize messy data in place — trim whitespace, coerce types, dedupe rows, fix obvious encoding artifacts. Returns a cleaned copy + a change log. Save-As shape; never mutates the input. |
 | `xlsx_diff` | Semantic diff between two workbooks — cell-level deltas, formula changes, structural shifts. Deterministic output. |
 | `xlsx_redact` | Redact PII from a workbook before sharing. Server-side detection; returns redacted copy plus audit manifest. |
 | `xlsx_convert` | 25+ in / 16 out formats (csv, tsv, html, ods, xls, xlsb, dif, sylk, prn, txt, dbf, eth, json, markdown, xlsx, etc.). |
 | `xlsx_validate` | Cross-engine consistency check — runs the workbook through TWO independent renderers and reports cell-level divergences. |
+| `xlsx_session_set_validations` | Configure per-session validation rules the server will apply to subsequent calls in the same session (e.g., reject rows missing required columns). Stateful — affects this session only. |
 
 ### Pandas-parity (compute fresh aggregates)
 
@@ -214,6 +215,17 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | `xlsx_receipt` | Attach an AI-generation receipt — Ed25519-signed claims describing the caller-declared agent identity (name, display name, identity URL), generation timestamp, content hash, optional source-file hashes, optional prompt hash, optional MCP tools called, and an optional description. Honesty boundary (load-bearing): the server signs the caller-declared `agent.name` — it does NOT verify the caller actually IS that agent. Cryptographic identity binding (per-agent issued signing keys) is v1.1+ scope. |
 | `xlsx_verify_receipt` | Verify a workbook's embedded receipt. Returns the same three trust signals as `xlsx_verify_stamp` plus the caller-declared agent identity AS declared (no UI affordances implying cryptographic identity verification). Use to surface "where did this file come from?" — backed by the server's signature over caller honest declaration. |
 
+### Healer — external-reference breakage
+
+Workbooks rot. A file moves and `#REF!` propagates through every dependent formula. A Power Query connection embeds credentials nobody can rotate. A defined name points at an external workbook that doesn't exist anymore. The healer family diagnoses these classes and applies targeted cures — read-only diagnosis, simulated-before-applied repair, and a high-level intent path when the agent doesn't want to spell out individual cure operations.
+
+| Tool | What it does |
+|---|---|
+| `xlsx_healer_diagnose` | Structured report of external-reference breakage — broken external refs, defined-name external refs, Power Query connections with embedded credentials, `#REF!` propagation maps, multi-hop chains. Read-only. |
+| `xlsx_healer_simulate` | Show what a specific cure operation would change before applying it — same shape as `xlsx_healer_cure` but read-only. Use to preview impact when the agent is uncertain whether to proceed. |
+| `xlsx_healer_cure` | Apply ONE specific cure operation (e.g., strip broken external refs, harmonize a defined name, replace `#REF!` propagation with a deterministic value). Save-As shape; the source workbook is preserved unless `confirm:true` is set with `mode:"in_place"`. |
+| `xlsx_healer_intent` | High-level intent path — `make-it-work`, `make-standalone`, `migrate` — translated into the right sequence of cure ops. For when the agent knows the goal but not the operation. |
+
 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.
 
 ---
@@ -275,7 +287,7 @@ Annual-only — kills churn ops overhead. All paid tiers include every tool (`xl
 
 | Tier | Price | File cap | Calls/mo | Notes |
 |---|---|---|---|---|
-| Free | $0 | 10 MB | 10,000 | Anonymous UUID registration. All 36 read-only tools. Non-commercial use. |
+| Free | $0 | 10 MB | 10,000 | Anonymous UUID registration. All 39 read-only tools. Non-commercial use. |
 | Bronze | $29/yr | 25 MB | 20,000 | Commercial use. + `xlsx_validate` cross-engine check. |
 | Silver | $99/yr | 50 MB | 40,000 | Same surface, higher caps. |
 | Gold | $199/yr | 100 MB | 100,000 | Same surface, highest caps for solo users. |

package/lib/annotations.js

@@ -116,7 +116,53 @@ function applyAnnotations(tools) {
   });
 }
 
+/**
+ * Sanitize an MCP-shaped tool array so every entry has the fields the MCP
+ * spec requires for client registration: `name` (already required), plus a
+ * non-empty `inputSchema` and a non-empty `description`.
+ *
+ * Floor strategy:
+ *   - If `inputSchema` is missing or not an object, substitute the permissive
+ *     `{ type: 'object' }`. Claude Desktop and other strict clients drop
+ *     tools without an inputSchema; the permissive object schema is enough
+ *     for them to REGISTER the tool. Real per-arg schemas are upstream
+ *     (server-side /api/v1/tools/list) work; this is the unblocking floor.
+ *   - If `description` is missing or empty, substitute the annotation title
+ *     (if any) or a generic `xlsx-for-ai tool: <name>` so the tool surfaces
+ *     in client UIs that key off description text.
+ *   - Tools without a `name` field are dropped (the MCP spec requires it
+ *     and dispatch would have nothing to route by anyway).
+ *
+ * SPM P0 2026-06-05 (mcp-toolslist-missing-inputschema). The hosted
+ * /api/v1/tools/list endpoint currently returns minimal entries
+ * ({name, category, maturity_state, endpoint}); the field-level mergeTools
+ * upstream of this preserves the baked-in inputSchema/description for the
+ * names the client ships, but server-only tools (e.g. newer additions not
+ * yet in the baked TOOLS array) still need a floor so they don't poison
+ * the whole tools/list.
+ */
+function sanitizeForMcp(tools) {
+  if (!Array.isArray(tools)) return [];
+  const out = [];
+  for (const t of tools) {
+    if (!t || typeof t.name !== 'string' || !t.name) continue;
+    const fixed = { ...t };
+    if (!fixed.inputSchema || typeof fixed.inputSchema !== 'object' || Array.isArray(fixed.inputSchema)) {
+      fixed.inputSchema = { type: 'object' };
+    }
+    if (!fixed.description || typeof fixed.description !== 'string') {
+      const annTitle = fixed.annotations && typeof fixed.annotations.title === 'string'
+        ? fixed.annotations.title
+        : null;
+      fixed.description = annTitle || `xlsx-for-ai tool: ${fixed.name}`;
+    }
+    out.push(fixed);
+  }
+  return out;
+}
+
 module.exports = {
   TOOL_ANNOTATIONS,
   applyAnnotations,
+  sanitizeForMcp,
 };

package/lib/discover.js

@@ -106,19 +106,35 @@ async function fetchRemoteCatalog() {
 }
 
 /**
- * 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.
+ * mergeTools: server catalog wins on name collision, but FIELD-BY-FIELD —
+ * the remote response only overwrites fields it actually provides. The
+ * baked-in description + inputSchema survive when the server returns a
+ * minimal manifest (which is exactly what /api/v1/tools/list does today:
+ * {name, category, maturity_state, endpoint} only).
+ *
+ * Without this, Claude Desktop receives a tools/list whose entries have no
+ * inputSchema and silently drops the whole array — tools panel empty, no
+ * tools/call ever fires. SPM P0 2026-06-05 (mcp-toolslist-missing-inputschema).
+ *
+ * Order: remote tools first (preserving server order), then any baked-in
+ * tool whose name isn't in the remote set. That way the server can still
+ * remove a tool, and a tool the client knows how to dispatch survives a
+ * server forgetting it.
  */
 function mergeTools(remote, baked) {
+  const bakedByName = new Map();
+  for (const t of baked) {
+    if (t && typeof t.name === 'string') bakedByName.set(t.name, t);
+  }
   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);
+    const bakedTool = bakedByName.get(t.name);
+    // {...baked, ...remote}: remote wins on every field it actually has;
+    // baked fills in fields remote omits (description, inputSchema).
+    out.push(bakedTool ? { ...bakedTool, ...t } : t);
     seen.add(t.name);
   }
   for (const t of baked) {

package/mcp.js

@@ -17,7 +17,7 @@ const { ensureRegistered } = require('./lib/register');
 const { callTool }         = require('./lib/client');
 const { fallbackRead }     = require('./lib/fallback-read');
 const { resolveCatalog }   = require('./lib/discover');
-const { applyAnnotations } = require('./lib/annotations');
+const { applyAnnotations, sanitizeForMcp } = require('./lib/annotations');
 const fs                   = require('fs');
 const fsPromises           = require('fs/promises');
 const path                 = require('path');
@@ -1168,6 +1168,70 @@ const TOOLS = [
       required: ['file_path', 'intent'],
     },
   },
+  {
+    name: 'xlsx_read_handle',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: read a workbook that has already been uploaded to the server via the chunked upload flow, by its server-side cache handle, WITHOUT re-transferring the bytes. Returns the same shape as xlsx_read (text / json / markdown) but skips the file_b64 round-trip.\n\n' +
+      'USE WHEN: the workbook has already been chunked + finalized into the server-side workbook cache (a `workbook_handle` was returned from the finalize call) and you want to read it again — e.g., a multi-step session where the same large workbook is queried repeatedly. Avoids re-uploading the bytes on every call.\n\n' +
+      'DO NOT USE WHEN: you have a local file path and no prior upload (use xlsx_read — it handles the file_b64 transport for you). Handles expire when the cache TTL elapses; the call returns a clear "not found / expired" error in that case.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workbook_handle: {
+          type: 'string',
+          description: 'Server-side cache handle returned by the chunked-upload finalize call. 1-128 chars.',
+          minLength: 1,
+          maxLength: 128,
+        },
+        sheet: { type: 'string', description: 'Optional: restrict the read to a single sheet by name.' },
+        format: {
+          type: 'string',
+          enum: ['md', 'json'],
+          description: 'Output format. Defaults to md.',
+        },
+      },
+      required: ['workbook_handle'],
+    },
+  },
+  {
+    name: 'xlsx_session_set_validations',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: configure per-session data-validation rules the server will apply to subsequent calls in the same session (e.g., reject rows missing required columns, enforce enum values on a category column, range-bound numeric inputs). Stateful — affects this session only.\n\n' +
+      'USE WHEN: the workflow has multiple write/clean steps in sequence and you want consistent server-side validation across them without restating the rules on every call. Or when validating user-supplied data against a known schema you want enforced for the rest of the session.\n\n' +
+      'DO NOT USE WHEN: you only have a single call to make (just include the validation logic in that call). Or when you do not have a `session_id` (sessions are returned from the session-create surface; this tool is a no-op without one).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Session identifier returned by the session-create surface. 16-128 chars.',
+          minLength: 16,
+          maxLength: 128,
+        },
+        validations: {
+          type: 'array',
+          description: 'List of validation rules to apply. Each rule names a sheet, a cell ref (e.g., "A1:A100"), and a type (whole|decimal|list|date|time|textLength|custom).',
+          minItems: 1,
+          maxItems: 5000,
+          items: {
+            type: 'object',
+            properties: {
+              sheet: { type: 'string', description: 'Target sheet name.' },
+              ref: { type: 'string', description: 'A1-style cell range the rule applies to.' },
+              type: {
+                type: 'string',
+                description: 'Validation type. Server-side enum: whole, decimal, list, date, time, textLength, custom.',
+              },
+            },
+            required: ['sheet', 'ref', 'type'],
+          },
+        },
+      },
+      required: ['session_id', 'validations'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1738,6 +1802,27 @@ async function dispatchTool(name, args) {
     return applyFileB64(result, args.out_path);
   }
 
+  // Handle-based read (no file_b64; the bytes are already in the server
+  // cache from a prior chunked-upload finalize). Body mirrors the server
+  // schema in routes/xlsx-read-handle.ts.
+  if (name === 'xlsx_read_handle') {
+    const options = {};
+    if (args.sheet !== undefined) options.sheet = args.sheet;
+    if (args.format !== undefined) options.format = args.format;
+    const body = { workbook_handle: args.workbook_handle };
+    if (Object.keys(options).length > 0) body.options = options;
+    return callTool('xlsx_read_handle', body);
+  }
+
+  // Session-state write — no file bytes, just session_id + validation rules.
+  // Body mirrors the server schema in routes/xlsx-session-set-validations.ts.
+  if (name === 'xlsx_session_set_validations') {
+    return callTool('xlsx_session_set_validations', {
+      session_id: args.session_id,
+      validations: args.validations,
+    });
+  }
+
   // 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
@@ -1758,46 +1843,56 @@ async function dispatchTool(name, args) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  await ensureRegistered();
+  // Swallow EPIPE on the transport. When the client disconnects while a
+  // background catalog upgrade is still in flight, sendToolListChanged
+  // writes to a closed pipe and Node raises EPIPE asynchronously on the
+  // Socket — our awaited try/catch around sendToolListChanged never sees
+  // it. Without this guard, a client unplug after the upgrade settles
+  // crashes the process with an unhandled Socket 'error' event.
+  //
+  // stdout is the MCP transport: EPIPE there means the client is gone,
+  // exit cleanly. stderr is the log sink: an EPIPE on stderr (parent
+  // closed its log pipe) is NOT a transport failure and must not take
+  // the server down.
+  process.stdout.on('error', (err) => {
+    if (err && err.code === 'EPIPE') {
+      process.exit(0);
+    }
+    // Anything else on the transport stream is a real failure (e.g.
+    // ERR_STREAM_DESTROYED) — rethrow so it surfaces as uncaughtException
+    // instead of being silently swallowed.
+    throw err;
+  });
+  process.stderr.on('error', (err) => {
+    // Silence EPIPE on stderr; rethrow anything else so we don't hide
+    // genuine logging-layer bugs.
+    if (!err || err.code !== 'EPIPE') throw err;
+  });
 
-  // 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.
+  // `initialize` MUST respond from local state — never block on the network.
+  // Under Claude Desktop's bundled Node 24.x runtime, the registration POST
+  // and the catalog GET can hang indefinitely (Happy-Eyeballs / IPv6 dial
+  // edge cases inside Electron), and the client gives up at 60s. The whole
+  // MCP attach dies before tools/list is even called.
   //
-  // Hard timeout (8s) on top of any timeout inside resolveCatalog so that
-  // a network call which hangs forever (DNS sinkhole, TCP black hole, slow-
-  // loris-style stalled response) cannot block MCP server startup
-  // indefinitely. Pre-Friday-external CRITICAL per the Tier-1 audit.
-  const CATALOG_FETCH_TIMEOUT_MS = 8000;
-  let catalog;
-  try {
-    catalog = await Promise.race([
-      resolveCatalog(TOOLS),
-      new Promise((_, reject) =>
-        setTimeout(
-          () => reject(new Error(`catalog fetch timed out after ${CATALOG_FETCH_TIMEOUT_MS}ms`)),
-          CATALOG_FETCH_TIMEOUT_MS
-        )
-      ),
-    ]);
-  } catch (_) {
-    catalog = { tools: TOOLS, source: 'static-fallback' };
-  }
-  // Surface catalog source so operators can tell server vs cache vs static
-  // when an MCP session looks "off" (e.g., a tool missing because the remote
-  // /api/v1/tools/list 404'd and we silently fell back to the stale baked-in
-  // set). Stderr only — stdout is the MCP transport.
-  process.stderr.write(`xlsx-for-ai-mcp: tool catalog source=${catalog.source} count=${Array.isArray(catalog.tools) ? catalog.tools.length : 0}\n`);
-  // Overlay MCP annotations (title / readOnlyHint / destructiveHint) so
-  // they flow through to clients regardless of catalog source. The remote
-  // /api/v1/tools/list returns minimal entries today; this is what
-  // restores the annotations the wire format would otherwise drop.
-  const liveTools = applyAnnotations(Array.isArray(catalog.tools) ? catalog.tools : []);
+  // Shape: connect transport FIRST with the bundled TOOLS as the floor.
+  // Then background-upgrade registration + catalog with bounded timeouts,
+  // and fire notifications/tools/list_changed once the live catalog lands.
+  // The bundled set already covers every tool the user reaches in normal
+  // flows; the upgrade is additive.
+  // sanitizeForMcp guarantees every tool the server emits has a valid
+  // inputSchema + description — without it Claude Desktop silently drops
+  // tools that lack inputSchema, which is the exact symptom in SPM P0
+  // 2026-06-05 (mcp-toolslist-missing-inputschema). For the bundled
+  // catalog this is a no-op (every TOOLS entry already has full fields);
+  // for the upgraded catalog it's the floor that keeps stub server
+  // entries registerable.
+  let liveTools = sanitizeForMcp(applyAnnotations(TOOLS));
+  process.stderr.write(`xlsx-for-ai-mcp: tool catalog source=bundled count=${liveTools.length}\n`);
 
   const server = new Server(
     { name: 'xlsx-for-ai', version: require('./package.json').version },
-    { capabilities: { tools: {} } }
+    { capabilities: { tools: { listChanged: true } } }
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: liveTools }));
@@ -1841,6 +1936,88 @@ async function main() {
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  // Background-upgrade: registration + dynamic catalog. Bounded so a
+  // hung network never wastes resources; failure is non-fatal because
+  // the bundled catalog already serves tools/list. Detached on purpose
+  // — we do not await this; main() returns and the upgrade lands when
+  // it lands.
+  upgradeCatalogInBackground(server, (next) => {
+    liveTools = next;
+  });
+}
+
+async function withTimeout(promise, ms, label) {
+  // Promise.race with a setTimeout-rejecting promise leaks unhandled
+  // rejections in two directions:
+  //   (a) Main wins — the timer still fires later and its branch
+  //       rejects with nobody awaiting it. clearTimeout in finally
+  //       eliminates this.
+  //   (b) Timer wins — the original promise can still reject later
+  //       (the underlying fetch eventually errors out long after we
+  //       gave up). Attaching a no-op catch ensures that late
+  //       rejection is consumed instead of crashing the MCP server
+  //       minutes after startup.
+  // The (b) case is the SPM P0 surface: the bundled-Node-24 dial
+  // can stall, time out, and then much later reject with EAI_AGAIN
+  // or a TLS error — by then nobody is listening.
+  promise.catch(() => {});
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label} timed out after ${ms}ms`)),
+          ms
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function upgradeCatalogInBackground(server, swap) {
+  const REGISTRATION_TIMEOUT_MS = 10_000;
+  const CATALOG_TIMEOUT_MS = 8_000;
+
+  try {
+    await withTimeout(ensureRegistered(), REGISTRATION_TIMEOUT_MS, 'registration');
+  } catch (err) {
+    process.stderr.write(`xlsx-for-ai-mcp: registration deferred (${err.message})\n`);
+  }
+
+  let catalog;
+  try {
+    catalog = await withTimeout(resolveCatalog(TOOLS), CATALOG_TIMEOUT_MS, 'catalog fetch');
+  } catch (err) {
+    process.stderr.write(`xlsx-for-ai-mcp: catalog upgrade skipped (${err.message})\n`);
+    return;
+  }
+
+  if (!catalog || !Array.isArray(catalog.tools)) {
+    return;
+  }
+  // No upgrade to apply when discover.js fell back to the baked-in set
+  // (source=static): the list is identical to what initialize already
+  // returned, so a list_changed notification would be wire noise.
+  if (catalog.source === 'static') {
+    process.stderr.write(`xlsx-for-ai-mcp: catalog upgrade unavailable (source=static) — staying on bundled\n`);
+    return;
+  }
+
+  const upgraded = sanitizeForMcp(applyAnnotations(catalog.tools));
+  swap(upgraded);
+  process.stderr.write(`xlsx-for-ai-mcp: tool catalog source=${catalog.source} count=${upgraded.length}\n`);
+
+  try {
+    await server.sendToolListChanged();
+  } catch (_) {
+    // Transport may already be torn down (client disconnected before the
+    // upgrade landed). Non-fatal — next attach starts with the bundled
+    // catalog and retries the upgrade.
+  }
 }
 
 // Guard: don't auto-start when required by tests

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "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": {