xlsx-for-ai 2.22.0 → 2.25.0

package/README.md

@@ -130,7 +130,7 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 
 ## What it does
 
-37 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).
+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).
 
 ### Triage / orient
 
@@ -196,6 +196,15 @@ For custom MCP clients, the binary is `xlsx-for-ai-mcp` (stdio transport). Overr
 | `xlsx_post_slack` | Post a workbook to a Slack channel as a file attachment with an optional message. BYOA — the agent supplies the user's Slack bot token (`xoxb-…`); the token is forwarded to Slack and never persisted. Uses Slack's external upload flow. |
 | `xlsx_post_teams` | Post a workbook to a Microsoft Teams channel as a file attachment in a channel message, with an optional message. BYOA — the agent supplies the user's Microsoft Graph access token (JWT); the token is forwarded to Microsoft and never persisted. Uses Graph's filesFolder + upload-session + post-message flow. |
 
+### Integrity verification
+
+| Tool | What it does |
+|---|---|
+| `xlsx_stamp` | Sign a workbook with a cryptographic "integrity verification" stamp — Ed25519-signed claims (named factual checks + their pass/fail/skip status + a content hash) embedded in `docProps/custom.xml`. The stamp travels with the file across saves; a recipient can verify it later to confirm the file hasn't been tampered with since signing. Factual attestations only — never an opinion-shaped seal of approval. |
+| `xlsx_verify_stamp` | Verify a workbook's embedded stamp. Returns (a) whether the Ed25519 signature is valid against the registered public key, (b) whether the workbook bytes match the hash IN the signed claims, and (c) the full check-result content of the stamp. Three distinct trust signals — signature integrity, content integrity, and what was originally attested. |
+| `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. |
+
 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.
 
 ---
@@ -355,3 +364,6 @@ The config file at `~/.xlsx-for-ai/config.json` is extended in-place — existin
 ## Security
 
 See [SECURITY.md](SECURITY.md). All file content is transmitted to `xlsx-for-ai-server.fly.dev` over HTTPS. Files are not retained beyond the duration of a single request on the free tier.
+
+<!-- ci-smoke-test: 2026-05-19 grace-review workflow -->
+<!-- retry: llm-review vendored -->

package/SECURITY.md

@@ -23,15 +23,16 @@ disclosure expectations in your first message.
 
 ## Supported versions
 
-The latest published `1.x` minor on npm receives security fixes. Older
-minors do not. Today that is `1.4.x`. If a fix requires a breaking change,
-it is shipped as a `2.x` and the prior minor is deprecated on npm.
-
-| Version | Status      | Security fixes |
-|---------|-------------|----------------|
-| 1.4.x   | current     | yes            |
-| 1.3.x   | superseded  | no             |
-| ≤ 1.2.x | superseded  | no             |
+The latest published `2.x` minor on npm receives security fixes. Older
+minors do not. Today that is `2.23.x`. If a fix requires a breaking change,
+it is shipped as the next `2.x` minor and the prior minor is deprecated on npm.
+
+| Version  | Status      | Security fixes |
+|----------|-------------|----------------|
+| 2.23.x   | current     | yes            |
+| 2.0–2.22 | superseded  | no             |
+| 1.5.x    | frozen      | no             |
+| ≤ 1.4.x  | superseded  | no             |
 
 ## What this project considers a security issue
 

package/index.js

@@ -6,6 +6,7 @@
  *
  * Usage:
  *   xlsx-for-ai <file.xlsx> [--json] [--md] [--sheet <name>] [--evaluate]
+ *   xlsx-for-ai <file.xlsx> --clean [--execute] [--json] [--sheet <name>] [--detectors <list>]
  *   xlsx-for-ai --telemetry-status
  *   xlsx-for-ai --enable-telemetry
  *   xlsx-for-ai --disable-telemetry
@@ -32,7 +33,8 @@ const {
 function parseArgs(argv) {
   const opts = { file: null, format: 'text', sheet: null, evaluate: false,
     telemetryStatus: false, enableTelemetry: false, disableTelemetry: false,
-    privacyStrict: false, showVersion: false };
+    privacyStrict: false, showVersion: false,
+    clean: false, execute: false, detectors: null };
   let i = 0;
   while (i < argv.length) {
     const a = argv[i];
@@ -45,18 +47,264 @@ function parseArgs(argv) {
     else if (a === '--disable-telemetry')  opts.disableTelemetry = true;
     else if (a === '--privacy=strict')     opts.privacyStrict = true;
     else if (a === '--version' || a === '-v') opts.showVersion = true;
+    else if (a === '--clean')              opts.clean = true;
+    else if (a === '--execute')            opts.execute = true;
+    else if (a === '--detectors') {
+      // Validate the next arg exists + isn't another flag — otherwise
+      // `--detectors --json` would silently swallow `--json` as the
+      // value. Caught by gpt-5 pre-push panel.
+      const next = argv[++i];
+      // Reject undefined, any `-`-prefixed token, or empty string —
+      // `--detectors ""` would otherwise silently disable detection.
+      // Caught by gpt-5 pre-push runs 2 + 3.
+      if (next === undefined || next.startsWith('-') || next.trim() === '') {
+        process.stderr.write('xlsx-for-ai: --detectors requires a non-empty value (comma-separated detector names)\n');
+        process.exit(2);
+      }
+      opts.detectors = next;
+    }
     else if (!a.startsWith('--'))          opts.file = a;
     i++;
   }
   return opts;
 }
 
+// ---------------------------------------------------------------------------
+// --clean flag — data-cleaning pipeline (xlsx_data_clean tool)
+// ---------------------------------------------------------------------------
+
+async function runClean(opts, absPath) {
+  const fileB64 = fs.readFileSync(absPath).toString('base64');
+  const body = { file_b64: fileB64, mode: opts.execute ? 'execute' : 'diagnose' };
+  if (opts.sheet) body.sheets = [opts.sheet];
+  if (opts.detectors) body.detectors = opts.detectors.split(',').map((s) => s.trim()).filter(Boolean);
+
+  let result;
+  try {
+    result = await callTool('xlsx_data_clean', body);
+  } catch (err) {
+    process.stderr.write(`xlsx-for-ai --clean error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const meta = (result && result._meta) || {};
+  if (opts.format === 'json') {
+    // Strip the cleaned-bytes blob from the JSON payload — it's
+    // re-emitted as a saved file below so stdout JSON stays small
+    // + human-readable.
+    const jsonOut = { ...meta };
+    delete jsonOut.file_b64;
+    process.stdout.write(JSON.stringify(jsonOut, null, 2) + '\n');
+  } else {
+    // Default: print the receipt markdown the server already
+    // synthesized.
+    const text = (result.content || []).map((c) => c.text).join('\n');
+    process.stdout.write(text + '\n');
+  }
+
+  // Execute mode + applied changes → save cleaned file next to the
+  // source. Cross-platform path derivation via Node's path.parse
+  // (caught by gpt-5 pre-push run 2): the earlier lastIndexOf('/')
+  // shortcut broke on Windows backslash paths + on directories with
+  // dots in the name. path.parse handles both.
+  if (opts.execute && meta.file_b64) {
+    let outPath = process.env.XFA_CLEAN_OUT;
+    if (!outPath) {
+      const parsed = path.parse(absPath);
+      outPath = path.join(parsed.dir, `${parsed.name}-cleaned${parsed.ext || '.xlsx'}`);
+    }
+    if (path.resolve(outPath) === path.resolve(absPath)) {
+      process.stderr.write('xlsx-for-ai --clean: refusing to overwrite source; set XFA_CLEAN_OUT to an explicit output path\n');
+      process.exit(1);
+    }
+    try {
+      fs.writeFileSync(outPath, Buffer.from(meta.file_b64, 'base64'));
+      process.stderr.write(`Cleaned file written to: ${outPath}\n`);
+    } catch (e) {
+      // Caught by gpt-5 pre-push run 2: writeFileSync throws on
+      // missing directory / permissions / disk-full. Wrap so the
+      // user sees a clear error + exit code, not a stack trace.
+      process.stderr.write(`xlsx-for-ai --clean: failed to write ${outPath}: ${e.message}\n`);
+      process.exit(1);
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Stamp / Receipt subcommands — thin wrappers around the MCP tool relays.
+//
+// CLI surface (per ana/specs/stamp.md §4.2 + ana/specs/receipt.md §4.4):
+//   xlsx-for-ai stamp <path> --checks <file.json> [--out <path>] [--exclude <s>...] [--supervisor <ver>]
+//   xlsx-for-ai verify-stamp <path>
+//   xlsx-for-ai receipt <path> --agent <name> [--display-name <s>] [--identity-url <u>]
+//       [--source <name>=<sha256>...] [--prompt-hash <sha256>] [--mcp-tool <name>...]
+//       [--description <s>] [--cover-sheet <s>...] [--out <path>]
+//   xlsx-for-ai verify-receipt <path>
+//
+// Exit codes (per spec/stamp.md §4.9):
+//   0 = success; 1 = verify returned valid=false; 2 = usage error;
+//   3 = server-side error; 4 = local file error.
+// ---------------------------------------------------------------------------
+
+const STAMP_SUBCOMMANDS = new Set(['stamp', 'verify-stamp', 'receipt', 'verify-receipt']);
+
+function nextRequiredArg(argv, i, flag) {
+  const v = argv[i + 1];
+  if (v === undefined || v.startsWith('-')) {
+    process.stderr.write(`xlsx-for-ai ${flag} requires a value\n`);
+    process.exit(2);
+  }
+  return v;
+}
+
+function loadChecksFile(checksPath) {
+  let raw;
+  try { raw = fs.readFileSync(path.resolve(checksPath), 'utf8'); }
+  catch (e) { process.stderr.write(`Cannot read --checks file: ${e.message}\n`); process.exit(4); }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (e) { process.stderr.write(`--checks file is not valid JSON: ${e.message}\n`); process.exit(2); }
+  if (!Array.isArray(parsed)) {
+    process.stderr.write('--checks file must contain a JSON array of {id, name, status, detail?}\n');
+    process.exit(2);
+  }
+  return parsed;
+}
+
+async function runStampSubcommand(subcmd, rest) {
+  if (rest.length === 0 || rest[0].startsWith('-')) {
+    process.stderr.write(`Usage: xlsx-for-ai ${subcmd} <path> [...]\n`);
+    process.exit(2);
+  }
+  const filePath = path.resolve(rest[0]);
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`File not found: ${filePath}\n`);
+    process.exit(4);
+  }
+  await ensureRegistered();
+  const fileB64 = fs.readFileSync(filePath).toString('base64');
+
+  if (subcmd === 'stamp') {
+    let checksPath = null, outPath = null, supervisor = null;
+    const excludeSheets = [];
+    for (let i = 1; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--checks')          checksPath = nextRequiredArg(rest, i++, '--checks');
+      else if (a === '--out')        outPath    = nextRequiredArg(rest, i++, '--out');
+      else if (a === '--supervisor') supervisor = nextRequiredArg(rest, i++, '--supervisor');
+      else if (a === '--exclude')    excludeSheets.push(nextRequiredArg(rest, i++, '--exclude'));
+      else { process.stderr.write(`Unknown flag: ${a}\n`); process.exit(2); }
+    }
+    if (!checksPath) { process.stderr.write('--checks <file.json> is required for stamp\n'); process.exit(2); }
+    const body = { file_b64: fileB64, checks: loadChecksFile(checksPath) };
+    if (excludeSheets.length) body.exclude_sheets = excludeSheets;
+    if (supervisor) body.generated_by = { npm: 'xlsx-for-ai@' + require('./package.json').version, supervisor };
+    const result = await callServerForStamp('xlsx_stamp', body, outPath, filePath, '.stamped.xlsx');
+    process.stdout.write(JSON.stringify(result._meta || {}, null, 2) + '\n');
+    return 0;
+  }
+
+  if (subcmd === 'verify-stamp') {
+    const body = { file_b64: fileB64 };
+    const result = await callTool('xlsx_verify_stamp', body);
+    const meta = result._meta || {};
+    process.stdout.write(JSON.stringify(meta, null, 2) + '\n');
+    return meta.valid === true ? 0 : 1;
+  }
+
+  if (subcmd === 'receipt') {
+    let agentName = null, displayName = null, identityUrl = null;
+    let promptHash = null, description = null, outPath = null;
+    const sourceFileHashes = [];
+    const mcpToolsCalled = [];
+    const coverSheets = [];
+    for (let i = 1; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--agent')              agentName     = nextRequiredArg(rest, i++, '--agent');
+      else if (a === '--display-name')  displayName   = nextRequiredArg(rest, i++, '--display-name');
+      else if (a === '--identity-url')  identityUrl   = nextRequiredArg(rest, i++, '--identity-url');
+      else if (a === '--prompt-hash')   promptHash    = nextRequiredArg(rest, i++, '--prompt-hash');
+      else if (a === '--description')   description   = nextRequiredArg(rest, i++, '--description');
+      else if (a === '--out')           outPath       = nextRequiredArg(rest, i++, '--out');
+      else if (a === '--mcp-tool')      mcpToolsCalled.push(nextRequiredArg(rest, i++, '--mcp-tool'));
+      else if (a === '--cover-sheet')   coverSheets.push(nextRequiredArg(rest, i++, '--cover-sheet'));
+      else if (a === '--source') {
+        const pair = nextRequiredArg(rest, i++, '--source');
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx < 0) {
+          process.stderr.write('--source requires <name>=<sha256> form\n');
+          process.exit(2);
+        }
+        sourceFileHashes.push({ name: pair.slice(0, eqIdx), sha256: pair.slice(eqIdx + 1) });
+      }
+      else { process.stderr.write(`Unknown flag: ${a}\n`); process.exit(2); }
+    }
+    if (!agentName) { process.stderr.write('--agent <name> is required for receipt\n'); process.exit(2); }
+    const body = { file_b64: fileB64, agent: { name: agentName } };
+    if (displayName)  body.agent.display_name  = displayName;
+    if (identityUrl)  body.agent.identity_url  = identityUrl;
+    const inputs = {};
+    if (sourceFileHashes.length) inputs.source_file_hashes = sourceFileHashes;
+    if (promptHash)              inputs.prompt_hash         = promptHash;
+    if (mcpToolsCalled.length)   inputs.mcp_tools_called    = mcpToolsCalled;
+    if (Object.keys(inputs).length) body.inputs = inputs;
+    if (description) body.description = description;
+    if (coverSheets.length) body.covers_sheets = coverSheets;
+    const result = await callServerForStamp('xlsx_receipt', body, outPath, filePath, '.receipted.xlsx');
+    process.stdout.write(JSON.stringify(result._meta || {}, null, 2) + '\n');
+    return 0;
+  }
+
+  if (subcmd === 'verify-receipt') {
+    const body = { file_b64: fileB64 };
+    const result = await callTool('xlsx_verify_receipt', body);
+    const meta = result._meta || {};
+    process.stdout.write(JSON.stringify(meta, null, 2) + '\n');
+    return meta.valid === true ? 0 : 1;
+  }
+  return 2;
+}
+
+async function callServerForStamp(tool, body, explicitOutPath, sourcePath, sidecarSuffix) {
+  let result;
+  try {
+    result = await callTool(tool, body);
+  } catch (err) {
+    process.stderr.write(`xlsx-for-ai ${tool}: ${err.message}\n`);
+    process.exit(err.code === 'API_UNREACHABLE' || err.code === 'API_SERVER_ERROR' ? 3 : 1);
+  }
+  const meta = result._meta || {};
+  if (!meta.file_b64) return result;
+  let outPath = explicitOutPath;
+  if (!outPath) {
+    const parsed = path.parse(sourcePath);
+    outPath = path.join(parsed.dir, `${parsed.name}${sidecarSuffix}`);
+  }
+  if (path.resolve(outPath) === path.resolve(sourcePath)) {
+    process.stderr.write(`xlsx-for-ai ${tool}: refusing to overwrite source — pass --out <other-path>\n`);
+    process.exit(2);
+  }
+  try { fs.writeFileSync(outPath, Buffer.from(meta.file_b64, 'base64')); }
+  catch (e) { process.stderr.write(`xlsx-for-ai ${tool}: failed to write ${outPath}: ${e.message}\n`); process.exit(4); }
+  process.stderr.write(`Wrote ${outPath}\n`);
+  return result;
+}
+
 async function main() {
-  const opts = parseArgs(process.argv.slice(2));
+  // Subcommand dispatch — stamp/verify-stamp/receipt/verify-receipt
+  // route through dedicated handlers; everything else uses the legacy
+  // flag-only CLI (xlsx-for-ai <file> [--json|--md|--clean|...]).
+  const argv = process.argv.slice(2);
+  if (argv.length > 0 && STAMP_SUBCOMMANDS.has(argv[0])) {
+    const code = await runStampSubcommand(argv[0], argv.slice(1));
+    process.exit(code);
+  }
+
+  const opts = parseArgs(argv);
 
   if (opts.showVersion) { console.log(require('./package.json').version); return; }
   if (opts.telemetryStatus) { console.log(telemetryStatus()); return; }
@@ -82,6 +330,13 @@ async function main() {
     process.env.XFA_PRIVACY = 'strict';
   }
 
+  // --clean diverts to the data-cleaning pipeline before falling
+  // through to the default xlsx_read path.
+  if (opts.clean) {
+    await runClean(opts, absPath);
+    return;
+  }
+
   const fileB64 = fs.readFileSync(absPath).toString('base64');
   // Server format enum is 'md' | 'json' | 'sql'. The legacy CLI default 'text'
   // maps to the server's default (md). Don't send 'text' — server rejects it.

package/lib/fallback-read.js

@@ -8,20 +8,75 @@
  * clear message if it isn't installed.
  *
  * Returns the same shape as the API: { content: [{ type: 'text', text }], _meta }
+ *
+ * Asymmetry vs. the hosted API (callers should be aware):
+ *   - options.sheet IS honored — the response is filtered to the named sheet.
+ *   - options.format is NOT honored — fallback always emits plain text.
+ *   - options.evaluate is NOT honored — formulas render as the cached values
+ *     stored in the workbook, not re-evaluated by a formula engine.
+ *
+ * When any option is passed and ignored, a visible warning is prepended to
+ * the text content AND the ignored option names are echoed back via
+ * _meta.ignored_options. Callers can detect fallback unambiguously via
+ * _meta.source === 'local-fallback'.
  */
 
-const fs   = require('fs');
 const path = require('path');
 
 function requireEngine() {
   try {
     return require('@protobi/exceljs');
-  } catch (_) {
-    const e = new Error(
+  } catch (e) {
+    // Only translate the "module not installed" case. A real bug inside the
+    // engine (syntax error, transitive missing dep, etc.) must surface as the
+    // original error, not get misreported as a missing-install.
+    const isModuleNotFound =
+      e && e.code === 'MODULE_NOT_FOUND' && String(e.message || '').includes('@protobi/exceljs');
+    if (!isModuleNotFound) throw e;
+    const err = new Error(
       'Local fallback requires `npm install @protobi/exceljs` ' +
       '(this is normally not needed when the hosted API is available).'
     );
-    e.code = 'FALLBACK_ENGINE_MISSING';
+    err.code = 'FALLBACK_ENGINE_MISSING';
+    throw err;
+  }
+}
+
+// @protobi/exceljs's cell.text getter throws on merge cells whose master
+// value is null — produced by SEC XBRL→xlsx converters and probably any
+// other tool that writes merge regions before populating the master cell.
+// The thrown shape is `TypeError: Cannot read properties of null (reading
+// 'toString')` from inside the MergeValue / value getter chain. Guard the
+// access so one cell of one sheet can't crash the entire dump, but only
+// swallow the exact null-deref TypeError class — anything else (a real
+// bug in the engine, a structural surprise we haven't characterized)
+// rethrows so we don't silently render data as empty.
+function safeCellText(cell) {
+  try {
+    const t = cell.text;
+    return t != null ? String(t) : '';
+  } catch (e) {
+    // Extract the message defensively — an exotic error whose `message`
+    // getter itself throws would otherwise crash the handler. The inner
+    // try/catch defaults to '' so the regex test below is always safe.
+    let msg = '';
+    try { msg = String((e && e.message) || ''); } catch (_) { msg = ''; }
+
+    // Match the exact null-deref TypeError shape — NOT any TypeError whose
+    // message contains "null", and NOT undefined-deref either. The bug
+    // class we're defending against (merge cells whose master value is
+    // explicitly null, produced by SEC XBRL→xlsx converters) emits null,
+    // never undefined; an undefined-deref here is more likely a real bug
+    // in the engine or upstream code and should surface, not be silenced.
+    // Regexes are anchored both ends so partial-prefix matches can't slip
+    // through. Two alternations cover modern V8 ("…properties of null
+    // (reading 'x')") and legacy V8 ("…property 'x' of null") for older
+    // Node runtimes some consumers may still pin to.
+    const isNullDeref = e instanceof TypeError && (
+      /^Cannot read properties of null(?: \(reading '.*'\))?$/.test(msg) ||
+      /^Cannot read property '.*' of null$/.test(msg)
+    );
+    if (isNullDeref) return '';
     throw e;
   }
 }
@@ -31,23 +86,55 @@ async function fallbackRead(filePath, options = {}) {
   const wb = new ExcelJS.Workbook();
   await wb.xlsx.readFile(filePath);
 
+  const requestedSheet = options.sheet || null;
+  // Detect presence (not truthiness) so the caller's intent is honored even
+  // for falsy-but-passed values like format:'' or evaluate:false.
+  const ignoredOptions = [];
+  if ('format' in options)   ignoredOptions.push('format');
+  if ('evaluate' in options) ignoredOptions.push('evaluate');
+
   const lines = [];
+  const warningParts = ['⚠ API unreachable — local fallback active.'];
+  if (ignoredOptions.length > 0) {
+    warningParts.push(`Options not honored by fallback: ${ignoredOptions.join(', ')}.`);
+  }
+  lines.push(warningParts.join(' '));
+  lines.push('');
+
+  let sheetMatched = false;
   wb.eachSheet((sheet) => {
+    if (requestedSheet && sheet.name !== requestedSheet) return;
+    sheetMatched = true;
     lines.push(`## Sheet: ${sheet.name}`);
     sheet.eachRow((row) => {
       const vals = [];
       row.eachCell({ includeEmpty: true }, (cell) => {
-        vals.push(cell.text != null ? String(cell.text) : '');
+        vals.push(safeCellText(cell));
       });
       lines.push(vals.join('\t'));
     });
     lines.push('');
   });
 
+  if (requestedSheet && !sheetMatched) {
+    const available = wb.worksheets.map((s) => s.name);
+    lines.push(
+      available.length === 0
+        ? `(no sheet named "${requestedSheet}" — workbook has no sheets)`
+        : `(no sheet named "${requestedSheet}" — workbook has: ${available.join(', ')})`
+    );
+  }
+
   const text = lines.join('\n');
   return {
     content: [{ type: 'text', text }],
-    _meta: { source: 'local-fallback', engine: '@protobi/exceljs', file: path.basename(filePath) },
+    _meta: {
+      source: 'local-fallback',
+      engine: '@protobi/exceljs',
+      file: path.basename(filePath),
+      sheet_filter: requestedSheet,
+      ignored_options: ignoredOptions,
+    },
   };
 }
 

package/mcp.js

@@ -17,6 +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 fs                   = require('fs');
 const fsPromises           = require('fs/promises');
 const path                 = require('path');
@@ -453,6 +454,68 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'xlsx_data_clean',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: AI-native data cleaning. Scans a workbook for the seven most common data-grime issues — NA variants (N/A, NA, null, -), merged-cell residue, type-coercion mistakes (numeric-as-text / date-as-serial / leading-zero stripped), trailing-row noise (footers / totals), header-row-not-first (preamble before headers), encoding glitches (UTF-8-as-CP1252 mojibake like Café), and duplicate column headers — and either flags them (diagnose mode) or applies deterministic fixes (execute mode).\n' +
+      'No other tool gives this in a single call: pandas does ad-hoc fixes inline; openpyxl is structure-only; pre-existing Python "clean" libraries are domain-specific. xlsx_data_clean is the only single-call clean pipeline with an explicit informer-not-enforcer contract: every fix surfaces as a Finding the caller can accept / reject / scope-override before the file is mutated.\n\n' +
+      'USE WHEN: an upstream pipeline produced an xlsx that\'s about to feed an LLM or downstream analysis and you want a one-pass scrub. Or you just got a "messy" export (financial reports with merged title banners, CRM exports with stripped zip codes, survey data with NA-variant noise) and need it normalized before reading. ' +
+      'Free tier — counts against the 10k/mo cap.\n\n' +
+      'DO NOT USE WHEN: domain-specific transforms are needed (use a dedicated pipeline; this tool is general-purpose). Or for structural integrity checks (use xlsx_doctor). Or for upload/attached files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file.' },
+        mode: {
+          type: 'string',
+          enum: ['diagnose', 'execute'],
+          description: 'diagnose (default): return findings only, file untouched. execute: apply deterministic fixes; cleaned bytes returned in _meta.file_b64.',
+        },
+        detectors: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Subset of detectors to run. Default: all 7 (na_variant, merged_cell_residue, type_coercion_mistake, trailing_row_noise, header_row_not_first, encoding_glitch, duplicate_header).',
+        },
+        sheets: { type: 'array', items: { type: 'string' }, description: 'Restrict to these sheet names. Default: all sheets.' },
+        options: {
+          type: 'object',
+          description: 'Detector tunables.',
+          properties: {
+            trailing_threshold: { type: 'integer', minimum: 1, maximum: 100, description: 'Min consecutive noise rows to flag (default 3).' },
+            header_scan_depth: { type: 'integer', minimum: 2, maximum: 50, description: 'Rows to scan for header inference (default 10).' },
+            na_canonical: { type: 'string', description: 'Replacement value for NA tokens. "" (default), "null", "(blank)", or any string.' },
+          },
+        },
+        overrides: {
+          type: 'array',
+          description: 'Per-detector / per-scope skip / flag_only / force overrides.',
+          items: {
+            type: 'object',
+            properties: {
+              detector: { type: 'string' },
+              scope: {
+                type: 'object',
+                properties: {
+                  sheet: { type: 'string' },
+                  column_letter: { type: 'string', description: 'A-Z column letter; alternative to region.' },
+                  region: { type: 'object', properties: { top_left: { type: 'string' }, bottom_right: { type: 'string' } } },
+                },
+                required: ['sheet'],
+              },
+              action: { type: 'string', enum: ['skip', 'flag_only', 'force'] },
+            },
+            required: ['detector', 'scope', 'action'],
+          },
+        },
+        accept_findings: { type: 'array', items: { type: 'string' }, description: 'Execute mode only — finding IDs to apply. Default: all.' },
+        reject_findings: { type: 'array', items: { type: 'string' }, description: 'Execute mode only — finding IDs to skip.' },
+        out_path: { type: 'string', description: 'Optional save path for cleaned output (execute mode).' },
+      },
+      required: ['file_path'],
+    },
+  },
+
   {
     name: 'xlsx_validate',
     description:
@@ -832,21 +895,23 @@ const TOOLS = [
     name: 'xlsx_post_slack',
     description:
       'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message. BYOA — the agent must pass the user\'s Slack bot token (xoxb-…). The token is forwarded to Slack and never stored server-side.\n' +
+      'This tool: upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message.\n' +
+      'Token intake: set SLACK_BOT_TOKEN in the environment (recommended — keeps the token out of conversation logs). ' +
+      'Alternatively pass slack_token as a tool argument (legacy; token will appear in MCP conversation history).\n' +
       'Posts via Slack\'s 3-step external upload flow (files.getUploadURLExternal → upload → files.completeUploadExternal), which is the only sanctioned path as of 2024+.\n\n' +
       'USE WHEN: the user asks "post this workbook to #channel," "share this with the team in Slack," or any other outbound-file-to-Slack request. The agent has just produced or modified a workbook and wants to deliver it. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: the file lives in a Slack channel and you want to READ it (that\'s the inbound Manual-Mode-Detector pattern, not this). Or when there is no Slack bot token available — the user must have installed a Slack app with files:write scope.',
+      'DO NOT USE WHEN: the file lives in a Slack channel and you want to READ it (that\'s the inbound Manual-Mode-Detector pattern, not this). Or when no Slack bot token is available — the user must have installed a Slack app with files:write scope.',
     inputSchema: {
       type: 'object',
       properties: {
         file_path: { type: 'string', description: 'Absolute path to the .xlsx file to post.' },
         channel: { type: 'string', description: 'Slack channel ID (C…/G…) the file should land in. Channel names like #general are NOT accepted — resolve to a channel ID first.' },
-        slack_token: { type: 'string', description: 'Slack bot token (xoxb-…). Forwarded to Slack; never persisted by us.' },
+        slack_token: { type: 'string', description: 'Slack bot token (xoxb-…). Optional when SLACK_BOT_TOKEN env var is set. Passing the token here exposes it in MCP conversation logs — prefer the env var.' },
         message: { type: 'string', description: 'Optional: message to post alongside the file (Slack\'s initial_comment).' },
         filename: { type: 'string', description: 'Optional: filename Slack will display. Defaults to the basename of file_path.' },
       },
-      required: ['file_path', 'channel', 'slack_token'],
+      required: ['file_path', 'channel'],
     },
   },
 
@@ -854,32 +919,233 @@ const TOOLS = [
     name: 'xlsx_post_teams',
     description:
       'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
-      'This tool: upload a local .xlsx file to a Microsoft Teams channel as a file attachment in a channel message, with an optional accompanying message. BYOA — the agent must pass the user\'s Microsoft Graph access token (a JWT starting with "eyJ"). The token is forwarded to Microsoft Graph and never stored server-side.\n' +
+      'This tool: upload a local .xlsx file to a Microsoft Teams channel as a file attachment in a channel message, with an optional accompanying message.\n' +
+      'Token intake: set TEAMS_GRAPH_TOKEN in the environment (recommended — keeps the token out of conversation logs). ' +
+      'Alternatively pass graph_token as a tool argument (legacy; token will appear in MCP conversation history).\n' +
       'Uses Microsoft Graph\'s 4-step flow: locate the channel\'s filesFolder driveItem, create an upload session, upload the bytes, then post a chatMessage with the file as an inline attachment.\n\n' +
       'USE WHEN: the user asks "post this workbook to my Teams channel," "share this with the team in Teams," or any other outbound-file-to-Teams request. The agent has just produced or modified a workbook and wants to deliver it to a Microsoft Teams channel. ' +
       'Free tier — counts against the 10k/mo cap.\n\n' +
-      'DO NOT USE WHEN: posting to Slack (use xlsx_post_slack). Or when there is no Microsoft Graph token available — the user must have an Entra ID app registration with Group.ReadWrite.All or Files.ReadWrite.All + ChannelMessage.Send scopes, AND a valid access token for that app.',
+      'DO NOT USE WHEN: posting to Slack (use xlsx_post_slack). Or when no Microsoft Graph token is available — the user must have an Entra ID app registration with Group.ReadWrite.All or Files.ReadWrite.All + ChannelMessage.Send scopes, AND a valid access token for that app.',
     inputSchema: {
       type: 'object',
       properties: {
         file_path: { type: 'string', description: 'Absolute path to the .xlsx file to post.' },
         team_id: { type: 'string', description: 'Microsoft Teams team ID (GUID). Find via Graph: GET /me/joinedTeams.' },
         channel_id: { type: 'string', description: 'Microsoft Teams channel ID. Find via Graph: GET /teams/{team-id}/channels.' },
-        graph_token: { type: 'string', description: 'Microsoft Graph access token (JWT). Forwarded to Microsoft; never persisted by us. Must have file-upload + channel-message-send scopes.' },
+        graph_token: { type: 'string', description: 'Microsoft Graph access token (JWT). Optional when TEAMS_GRAPH_TOKEN env var is set. Passing the token here exposes it in MCP conversation logs — prefer the env var. Must have file-upload + channel-message-send scopes.' },
         message: { type: 'string', description: 'Optional: message to post alongside the file. Plain text; will be HTML-escaped server-side.' },
         filename: { type: 'string', description: 'Optional: filename Teams will display. Defaults to the basename of file_path.' },
       },
-      required: ['file_path', 'team_id', 'channel_id', 'graph_token'],
+      required: ['file_path', 'team_id', 'channel_id'],
+    },
+  },
+
+  {
+    name: 'xlsx_stamp',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: sign a workbook with a "workbook integrity verification" stamp — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by these tools, passed these N specific checks, signed at this time, and hasn\'t been tampered with since." Factual claims only (never an opinion-shaped seal of approval). Returns the stamped workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n' +
+      'The caller supplies the `checks` array (e.g., from a supervisor review): list of named tests, each with passed/failed/skipped status. Verifiers see the individual check results, not a single good/bad opinion.\n\n' +
+      'USE WHEN: the agent has just produced or reviewed a workbook and wants to attach provable provenance + check results that travel with the file. The recipient can later verify the stamp via xlsx_verify_stamp to confirm the file hasn\'t been modified and to see the original check results.\n\n' +
+      'DO NOT USE WHEN: the user just wants to share a file (use xlsx_post_slack / xlsx_post_teams). Or when there are no real checks to attest to (an empty checks array is allowed and means "we ran zero checks" — but the stamp\'s value is in the checks it records).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to stamp.' },
+        checks: {
+          type: 'array',
+          description: 'Array of named checks, each with passed/failed/skipped status. These are the factual claims the stamp attests to.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Stable check identifier (e.g., "tieouts_consistent").' },
+              name: { type: 'string', description: 'Human-readable check name.' },
+              status: { type: 'string', enum: ['passed', 'failed', 'skipped'] },
+              detail: { type: 'string', description: 'Optional explanation, especially for failed/skipped status.' },
+            },
+            required: ['id', 'name', 'status'],
+          },
+        },
+        out_path: { type: 'string', description: 'Optional: write the stamped workbook to this absolute path. If omitted, the stamped bytes are returned in _meta.file_b64 only.' },
+        exclude_sheets: { type: 'array', items: { type: 'string' }, description: 'Optional: sheet names to exclude from the content hash. Use for scratch tabs that legitimately change without affecting attestation.' },
+        supervisor_version: { type: 'string', description: 'Optional: xlsx-supervisor version string to include in the stamp\'s generated_by claim (e.g., "xlsx-supervisor@1.4.0").' },
+      },
+      required: ['file_path', 'checks'],
+    },
+  },
+
+  {
+    name: 'xlsx_verify_stamp',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: verify a workbook\'s embedded integrity-verification stamp. Returns whether the cryptographic signature is valid, whether the workbook bytes match what was signed (recomputed hash vs hash IN the stamp), and the full check-result content of the stamp.\n' +
+      'A workbook can fail verification three ways: (1) no stamp present (file was never stamped, or the stamp was stripped); (2) signature_valid=false (someone modified the claims after signing, or signed with a different key); (3) hash_matches=false (someone modified the workbook bytes after signing). Each is a distinct trust signal.\n\n' +
+      'USE WHEN: the agent (or a downstream verifier) needs to confirm a workbook hasn\'t been tampered with since it was signed, OR needs to surface the original check results that were attested to. Common scenario: incoming workbook from a counterparty, agent runs verify before trusting any of its values.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to verify.' },
+      },
+      required: ['file_path'],
+    },
+  },
+
+  {
+    name: 'xlsx_receipt',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: attach an AI-generation receipt to a workbook — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by THIS agent, at THIS time, against THESE inputs." Returns the receipted workbook as base64 in _meta.file_b64; pass out_path to write to disk.\n' +
+      'Honesty boundary (load-bearing): the server signs the CALLER-DECLARED `agent.name` — it does NOT verify the caller actually IS that agent. The signature proves "this server signed these strings at this time," not "this came from claude-sonnet-4-6." Caller is responsible for honest declaration. Cryptographic identity binding (per-agent issued signing keys) is v1.1+ scope.\n\n' +
+      'USE WHEN: an AI agent (Claude, custom SDK agent, automated pipeline) generates a workbook and the recipient wants verifiable provenance — "what produced this file, when, against what." Or chaining attestations across a multi-step pipeline (each step adds its own receipt under different agent.name).\n\n' +
+      'DO NOT USE WHEN: the workbook was human-authored (use xlsx_stamp — Stamp attests to check results, Receipt attests to generation context). Or when the use case demands cryptographically-bound identity (v1.1+).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to receipt.' },
+        agent_name: {
+          type: 'string',
+          description: 'Canonical agent name (lowercase + dot/dash/underscore/slash/colon, 1-128 chars). Examples: "claude-sonnet-4-6", "claude-code/0.5.2", "custom:my-agent-v1".',
+        },
+        agent_display_name: { type: 'string', description: 'Optional: human-readable display name (e.g., "Acme Q4 Forecast Bot").' },
+        agent_identity_url: { type: 'string', description: 'Optional: caller-declared identity URL (GitHub repo, registry entry, etc.).' },
+        source_file_hashes: {
+          type: 'array',
+          description: 'Optional: array of {name, sha256} entries describing source files the agent read to produce this workbook.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              sha256: { type: 'string', description: 'Hex SHA-256 (64 lowercase chars).' },
+            },
+            required: ['name', 'sha256'],
+          },
+        },
+        prompt_hash: { type: 'string', description: 'Optional: hex SHA-256 of the prompt or instruction set that produced the workbook.' },
+        mcp_tools_called: { type: 'array', items: { type: 'string' }, description: 'Optional: list of MCP tool names the agent called during generation.' },
+        description: { type: 'string', description: 'Optional: short human-readable description of what the workbook is (≤256 chars).' },
+        covers_sheets: { type: 'array', items: { type: 'string' }, description: 'Optional: sheets covered by the content hash. Default: all sheets.' },
+        out_path: { type: 'string', description: 'Optional: write the receipted workbook to this absolute path. If omitted, the bytes are returned in _meta.file_b64 only.' },
+      },
+      required: ['file_path', 'agent_name'],
+    },
+  },
+
+  {
+    name: 'xlsx_verify_receipt',
+    description:
+      'xlsx-for-ai — read, write, diff, redact, supervise .xlsx files locally.\n' +
+      'This tool: verify a workbook\'s embedded AI-generation receipt. Returns whether the signature is valid, whether the recomputed content hash matches the hash IN the receipt, and the full caller-declared claims (agent identity, generation timestamp, source-file hashes, prompt hash, MCP tools called, description).\n' +
+      'A workbook can fail verification three ways: (1) no receipt present (never receipted, or receipt was stripped); (2) signature_valid=false (claims modified after signing); (3) hash_matches=false (workbook bytes modified after receipt was generated). Honesty: a valid receipt proves the SERVER signed the caller-DECLARED agent string — not that the agent IS that.\n\n' +
+      'USE WHEN: a workbook arrives claiming AI provenance and the user wants to verify it. Or auditing a corpus of workbooks to find ones with broken receipts (likely-tampered) or no receipts at all.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the .xlsx file to verify.' },
+      },
+      required: ['file_path'],
     },
   },
 ];
 
 // ---------------------------------------------------------------------------
 // File → base64 helper
+//
+// Security: only spreadsheet extensions are permitted. Any path that resolves
+// to a non-allowed extension (or does not exist) is rejected immediately so a
+// misbehaving agent cannot exfiltrate arbitrary local files via a tool call.
+//
+// Stability: a size cap is enforced before the synchronous read so a giant
+// workbook can't OOM-kill the MCP server (which would disconnect every tool
+// for the user). Override via XFA_MAX_FILE_MB; default is 50 MB.
 // ---------------------------------------------------------------------------
 
+const ALLOWED_READ_EXTENSIONS = new Set(['.xlsx', '.xls', '.xlsm', '.xlsb', '.csv', '.ods', '.fods', '.numbers', '.tsv']);
+const DEFAULT_MAX_FILE_MB = 50;
+
+function getMaxFileMB() {
+  const raw = process.env.XFA_MAX_FILE_MB;
+  if (!raw) return DEFAULT_MAX_FILE_MB;
+  const parsed = parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MAX_FILE_MB;
+  return parsed;
+}
+
 function fileToB64(filePath) {
-  return fs.readFileSync(filePath).toString('base64');
+  const resolved = path.resolve(filePath);
+
+  // Open the file once and operate on the fd from here on. fstatSync and the
+  // subsequent read both bind to the inode the fd points at, so even if the
+  // path is swapped after the size check the bytes we hash are the bytes we
+  // sized — the size-cap TOCTOU is closed.
+  // O_NOFOLLOW (where available) refuses symlinks at open time; it's undefined
+  // on Windows, where we fall back to 0 (symlink semantics differ there and
+  // the spreadsheet-extension allowlist is the load-bearing guard anyway).
+  const O_NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+  let fd;
+  try {
+    fd = fs.openSync(resolved, fs.constants.O_RDONLY | O_NOFOLLOW);
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      const err = new Error(`File not found: ${resolved}`);
+      err.code = 'FILE_NOT_FOUND';
+      throw err;
+    }
+    if (e && e.code === 'ELOOP') {
+      const err = new Error(`Refusing to read symlink: ${resolved}`);
+      err.code = 'SYMLINK_REJECTED';
+      throw err;
+    }
+    throw e;
+  }
+
+  try {
+    const stat = fs.fstatSync(fd);
+
+    if (!stat.isFile()) {
+      const err = new Error(`Not a regular file: ${resolved}`);
+      err.code = 'NOT_REGULAR_FILE';
+      throw err;
+    }
+
+    const ext = path.extname(resolved).toLowerCase();
+    if (!ALLOWED_READ_EXTENSIONS.has(ext)) {
+      const err = new Error(
+        `Blocked: "${ext}" is not an allowed spreadsheet extension. ` +
+        `Allowed: ${[...ALLOWED_READ_EXTENSIONS].join(', ')}`
+      );
+      err.code = 'DISALLOWED_EXTENSION';
+      throw err;
+    }
+
+    const maxMB = getMaxFileMB();
+    if (stat.size > maxMB * 1024 * 1024) {
+      const sizeMB = stat.size / (1024 * 1024);
+      const err = new Error(
+        `File too large: ${sizeMB.toFixed(1)} MB exceeds the ${maxMB} MB cap. ` +
+        `Set XFA_MAX_FILE_MB to a higher value to allow larger workbooks. ` +
+        `(The cap protects the MCP server from OOM on synchronous base64 load — ` +
+        `a 200 MB workbook would allocate ~267 MB of base64 before any API call.)`
+      );
+      err.code = 'FILE_TOO_LARGE';
+      throw err;
+    }
+
+    // Read exactly stat.size bytes from the fd into a pre-sized buffer. If
+    // the file grows between fstat and now, the extra bytes are NOT read —
+    // we never allocate more than the validated cap. If the file shrinks
+    // (short read), we encode what we got and stop. This closes the
+    // grow-after-stat bypass on the size cap.
+    const buf = Buffer.alloc(stat.size);
+    let bytesRead = 0;
+    while (bytesRead < stat.size) {
+      const chunk = fs.readSync(fd, buf, bytesRead, stat.size - bytesRead, null);
+      if (chunk === 0) break;
+      bytesRead += chunk;
+    }
+    return buf.subarray(0, bytesRead).toString('base64');
+  } finally {
+    try { fs.closeSync(fd); } catch (_) { /* best effort */ }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -953,7 +1219,23 @@ async function dispatchTool(name, args) {
   if (name === 'xlsx_write') {
     let spec = args.spec;
     if (!spec && args.spec_path) {
-      spec = JSON.parse(fs.readFileSync(args.spec_path, 'utf8'));
+      // Security: spec_path must exist and must be a .json file.
+      const resolvedSpecPath = path.resolve(args.spec_path);
+      if (!fs.existsSync(resolvedSpecPath)) {
+        const err = new Error(`spec_path not found: ${resolvedSpecPath}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      const specExt = path.extname(resolvedSpecPath).toLowerCase();
+      if (specExt !== '.json') {
+        const err = new Error(
+          `spec_path must be a .json file; got "${specExt}". ` +
+          'Pass the workbook spec as inline JSON via the "spec" argument instead.'
+        );
+        err.code = 'DISALLOWED_EXTENSION';
+        throw err;
+      }
+      spec = JSON.parse(fs.readFileSync(resolvedSpecPath, 'utf8'));
     }
     const writeBody = { spec };
     if (args.base_file_b64) writeBody.base_file_b64 = args.base_file_b64;
@@ -1085,14 +1367,47 @@ async function dispatchTool(name, args) {
     });
   }
 
+  // xlsx_data_clean: scan + optional execute. Diagnose mode returns
+  // findings only (no file_b64 in _meta). Execute mode returns
+  // cleaned bytes in _meta.file_b64; applyFileB64 saves to out_path
+  // if provided. SPEC fields pass through verbatim — server validates.
+  if (name === 'xlsx_data_clean') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    if (args.mode !== undefined) body.mode = args.mode;
+    if (args.detectors !== undefined) body.detectors = args.detectors;
+    if (args.sheets !== undefined) body.sheets = args.sheets;
+    if (args.options !== undefined) body.options = args.options;
+    if (args.overrides !== undefined) body.overrides = args.overrides;
+    if (args.accept_findings !== undefined) body.accept_findings = args.accept_findings;
+    if (args.reject_findings !== undefined) body.reject_findings = args.reject_findings;
+    const result = await callTool('xlsx_data_clean', body);
+    return applyFileB64(result, args.out_path);
+  }
+
   // xlsx_post_slack: outbound file-to-Slack. Top-level fields, not the
   // standard {file_b64, options} shape — channel + slack_token + message
   // + filename live alongside file_b64 in the server route's body schema.
+  //
+  // Token resolution order (H3 fix):
+  //   1. SLACK_BOT_TOKEN env var (recommended — never enters conversation logs)
+  //   2. slack_token tool arg (legacy; visible in MCP conversation history)
+  // Error if neither is present.
   if (name === 'xlsx_post_slack') {
+    const slackToken = process.env.SLACK_BOT_TOKEN || args.slack_token;
+    if (!slackToken) {
+      const err = new Error(
+        'Slack token required. Set the SLACK_BOT_TOKEN environment variable ' +
+        '(recommended) or pass slack_token as a tool argument.'
+      );
+      err.code = 'MISSING_TOKEN';
+      throw err;
+    }
+    // fileToB64 enforces existence + extension allowlist (H1 fix) — only
+    // spreadsheet extensions (.xlsx, .xlsm, etc.) are permitted here.
     const body = {
       file_b64: fileToB64(args.file_path),
       channel: args.channel,
-      slack_token: args.slack_token,
+      slack_token: slackToken,
     };
     if (args.message !== undefined) body.message = args.message;
     body.filename = args.filename || path.basename(args.file_path);
@@ -1101,18 +1416,89 @@ async function dispatchTool(name, args) {
 
   // xlsx_post_teams: outbound file-to-Teams. Same shape as Slack but with
   // Microsoft Graph fields (team_id + channel_id + graph_token).
+  //
+  // Token resolution order (H3 fix):
+  //   1. TEAMS_GRAPH_TOKEN env var (recommended — never enters conversation logs)
+  //   2. graph_token tool arg (legacy; visible in MCP conversation history)
+  // Error if neither is present.
   if (name === 'xlsx_post_teams') {
+    const graphToken = process.env.TEAMS_GRAPH_TOKEN || args.graph_token;
+    if (!graphToken) {
+      const err = new Error(
+        'Microsoft Graph token required. Set the TEAMS_GRAPH_TOKEN environment variable ' +
+        '(recommended) or pass graph_token as a tool argument.'
+      );
+      err.code = 'MISSING_TOKEN';
+      throw err;
+    }
+    // fileToB64 enforces existence + extension allowlist (H1 fix) — only
+    // spreadsheet extensions (.xlsx, .xlsm, etc.) are permitted here.
     const body = {
       file_b64: fileToB64(args.file_path),
       team_id: args.team_id,
       channel_id: args.channel_id,
-      graph_token: args.graph_token,
+      graph_token: graphToken,
     };
     if (args.message !== undefined) body.message = args.message;
     body.filename = args.filename || path.basename(args.file_path);
     return callTool('xlsx_post_teams', body);
   }
 
+  // xlsx_stamp: sign + embed an integrity-verification stamp. Returns the
+  // stamped file as base64 in _meta.file_b64; if out_path is provided we
+  // also write the bytes to disk (same pattern as xlsx_write / xlsx_redact).
+  if (name === 'xlsx_stamp') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      checks: args.checks,
+    };
+    if (args.exclude_sheets !== undefined) body.exclude_sheets = args.exclude_sheets;
+    if (args.supervisor_version !== undefined) {
+      body.generated_by = { npm: 'xlsx-for-ai@' + require('./package.json').version, supervisor: args.supervisor_version };
+    }
+    const result = await callTool('xlsx_stamp', body);
+    return applyFileB64(result, args.out_path);
+  }
+
+  // xlsx_verify_stamp: extract + verify the integrity-verification stamp.
+  // Returns structured result in _meta.{valid, signature_valid, hash_matches,
+  // claims, workbook_hash_in_stamp, workbook_hash_recomputed, …}.
+  if (name === 'xlsx_verify_stamp') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    return callTool('xlsx_verify_stamp', body);
+  }
+
+  // xlsx_receipt: attach an AI-generation receipt. Server signs caller-
+  // declared agent + optional inputs (source-file hashes, prompt hash,
+  // mcp-tools-called) + optional description; embeds the SignedReceipt in
+  // docProps/custom.xml. Honesty: server signs the STRINGS the caller
+  // supplied; does NOT verify agent identity.
+  if (name === 'xlsx_receipt') {
+    const body = {
+      file_b64: fileToB64(args.file_path),
+      agent: { name: args.agent_name },
+    };
+    if (args.agent_display_name !== undefined) body.agent.display_name = args.agent_display_name;
+    if (args.agent_identity_url !== undefined) body.agent.identity_url = args.agent_identity_url;
+    const inputs = {};
+    if (args.source_file_hashes !== undefined) inputs.source_file_hashes = args.source_file_hashes;
+    if (args.prompt_hash !== undefined) inputs.prompt_hash = args.prompt_hash;
+    if (args.mcp_tools_called !== undefined) inputs.mcp_tools_called = args.mcp_tools_called;
+    if (Object.keys(inputs).length > 0) body.inputs = inputs;
+    if (args.description !== undefined) body.description = args.description;
+    if (args.covers_sheets !== undefined) body.covers_sheets = args.covers_sheets;
+    const result = await callTool('xlsx_receipt', body);
+    return applyFileB64(result, args.out_path);
+  }
+
+  // xlsx_verify_receipt: extract + verify the AI-generation receipt.
+  // Surfaces caller-declared agent.name as declared; no cryptographic
+  // identity binding in v1.
+  if (name === 'xlsx_verify_receipt') {
+    const body = { file_b64: fileToB64(args.file_path) };
+    return callTool('xlsx_verify_receipt', body);
+  }
+
   // All other tools (list_sheets, schema, hyperlinks, conditional_formats,
   // styles, etc.) — single-file relay. Forward any common option keys the
   // routes accept so we don't silently drop them. New keys added here as
@@ -1145,7 +1531,16 @@ async function main() {
   } catch (_) {
     catalog = { tools: TOOLS, source: 'static-fallback' };
   }
-  const liveTools = catalog.tools;
+  // 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 : []);
 
   const server = new Server(
     { name: 'xlsx-for-ai', version: require('./package.json').version },
@@ -1192,5 +1587,9 @@ if (require.main === module) {
   });
 }
 
-// Test-only exports — never import these in production code
-module.exports = { applyFileB64, dispatchTool };
+// Exports for build-time scripts and tests only. Do NOT import these from
+// runtime production code — they're only here to let the manifest-build
+// script use TOOLS as the single source of truth for downstream artifacts
+// (manifest.json, mcp-tools.json snapshot consumed by the MSFT plugin
+// manifest), and to expose helpers under test.
+module.exports = { applyFileB64, dispatchTool, TOOLS };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xlsx-for-ai",
   "mcpName": "io.github.senoff/xlsx-for-ai",
-  "version": "2.22.0",
+  "version": "2.25.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": {
@@ -22,7 +22,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/v2/*.test.js"
+    "test": "node --test test/v2/*.test.js",
+    "build-manifests": "node scripts/build-manifests.js",
+    "check-manifests": "node scripts/build-manifests.js --check",
+    "prepare": "husky"
   },
   "keywords": [
     "xlsx",
@@ -57,5 +60,8 @@
   },
   "optionalDependencies": {
     "@protobi/exceljs": "^4.4.0-protobi.9"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7"
   }
 }