xlsx-for-ai 3.0.4 → 3.0.8

package/lib/annotations.js

@@ -65,14 +65,26 @@ const TOOL_ANNOTATIONS = Object.freeze({
   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 },
+  xlsx_verify_receipt:      { title: 'Verify Excel provenance receipt',       readOnlyHint: true,  destructiveHint: false },
+  xlsx_read_handle:         { title: 'Read Excel by handle',                  readOnlyHint: true,  destructiveHint: false },
+  xlsx_healer_diagnose:     { title: 'Diagnose Excel external references',    readOnlyHint: true,  destructiveHint: false },
+  xlsx_healer_simulate:     { title: 'Simulate Excel reference repair',       readOnlyHint: true,  destructiveHint: false },
 
-  // ---- Writing — non-destructive: 5 Save-As-shape tools -----------------
+  // ---- Writing — non-destructive: 9 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 },
+  xlsx_receipt:             { title: 'Generate Excel provenance receipt',     readOnlyHint: false, destructiveHint: false },
+  xlsx_healer_cure:         { title: 'Repair Excel external references',      readOnlyHint: false, destructiveHint: false },
+  xlsx_healer_intent:       { title: 'Generate Excel repair-intent file',     readOnlyHint: false, destructiveHint: false },
+
+  // ---- Stateful session write: 1 tool -----------------------------------
+  // Mutates session-scoped state on the server (reversible by a follow-up call).
+  xlsx_session_set_validations:
+                            { title: 'Set Excel session validation rules',    readOnlyHint: false, destructiveHint: false },
 
   // ---- External side-effects — destructive: 2 tools ---------------------
   // A post can't be undone; the message lands in a third-party system.

package/lib/client.js

@@ -8,19 +8,53 @@
  * post(path, body, opts)         — POST JSON, returns parsed response body
  * callTool(toolName, body)       — POST /api/v1/tools/<toolName> with auth
  *
- * Retries once on network errors. Maps HTTP errors to structured Error objects.
+ * 15s per-attempt timeout, up to 3 attempts (45s ceiling). On retry the
+ * AbortController for the prior attempt has already fired, so any
+ * keep-alive socket undici held on the failing attempt is released
+ * before the retry opens a fresh one. Surfaces phase timing to stderr
+ * for production-incident diagnosis (SPM P1 2026-06-06: hosted tool
+ * calls timing out in Claude Desktop — server saw ~200ms responses
+ * but client saw 2-4 minute round-trips; the gap is in the connection
+ * dial / IPC layer, observability captures which next time).
  */
 
 const { readConfig } = require('./config');
 const { version: CLIENT_VERSION } = require('../package.json');
 
 const DEFAULT_API = 'https://api.xlsx-for-ai.dev';
-const TIMEOUT_MS  = 30_000;
+// Per-attempt timeout. Was 30s pre-3.0.7. Tighter so a stuck dial
+// (IPv6 black hole, stale keep-alive) fails fast and the retry path
+// reopens a fresh socket. 3 attempts × 15s = 45s ceiling, well under
+// Claude Desktop's 60s client-side initialize timeout AND under the
+// MCP tools/call timeout class.
+const TIMEOUT_MS  = 15_000;
+const MAX_ATTEMPTS = 3;
 
 function apiBase() {
   return (process.env.XLSX_FOR_AI_API || DEFAULT_API).replace(/\/$/, '');
 }
 
+// Stderr structured timing log. stdout is the MCP transport in the
+// mcp-server context; never write timing data there.
+function emitTiming(toolPath, attempt, phase, elapsedMs, extra) {
+  // One-line JSON so future log-shipper can grep / parse. Kept compact
+  // to stay inside Claude Desktop's MCP log buffer.
+  const obs = {
+    t: 'xlsx-for-ai-mcp.timing',
+    path: toolPath,
+    attempt,
+    phase,
+    elapsed_ms: Math.round(elapsedMs),
+  };
+  if (extra) Object.assign(obs, extra);
+  try {
+    process.stderr.write(JSON.stringify(obs) + '\n');
+  } catch (_) {
+    // EPIPE on stderr is swallowed by the mcp.js top-level guard;
+    // here we just no-op so a missing log sink doesn't break the call.
+  }
+}
+
 async function fetchWithTimeout(url, init) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
@@ -49,32 +83,71 @@ async function post(path, body, opts = {}) {
     headers['X-XFA-Privacy'] = 'strict';
   }
 
+  const requestStart = Date.now();
+  const jsonBody = JSON.stringify(body);
+  // Byte length (UTF-8), not code-unit length — multi-byte chars in the
+  // body would otherwise be undercounted in observability.
+  const bodyBytes = Buffer.byteLength(jsonBody, 'utf8');
+  // `attempt: -1` is the convention for non-attempt-scoped events
+  // (per-request setup / teardown); keeps the 1..MAX_ATTEMPTS scope
+  // unambiguous in log analysis.
+  emitTiming(path, -1, 'send', 0, { body_bytes: bodyBytes });
+
   let res;
-  try {
-    res = await fetchWithTimeout(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(body),
-    });
-  } catch (err) {
-    // One retry on network error
+  let lastErr;
+  let winningAttempt = -1;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    const attemptStart = Date.now();
     try {
       res = await fetchWithTimeout(url, {
         method: 'POST',
         headers,
-        body: JSON.stringify(body),
+        body: jsonBody,
+      });
+      const attemptElapsed = Date.now() - attemptStart;
+      emitTiming(path, attempt, 'response-headers', attemptElapsed, {
+        status: res.status,
+      });
+      lastErr = null;
+      winningAttempt = attempt;
+      break;
+    } catch (err) {
+      lastErr = err;
+      const attemptElapsed = Date.now() - attemptStart;
+      const errName = err && err.name ? err.name : 'Unknown';
+      const errCode = err && err.code ? err.code : null;
+      emitTiming(path, attempt, 'attempt-failed', attemptElapsed, {
+        error_name: errName,
+        error_code: errCode,
       });
-    } catch (err2) {
-      const e = new Error(`xlsx-for-ai API unreachable: ${err2.message}`);
-      e.code = 'API_UNREACHABLE';
-      throw e;
+      // No sleep between retries — let the underlying socket pool refresh
+      // on the next fetch call. A sleep would just lengthen the total
+      // wait and the SPM-evidenced symptom is already a dial stall that
+      // a fresh socket fixes.
     }
   }
 
+  if (!res) {
+    const totalElapsed = Date.now() - requestStart;
+    emitTiming(path, MAX_ATTEMPTS, 'all-attempts-failed', totalElapsed);
+    const e = new Error(`xlsx-for-ai API unreachable: ${lastErr ? lastErr.message : 'unknown'}`);
+    e.code = 'API_UNREACHABLE';
+    throw e;
+  }
+
   if (!res.ok) {
     let payload;
     try { payload = await res.json(); } catch (_) { payload = null; }
-    const msg = payload?.error || payload?.message || res.statusText;
+    // Prefer the structured `{code, message}` shape our server emits; the
+    // top-level `error` / `message` fall-back keeps the older surfaces
+    // working. `payload.error` could be an OBJECT — coerce to .message
+    // first to avoid stringifying [object Object].
+    const errField = payload?.error;
+    const msg = (errField && typeof errField === 'object' ? errField.message : errField)
+      || payload?.message
+      || res.statusText;
+    const totalElapsed = Date.now() - requestStart;
+    emitTiming(path, winningAttempt, 'http-error', totalElapsed, { status: res.status });
     const e = new Error(`xlsx-for-ai API error ${res.status}: ${msg}`);
     e.status = res.status;
     e.payload = payload;
@@ -82,7 +155,10 @@ async function post(path, body, opts = {}) {
     throw e;
   }
 
-  return res.json();
+  const json = await res.json();
+  const totalElapsed = Date.now() - requestStart;
+  emitTiming(path, winningAttempt, 'body-complete', totalElapsed);
+  return json;
 }
 
 async function callTool(toolName, body) {

package/mcp.js

@@ -20,6 +20,7 @@ const { resolveCatalog }   = require('./lib/discover');
 const { applyAnnotations, sanitizeForMcp } = require('./lib/annotations');
 const fs                   = require('fs');
 const fsPromises           = require('fs/promises');
+const os                   = require('os');
 const path                 = require('path');
 
 // ---------------------------------------------------------------------------
@@ -1193,8 +1194,19 @@ function getMaxFileMB() {
   return parsed;
 }
 
+// Expand a leading `~` to the user's home dir so tilde-prefixed paths the
+// model passes ("~/Desktop/foo.xlsx") don't dead-end with ENOENT. SPM P1
+// 2026-06-06 "secondary" finding — a cheap friction-reducer.
+// Only the leading character; we don't try to resolve `~user/foo` patterns.
+function expandTilde(p) {
+  if (typeof p !== 'string' || p.length === 0) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
 function fileToB64(filePath) {
-  const resolved = path.resolve(filePath);
+  const resolved = path.resolve(expandTilde(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

package/package.json

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