xlsx-for-ai 2.26.0 → 3.0.0

package/README.md

@@ -1,13 +1,17 @@
 # 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 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 48 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.
 
 ---
@@ -30,13 +34,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?" — 48 `xlsx_*` tools should appear, including `xlsx_doctor` (one-call health report — try it first on any unknown workbook).
 
 ### Cursor
 
@@ -46,7 +51,8 @@ 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"]
     }
   }
 }
@@ -63,7 +69,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,7 +86,8 @@ 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"]
     }
   }
 }
@@ -96,8 +104,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 +122,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 +139,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).
+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).
 
 ### Triage / orient
 

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

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * MCP tool annotations — canonical source.
+ *
+ * Per MCP spec (2025-06-18+) tool annotations describe runtime behavior:
+ *   - title           Human-readable tool name
+ *   - readOnlyHint    Tool does NOT modify its environment
+ *   - destructiveHint Tool may perform irreversible side-effects
+ *
+ * The annotations live here rather than inline on each tool definition so:
+ *   1. They overlay onto tools regardless of source — static fallback,
+ *      cached catalog, or freshly-fetched remote. The remote /api/v1/tools/list
+ *      currently returns minimal entries; this overlay restores the
+ *      annotations the wire format would otherwise drop.
+ *   2. They drive manifest generation downstream (MCPB, M365 declarative
+ *      agent, future OpenAPI). One annotation change → all manifests
+ *      regenerate consistently.
+ *
+ * Classification rules:
+ *   - readOnlyHint: true  → tool only reads; never writes a file or causes
+ *                            an externally observable side-effect.
+ *   - destructiveHint: true → tool causes an irreversible external action
+ *                              (e.g., posts to a third-party system).
+ *     Note: tools that write a NEW file (Save-As shape) are NOT destructive
+ *     even though readOnlyHint is false — the source workbook is preserved.
+ *     destructiveHint is reserved for actions that cannot be undone by
+ *     deleting the output, which means external side-effects.
+ */
+
+const TOOL_ANNOTATIONS = Object.freeze({
+  // ---- Reading / inspection: 35 read-only tools -------------------------
+  xlsx_read:                { title: 'Read Excel file',                       readOnlyHint: true,  destructiveHint: false },
+  xlsx_list_sheets:         { title: 'List Excel sheets',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_schema:              { title: 'Infer Excel column types',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_diff:                { title: 'Diff two Excel workbooks',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_describe:            { title: 'Summarize Excel columns',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_filter:              { title: 'Filter Excel rows',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_aggregate:           { title: 'Group-by aggregate Excel rows',         readOnlyHint: true,  destructiveHint: false },
+  xlsx_named_ranges:        { title: 'List Excel named ranges',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_sort:                { title: 'Sort Excel rows',                       readOnlyHint: true,  destructiveHint: false },
+  xlsx_value_counts:        { title: 'Count Excel column values',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_formulas:            { title: 'Inspect Excel formulas',                readOnlyHint: true,  destructiveHint: false },
+  xlsx_tables:              { title: 'List Excel tables',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_pivot:               { title: 'Pivot Excel data',                      readOnlyHint: true,  destructiveHint: false },
+  xlsx_eval:                { title: 'Evaluate Excel formula',                readOnlyHint: true,  destructiveHint: false },
+  xlsx_validate:            { title: 'Cross-engine validate Excel',           readOnlyHint: true,  destructiveHint: false },
+  xlsx_data_validations:    { title: 'List Excel data-validation rules',      readOnlyHint: true,  destructiveHint: false },
+  xlsx_hyperlinks:          { title: 'List Excel hyperlinks',                 readOnlyHint: true,  destructiveHint: false },
+  xlsx_topology:            { title: 'Map Excel sheet topology',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_conditional_formats: { title: 'List Excel conditional formats',        readOnlyHint: true,  destructiveHint: false },
+  xlsx_comments:            { title: 'List Excel comments',                   readOnlyHint: true,  destructiveHint: false },
+  xlsx_doctor:              { title: 'Audit Excel workbook health',           readOnlyHint: true,  destructiveHint: false },
+  xlsx_form_controls:       { title: 'List Excel form controls',              readOnlyHint: true,  destructiveHint: false },
+  xlsx_macros:              { title: 'List Excel VBA macros',                 readOnlyHint: true,  destructiveHint: false },
+  xlsx_merged_cells:        { title: 'List Excel merged cells',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_workbook_views:      { title: 'List Excel workbook views',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_print_settings:      { title: 'List Excel print settings',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_properties:          { title: 'Read Excel document properties',        readOnlyHint: true,  destructiveHint: false },
+  xlsx_external_links:      { title: 'List Excel external links',             readOnlyHint: true,  destructiveHint: false },
+  xlsx_slicers_timelines:   { title: 'List Excel slicers and timelines',      readOnlyHint: true,  destructiveHint: false },
+  xlsx_pivot_tables:        { title: 'List Excel pivot tables',               readOnlyHint: true,  destructiveHint: false },
+  xlsx_images:              { title: 'List Excel embedded images',            readOnlyHint: true,  destructiveHint: false },
+  xlsx_charts:              { title: 'List Excel charts',                     readOnlyHint: true,  destructiveHint: false },
+  xlsx_protection:          { title: 'List Excel protection settings',        readOnlyHint: true,  destructiveHint: false },
+  xlsx_styles:              { title: 'List Excel cell styles',                readOnlyHint: true,  destructiveHint: false },
+  xlsx_verify_stamp:        { title: 'Verify Excel integrity stamp',          readOnlyHint: true,  destructiveHint: false },
+
+  // ---- Writing — non-destructive: 5 Save-As-shape tools -----------------
+  // Source workbook is preserved; output goes to a new path or returned bytes.
+  xlsx_write:               { title: 'Write Excel file',                      readOnlyHint: false, destructiveHint: false },
+  xlsx_redact:              { title: 'Redact Excel file',                     readOnlyHint: false, destructiveHint: false },
+  xlsx_convert:             { title: 'Convert Excel to other format',         readOnlyHint: false, destructiveHint: false },
+  xlsx_data_clean:          { title: 'Clean Excel data',                      readOnlyHint: false, destructiveHint: false },
+  xlsx_stamp:               { title: 'Stamp Excel with integrity verification', readOnlyHint: false, destructiveHint: false },
+
+  // ---- External side-effects — destructive: 2 tools ---------------------
+  // A post can't be undone; the message lands in a third-party system.
+  xlsx_post_slack:          { title: 'Post Excel summary to Slack',           readOnlyHint: false, destructiveHint: true },
+  xlsx_post_teams:          { title: 'Post Excel summary to Teams',           readOnlyHint: false, destructiveHint: true },
+});
+
+/**
+ * Overlay annotations onto an MCP-shaped tool array.
+ *
+ * Returns a new array with each tool extended with an `annotations` object
+ * pulled from TOOL_ANNOTATIONS by name. Tools without a known annotation
+ * pass through unchanged — this is intentional so that a dynamically-
+ * discovered tool the client doesn't recognize still appears, just without
+ * the annotation hints. The annotation map should be updated whenever
+ * a new tool is added to the server.
+ */
+// Keys we refuse to copy from upstream annotation objects — guards against
+// prototype-pollution if a remote /api/v1/tools/list ever returns hostile
+// data. Our overlay map is a frozen const so it's safe to spread directly;
+// the danger is only the foreign `existing` object.
+const POLLUTION_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+
+function applyAnnotations(tools) {
+  if (!Array.isArray(tools)) return tools;
+  return tools.map((t) => {
+    if (!t || typeof t.name !== 'string') return t;
+    const ann = TOOL_ANNOTATIONS[t.name];
+    if (!ann) return t;
+    // Preserve any annotations the upstream source already carries; ours fill
+    // in the gaps without clobbering richer remote data. Reject pollution
+    // keys and non-plain-object inputs.
+    const merged = { ...ann };
+    if (t.annotations && typeof t.annotations === 'object' && !Array.isArray(t.annotations)) {
+      for (const [k, v] of Object.entries(t.annotations)) {
+        if (POLLUTION_KEYS.has(k)) continue;
+        merged[k] = v;
+      }
+    }
+    return { ...t, annotations: merged };
+  });
+}
+
+module.exports = {
+  TOOL_ANNOTATIONS,
+  applyAnnotations,
+};

package/mcp.js

@@ -1045,6 +1045,129 @@ 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'],
+    },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -1567,6 +1690,54 @@ 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);
+  }
+
   // 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.26.0",
+  "version": "3.0.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": {
@@ -12,11 +12,12 @@
   "files": [
     "index.js",
     "mcp.js",
+    "lib/annotations.js",
     "lib/client.js",
     "lib/config.js",
-    "lib/register.js",
-    "lib/fallback-read.js",
     "lib/discover.js",
+    "lib/fallback-read.js",
+    "lib/register.js",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -25,6 +26,8 @@
     "test": "node --test test/v2/*.test.js",
     "build-manifests": "node scripts/build-manifests.js",
     "check-manifests": "node scripts/build-manifests.js --check",
+    "check-publish-allowlist": "node scripts/check-publish-allowlist.js",
+    "prepublishOnly": "node scripts/check-publish-allowlist.js && node scripts/build-manifests.js --check",
     "prepare": "husky"
   },
   "keywords": [