xlsx-for-ai 2.26.1 → 3.0.2

package/README.md

@@ -2,12 +2,14 @@
 
 **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 six production-grade tools for reading, writing, diffing, and redacting `.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
 ```
 
+**Or — recommended for MCP use:** the canonical configs below use `npx -y xlsx-for-ai@latest`, which fetches and runs the latest version on every client restart. Self-heals across releases without a manual global re-install when a new version ships.
+
 > **Upgrading from 1.5.x?** This is a re-architecture, not a feature bump: the heavy local engine is gone from the npm package. All rendering happens server-side. The `cursor-reads-xlsx` alias still works. See [Migration](#migration-from-15x) below.
 
 ---
@@ -20,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.
 
@@ -30,13 +32,14 @@ The bundle includes the full npm package and registers all MCP tools automatical
 {
   "mcpServers": {
     "xlsx-for-ai": {
-      "command": "xlsx-for-ai-mcp"
+      "command": "npx",
+      "args": ["-y", "-p", "xlsx-for-ai@latest", "xlsx-for-ai-mcp"]
     }
   }
 }
 ```
 
-Verify either path: restart Claude Desktop, open a new conversation, and ask "what MCP tools do you have?" — 37 `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
 
@@ -46,13 +49,14 @@ Config file: `~/.cursor/mcp.json`
 {
   "mcpServers": {
     "xlsx-for-ai": {
-      "command": "xlsx-for-ai-mcp"
+      "command": "npx",
+      "args": ["-y", "-p", "xlsx-for-ai@latest", "xlsx-for-ai-mcp"]
     }
   }
 }
 ```
 
-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
 
@@ -63,7 +67,8 @@ Config file: `~/.continue/config.json`
   "mcpServers": [
     {
       "name": "xlsx-for-ai",
-      "command": "xlsx-for-ai-mcp"
+      "command": "npx",
+      "args": ["-y", "-p", "xlsx-for-ai@latest", "xlsx-for-ai-mcp"]
     }
   ]
 }
@@ -79,13 +84,14 @@ Pass `--mcp-server` on the command line, or add to your Codex config:
 {
   "mcpServers": {
     "xlsx-for-ai": {
-      "command": "xlsx-for-ai-mcp"
+      "command": "npx",
+      "args": ["-y", "-p", "xlsx-for-ai@latest", "xlsx-for-ai-mcp"]
     }
   }
 }
 ```
 
-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
 
@@ -96,8 +102,8 @@ Config file: `~/.config/zed/settings.json`
   "context_servers": {
     "xlsx-for-ai": {
       "command": {
-        "path": "xlsx-for-ai-mcp",
-        "args": []
+        "path": "npx",
+        "args": ["-y", "-p", "xlsx-for-ai@latest", "xlsx-for-ai-mcp"]
       }
     }
   }
@@ -114,7 +120,8 @@ Config file: `~/.codeium/windsurf/mcp_config.json`
 {
   "mcpServers": {
     "xlsx-for-ai": {
-      "command": "xlsx-for-ai-mcp"
+      "command": "npx",
+      "args": ["-y", "-p", "xlsx-for-ai@latest", "xlsx-for-ai-mcp"]
     }
   }
 }
@@ -130,7 +137,7 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 
 ## What it does
 
-44 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
 
@@ -149,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)
 
@@ -205,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.
 
 ---
@@ -266,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/index.js

@@ -218,21 +218,30 @@ function loadChecksFile(checksPath) {
 // ---------------------------------------------------------------------------
 // Heal subcommand — exposes the healer-deep HTTP routes from the CLI.
 //
-//   xlsx-for-ai heal <path>                    diagnose-only (default)
-//   xlsx-for-ai heal <path> --diagnose-only    explicit form of the default
-//   xlsx-for-ai heal <path> --operation <op> --params <json> [--mode <m>] [--out <path>]
-//   xlsx-for-ai heal <path> --format text|json [other flags]
+//   xlsx-for-ai heal <path>                                          diagnose-only (default)
+//   xlsx-for-ai heal <path> --diagnose-only                          explicit form of the default
+//   xlsx-for-ai heal <path> --operation <op> --params <json>         apply one cure operation
+//   xlsx-for-ai heal <path> --intent <make-it-work|make-standalone|migrate>
+//                           [--from <prefix>] [--to <prefix>]        intent-driven cure (plan + apply)
+//                           [--confirm]                              required for --mode in_place
+//   xlsx-for-ai heal <path> [--mode as_copy|in_place] [--out <path>] [--format text|json]
 //
-// `--intent`/`--from`/`--to` are reserved for v1.1 once the
-// /api/v1/tools/xlsx_healer_intent route ships; the CLI rejects
-// those flags today so callers see a clean "v1.1" message rather
-// than a server 404.
+// The intent path requires the /api/v1/tools/xlsx_healer_intent route
+// to be live; it's been deployed since 2026-06-04. `--from` and `--to`
+// are required when intent=migrate (the route also enforces this); for
+// other intents they're ignored.
 // ---------------------------------------------------------------------------
 
+const VALID_INTENTS = new Set(['make-it-work', 'make-standalone', 'migrate']);
+
 async function runHealSubcommand(rest) {
   if (rest.length === 0 || rest[0].startsWith('-')) {
     process.stderr.write(
-      'Usage: xlsx-for-ai heal <file.xlsx> [--diagnose-only | --operation <op> --params <json>] [--mode as_copy|in_place] [--out <path>] [--format text|json]\n',
+      'Usage: xlsx-for-ai heal <file.xlsx>\n' +
+        '         [--diagnose-only]\n' +
+        '         [--operation <op> --params <json>]\n' +
+        '         [--intent <make-it-work|make-standalone|migrate> [--from <prefix>] [--to <prefix>] [--confirm]]\n' +
+        '         [--mode as_copy|in_place] [--out <path>] [--format text|json]\n',
     );
     process.exit(2);
   }
@@ -246,6 +255,10 @@ async function runHealSubcommand(rest) {
   let diagnoseOnly = false;
   let operation = null;
   let paramsJson = null;
+  let intent = null;
+  let intentFrom = null;
+  let intentTo = null;
+  let confirm = false;
   let mode = 'as_copy';
   let outPath = null;
   let format = 'text';
@@ -254,13 +267,14 @@ async function runHealSubcommand(rest) {
     if      (a === '--diagnose-only')   diagnoseOnly = true;
     else if (a === '--operation')       operation = nextRequiredArg(rest, i++, '--operation');
     else if (a === '--params')          paramsJson = nextRequiredArg(rest, i++, '--params');
+    else if (a === '--intent')          intent     = nextRequiredArg(rest, i++, '--intent');
+    else if (a === '--from')            intentFrom = nextRequiredArg(rest, i++, '--from');
+    else if (a === '--to')              intentTo   = nextRequiredArg(rest, i++, '--to');
+    else if (a === '--confirm')         confirm    = true;
     else if (a === '--mode')            mode       = nextRequiredArg(rest, i++, '--mode');
     else if (a === '--out')             outPath    = nextRequiredArg(rest, i++, '--out');
     else if (a === '--format')          format     = nextRequiredArg(rest, i++, '--format');
-    else if (a === '--intent' || a === '--from' || a === '--to') {
-      process.stderr.write(`xlsx-for-ai heal: ${a} is reserved for v1.1 (intent-driven cures via /xlsx_healer_intent); not yet wired\n`);
-      process.exit(2);
-    } else {
+    else {
       process.stderr.write(`Unknown flag: ${a}\n`);
       process.exit(2);
     }
@@ -268,19 +282,43 @@ async function runHealSubcommand(rest) {
 
   // Validate mutually-exclusive shapes early — clearer than letting
   // the server emit `conflicting_repair_directives` on its O8 check.
-  if (diagnoseOnly && operation) {
-    process.stderr.write('xlsx-for-ai heal: --diagnose-only and --operation are mutually exclusive\n');
+  const modeCount = (diagnoseOnly ? 1 : 0) + (operation ? 1 : 0) + (intent ? 1 : 0);
+  if (modeCount > 1) {
+    process.stderr.write(
+      'xlsx-for-ai heal: --diagnose-only, --operation, and --intent are mutually exclusive — pick one.\n',
+    );
     process.exit(2);
   }
-  if (!diagnoseOnly && !operation) {
+  if (modeCount === 0) {
     // Default to diagnose-only — first-touch use of `xlsx-for-ai heal`
     // should show the user what's wrong before they pick a cure.
     diagnoseOnly = true;
   }
+  if (intent !== null && !VALID_INTENTS.has(intent)) {
+    process.stderr.write(
+      `xlsx-for-ai heal: --intent must be one of: ${[...VALID_INTENTS].join(', ')} (got '${intent}')\n`,
+    );
+    process.exit(2);
+  }
+  if (intent === 'migrate' && (!intentFrom || !intentTo)) {
+    process.stderr.write(
+      'xlsx-for-ai heal: --intent migrate requires both --from <prefix> and --to <prefix>\n',
+    );
+    process.exit(2);
+  }
   if (mode !== 'as_copy' && mode !== 'in_place') {
     process.stderr.write(`xlsx-for-ai heal: --mode must be 'as_copy' or 'in_place' (got '${mode}')\n`);
     process.exit(2);
   }
+  if (mode === 'in_place' && !confirm && (operation || intent)) {
+    // Server-side intent route enforces confirm for in_place — surface
+    // the same gate client-side so the CLI's error message matches the
+    // intent of the safety check (don't overwrite without confirmation).
+    process.stderr.write(
+      'xlsx-for-ai heal: --mode in_place requires --confirm (explicit overwrite gate)\n',
+    );
+    process.exit(2);
+  }
   if (format !== 'text' && format !== 'json') {
     process.stderr.write(`xlsx-for-ai heal: --format must be 'text' or 'json' (got '${format}')\n`);
     process.exit(2);
@@ -316,31 +354,52 @@ async function runHealSubcommand(rest) {
     return 0;
   }
 
-  // ---- cure path ---------------------------------------------------------
-  let cureParams = {};
-  if (paramsJson !== null) {
+  // ---- cure or intent path -----------------------------------------------
+  let result;
+  let healLabel; // for the friendly error prefix
+  if (intent) {
+    // Intent path — server plans + applies. intent_params carries the
+    // optional from/to prefix pair for the migrate intent.
+    const intentParams = {};
+    if (intentFrom) intentParams.from = intentFrom;
+    if (intentTo)   intentParams.to   = intentTo;
+    const body = { file_b64: fileB64, intent, mode };
+    if (Object.keys(intentParams).length > 0) body.intent_params = intentParams;
+    if (mode === 'in_place') body.confirm = true;
+    healLabel = `--intent ${intent}`;
     try {
-      cureParams = JSON.parse(paramsJson);
-    } catch (e) {
-      process.stderr.write(`xlsx-for-ai heal: --params is not valid JSON: ${e.message}\n`);
-      process.exit(2);
+      result = await callTool('xlsx_healer_intent', body);
+    } catch (err) {
+      process.stderr.write(friendlyCliError(`xlsx-for-ai heal ${healLabel}`, err) + '\n');
+      process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
     }
-    if (cureParams === null || typeof cureParams !== 'object' || Array.isArray(cureParams)) {
-      process.stderr.write('xlsx-for-ai heal: --params must be a JSON object\n');
-      process.exit(2);
+  } else {
+    let cureParams = {};
+    if (paramsJson !== null) {
+      try {
+        cureParams = JSON.parse(paramsJson);
+      } catch (e) {
+        process.stderr.write(`xlsx-for-ai heal: --params is not valid JSON: ${e.message}\n`);
+        process.exit(2);
+      }
+      if (cureParams === null || typeof cureParams !== 'object' || Array.isArray(cureParams)) {
+        process.stderr.write('xlsx-for-ai heal: --params must be a JSON object\n');
+        process.exit(2);
+      }
     }
-  }
 
-  const body = { file_b64: fileB64, operation, cure_params: cureParams, mode };
-  let result;
-  try {
-    result = await callTool('xlsx_healer_cure', body);
-  } catch (err) {
-    // Same sanitization shape as the diagnose path — friendlyCliError
-    // (above) maps known codes to canned messages; raw err.message
-    // only surfaces with XFA_DEBUG=1 for incident triage.
-    process.stderr.write(friendlyCliError(`xlsx-for-ai heal --operation ${operation}`, err) + '\n');
-    process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
+    const body = { file_b64: fileB64, operation, cure_params: cureParams, mode };
+    if (mode === 'in_place') body.confirm = true;
+    healLabel = `--operation ${operation}`;
+    try {
+      result = await callTool('xlsx_healer_cure', body);
+    } catch (err) {
+      // Same sanitization shape as the diagnose path — friendlyCliError
+      // (above) maps known codes to canned messages; raw err.message
+      // only surfaces with XFA_DEBUG=1 for incident triage.
+      process.stderr.write(friendlyCliError(`xlsx-for-ai heal ${healLabel}`, err) + '\n');
+      process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
+    }
   }
 
   const meta = (result && result._meta) || {};

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');
@@ -1045,6 +1045,193 @@ const TOOLS = [
       required: ['file_path'],
     },
   },
+
+  {
+    name: 'xlsx_healer_diagnose',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: produce a structured diagnostic report of external references that are broken or at risk in a workbook. Returns five classes of finding: (1) external-workbook references that can\'t resolve, (2) defined-name external refs, (3) Power Query connections with embedded credentials, (4) #REF! propagation maps from upstream breakage, (5) multi-hop chains (workbook → workbook → workbook). Findings carry reference_id keys that downstream cure operations key on.\n\n' +
+      'USE WHEN: a workbook shows #REF! errors, an agent moves a file and refs need rewriting, a customer reports "the workbook stopped working after we reorganized SharePoint", or auditing a corpus for hidden external-link breakage before sharing.\n\n' +
+      'DO NOT USE WHEN: the user wants the cleaning/normalization surface (use xlsx_data_clean — different concern). Or when there is no .xlsx source path (Healer reads the source bytes, doesn\'t reconstruct from a structured spec).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to diagnose.' },
+      },
+      required: ['file_path'],
+    },
+  },
+
+  {
+    name: 'xlsx_healer_cure',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: apply ONE specific cure operation against a diagnosed workbook. Each operation targets a specific failure mode: rename_move (rewrite ref paths), pattern_bulk (regex-style ref rewrites), source_deleted_freeze (replace broken refs with cached values), source_deleted_redirect (point at a replacement file), source_deleted_localize (snapshot full external source into a local copy), permission_denied (strip credentials), structure_changed (rewrite formulas for moved cells), format_change (re-link after extension change), make_standalone (fully dereference all externals). Returns the cured workbook bytes + a receipt naming exactly what changed.\n\n' +
+      'USE WHEN: a diagnostic report (xlsx_healer_diagnose) named a specific operation as the recommended fix and the user confirmed it; or running a known recipe across a folder of files; or restoring a workbook whose source moved by a known prefix.\n\n' +
+      'DO NOT USE WHEN: the failure mode isn\'t one of the supported operations (use xlsx_healer_intent for goal-shaped fixes). Or when diagnose hasn\'t been run yet on the file (cures need diagnose-emitted reference_ids).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to cure.' },
+        operation: {
+          type: 'string',
+          description: 'The cure operation to apply.',
+          enum: [
+            'rename_move',
+            'pattern_bulk',
+            'source_deleted_freeze',
+            'source_deleted_redirect',
+            'source_deleted_localize',
+            'permission_denied',
+            'structure_changed',
+            'format_change',
+            'make_standalone',
+            'chain_collapse',
+            'modernize_to_pq',
+          ],
+        },
+        cure_params: {
+          type: 'object',
+          description: 'Operation-specific parameters. E.g., rename_move takes {from_prefix, to_prefix}; pattern_bulk takes {pattern, replacement}.',
+        },
+        mode: {
+          type: 'string',
+          enum: ['as_copy', 'in_place'],
+          description: 'as_copy (default) writes a new file alongside the source; in_place overwrites it.',
+        },
+        confirm: {
+          type: 'boolean',
+          description: 'Required as true when mode=in_place. Prevents accidental in-place overwrites; explicit confirmation is the safety gate.',
+        },
+        out_path: { type: 'string', description: 'Optional: write the cured workbook to this absolute path. Defaults to <name>-healed.xlsx next to the source when mode=as_copy.' },
+      },
+      required: ['file_path', 'operation'],
+    },
+  },
+
+  {
+    name: 'xlsx_healer_simulate',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: simulate recipient-side accessibility of a workbook\'s external references. Given a list of paths the recipient CAN see (`accessible_paths`), returns which references will still resolve at the recipient end and which will break (and why). Read-only; produces no output workbook.\n\n' +
+      'USE WHEN: an agent or user wants to know "will this workbook work when I send it to <person>?" before sharing — e.g., before posting to Slack, attaching to email, or sharing a OneDrive link. Or auditing a workbook against a known recipient-accessible-paths inventory.\n\n' +
+      'DO NOT USE WHEN: the user wants to FIX the breakage (use xlsx_healer_cure or xlsx_healer_intent). Or when the recipient is the sender themselves (no path discrepancy to simulate).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to simulate.' },
+        accessible_paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of paths (absolute or URL) the recipient CAN see. Max 1000 entries, each ≤4096 chars. Often a folder tree or a SharePoint root.',
+        },
+      },
+      required: ['file_path', 'accessible_paths'],
+    },
+  },
+
+  {
+    name: 'xlsx_healer_intent',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: goal-driven healing. Caller declares an INTENT (`make-it-work`, `make-standalone`, or `migrate`) instead of a specific cure operation; Healer plans the operation sequence + applies it. make-it-work: minimum surgery to clear errors. make-standalone: fully de-externalize the workbook (snapshot every external dep). migrate: rewrite all references against a from/to prefix pair. Returns the planned operations, the cured bytes, and an unactionable list for refs that couldn\'t be auto-resolved.\n\n' +
+      'USE WHEN: the user describes the goal in plain English ("just make this work for the recipient" / "send a fully self-contained version" / "we moved the share root, update the refs"). Or when multiple cure operations need to compose and the orchestration is non-trivial.\n\n' +
+      'DO NOT USE WHEN: the user has already chosen a specific cure operation (use xlsx_healer_cure directly — avoids the planning overhead). Or when no diagnostic has been run on the workbook yet (intent uses the diagnostic surface internally; running diagnose first surfaces what intent will work with).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to heal.' },
+        intent: {
+          type: 'string',
+          enum: ['make-it-work', 'make-standalone', 'migrate'],
+          description: 'The healing goal. make-it-work: smallest surgery to clear errors. make-standalone: fully dereference all externals. migrate: rewrite against a from/to prefix pair (requires intent_params.from + intent_params.to).',
+        },
+        intent_params: {
+          type: 'object',
+          properties: {
+            from: { type: 'string', description: 'Source path prefix (required for migrate intent).' },
+            to: { type: 'string', description: 'Target path prefix (required for migrate intent).' },
+          },
+          description: 'Intent-specific parameters. Required keys depend on the intent (migrate needs from + to).',
+        },
+        mode: {
+          type: 'string',
+          enum: ['as_copy', 'in_place'],
+          description: 'as_copy (default) writes a new file alongside the source; in_place overwrites it.',
+        },
+        confirm: {
+          type: 'boolean',
+          description: 'Required as true when mode=in_place. Prevents accidental in-place overwrites; explicit confirmation is the safety gate.',
+        },
+        out_path: { type: 'string', description: 'Optional: write the cured workbook to this absolute path. Defaults to <name>-healed.xlsx next to the source when mode=as_copy.' },
+      },
+      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'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1567,6 +1754,75 @@ async function dispatchTool(name, args) {
     return callTool('xlsx_verify_receipt', body);
   }
 
+  // xlsx_healer_diagnose: produce structured diagnostic report of broken/
+  // at-risk external refs. Read-only; returns the report in the response
+  // _meta block. No output file.
+  if (name === 'xlsx_healer_diagnose') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    return callTool('xlsx_healer_diagnose', body);
+  }
+
+  // xlsx_healer_cure: apply ONE specific cure operation. Returns the
+  // cured bytes in _meta.file_b64 + a per-operation receipt; out_path
+  // (or in_place mode) triggers the standard applyFileB64 disk write.
+  if (name === 'xlsx_healer_cure') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      operation: args.operation,
+    };
+    if (args.cure_params !== undefined) body.cure_params = args.cure_params;
+    if (args.mode !== undefined) body.mode = args.mode;
+    if (args.confirm !== undefined) body.confirm = args.confirm;
+    const result = await callTool('xlsx_healer_cure', body);
+    return applyFileB64(result, args.out_path);
+  }
+
+  // xlsx_healer_simulate: recipient-side accessibility check. Read-only;
+  // returns the simulation report in _meta. No output file.
+  if (name === 'xlsx_healer_simulate') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      accessible_paths: args.accessible_paths,
+    };
+    return callTool('xlsx_healer_simulate', body);
+  }
+
+  // xlsx_healer_intent: goal-driven healing (plan + apply). Returns the
+  // planned operations + cured bytes + unactionable list. Same out_path /
+  // in_place semantics as xlsx_healer_cure.
+  if (name === 'xlsx_healer_intent') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      intent: args.intent,
+    };
+    if (args.intent_params !== undefined) body.intent_params = args.intent_params;
+    if (args.mode !== undefined) body.mode = args.mode;
+    if (args.confirm !== undefined) body.confirm = args.confirm;
+    const result = await callTool('xlsx_healer_intent', body);
+    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
@@ -1587,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 }));
@@ -1670,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": "2.26.1",
+  "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": {