xlsx-for-ai 3.0.6 → 3.0.9

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');
 
 // ---------------------------------------------------------------------------
@@ -109,24 +110,95 @@ const TOOLS = [
   {
     name: 'xlsx_write',
     description:
-      'create or update a LOCAL .xlsx file from a structured spec.\n' +
-      'DEFAULT creates a new workbook from spec. Pass base_file_b64 to edit-in-place instead. Workbook bytes return in _meta.file_b64 (base64) — NOT in content[0].text.\n\n' +
-      'ALWAYS pass out_path when the user wants the written file saved to disk.\n' +
-      'WITHOUT out_path: workbook bytes return in _meta.file_b64 (base64) — caller must save them.\n' +
-      'The response text confirms whether a save happened — trust the response, do not infer.\n\n' +
-      'USE WHEN: the user wants to write or edit a spreadsheet at a LOCAL file path. ' +
-      'Supports multi-sheet workbooks, formulas, named ranges, and table definitions. ' +
-      'Server-validated before writing — safer than generating xlsx bytes directly.\n\n' +
-      'DO NOT USE WHEN: working in a sandbox without local filesystem write access. ' +
-      'Or when the user wants to edit an uploaded file in place (there is no local path to write to).',
+      'create or update a LOCAL .xlsx file from a structured spec.\n\n' +
+      'Spec shape: `{sheets: [{name, cells: [{address, value | formula}]}]}`. Each cell has an A1 address ("A1", "B2") and EITHER `value` (string|number|boolean|null) OR `formula` (string, no leading "="). Minimal example:\n' +
+      '`{"sheets":[{"name":"Sheet1","cells":[{"address":"A1","value":"id"},{"address":"A2","value":1},{"address":"B2","formula":"A2*2"}]}]}`\n\n' +
+      'ALWAYS pass out_path to save to disk. Without out_path the workbook bytes return in _meta.file_b64.\n\n' +
+      'USE WHEN: the user wants to write or edit a spreadsheet at a LOCAL file path. Server-validated before writing — safer than generating xlsx bytes directly.\n\n' +
+      'DO NOT USE WHEN: working in a sandbox without local filesystem write access. Or editing an uploaded file in place (there is no local path to write to).',
     inputSchema: {
       type: 'object',
       properties: {
-        spec:      { type: 'object', description: 'Workbook spec object.' },
-        spec_path: { type: 'string', description: 'Path to a JSON spec file (alternative to inline spec).' },
-        out_path:  { type: 'string', description: 'Destination .xlsx path.' },
+        spec: {
+          type: 'object',
+          description:
+            'Workbook spec. Shape: {sheets: [{name: string, cells: [{address, value | formula}]}]}. ' +
+            'Each cell has an A1-style `address` (regex ^[A-Za-z]+\\d+$) and EXACTLY ONE of `value` ' +
+            '(string|number|boolean|null) or `formula` (string WITHOUT leading "=" — e.g. "SUM(A1:A10)" not "=SUM(A1:A10)"). ' +
+            'Example: {"sheets":[{"name":"Sheet1","cells":[{"address":"A1","value":"id"},{"address":"A2","value":1},{"address":"B2","formula":"A2*2"}]}]}',
+          properties: {
+            sheets: {
+              type: 'array',
+              minItems: 1,
+              description: 'One or more sheets. Each sheet is { name: string, cells: array }.',
+              items: {
+                type: 'object',
+                required: ['name', 'cells'],
+                properties: {
+                  name: {
+                    type: 'string',
+                    minLength: 1,
+                    description: 'Sheet name (non-empty).',
+                  },
+                  cells: {
+                    type: 'array',
+                    description: 'List of cells to write. Order does not matter; addresses are absolute.',
+                    items: {
+                      type: 'object',
+                      required: ['address'],
+                      description: 'Cell entry. Provide EXACTLY ONE of `value` or `formula`.',
+                      properties: {
+                        address: {
+                          type: 'string',
+                          pattern: '^[A-Za-z]+\\d+$',
+                          description: 'A1-style cell address — e.g. "A1", "B2", "AA10".',
+                        },
+                        value: {
+                          type: ['string', 'number', 'boolean', 'null'],
+                          description: 'Cell value: string, number, boolean, or null. Mutually exclusive with `formula`.',
+                        },
+                        formula: {
+                          type: 'string',
+                          // No leading `=` — the server expects bare expressions.
+                          // `^(?!=)` is a negative lookahead that rejects an `=`
+                          // as the first character; ECMA-262 supported.
+                          pattern: '^(?!=).+',
+                          description: 'Excel formula, WITHOUT leading "=". E.g. "SUM(A1:A10)" not "=SUM(A1:A10)". Mutually exclusive with `value`.',
+                        },
+                      },
+                      // Enforce the value-XOR-formula rule at the schema layer
+                      // so a strict client (or future server) rejects malformed
+                      // cells before the request fires. SPM 2026-06-06
+                      // wild-adoption follow-up.
+                      oneOf: [
+                        { required: ['value'], not: { required: ['formula'] } },
+                        { required: ['formula'], not: { required: ['value'] } },
+                      ],
+                    },
+                  },
+                },
+              },
+            },
+          },
+          required: ['sheets'],
+        },
+        spec_path: {
+          type: 'string',
+          description: 'Path to a .json file carrying the spec (alternative to inline spec for large workbooks).',
+        },
+        out_path: {
+          type: 'string',
+          description: 'Destination .xlsx path. Required when the caller wants the file saved to disk.',
+        },
+        base_file_b64: {
+          type: 'string',
+          description: 'Optional base64 of an existing .xlsx to edit-in-place. When omitted, a fresh workbook is created.',
+        },
       },
-      required: ['out_path'],
+      // out_path is the typical caller's choice but not strictly required —
+      // when omitted, the workbook bytes return in _meta.file_b64 and the
+      // caller saves them (or feeds them to another tool). spec / spec_path
+      // is the only hard requirement.
     },
   },
   {
@@ -1193,8 +1265,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
@@ -1343,7 +1426,63 @@ async function applyFileB64(result, outPath) {
 // reveal at the boundary.
 // ---------------------------------------------------------------------------
 
-function friendlyErrorMessage(toolName, code) {
+// Defense in depth on the 4xx inline message. The SPEC's bet is that
+// 4xx server messages describe the CALLER'S OWN INPUT (which field,
+// what was expected) — but a wrapped 4xx path could still carry
+// absolute file paths, emails, JWTs / Bearer tokens, Slack tokens,
+// or other PII. Scrub those before surfacing, replace with `<…>`
+// placeholders so the caller still sees the SHAPE of the message
+// without the sensitive payload.
+//
+// `<…>` was picked over a more verbose `[redacted-x]` so it's
+// visually compact and unambiguously not real input.
+const PII_SCRUBBERS = [
+  // Bearer / Authorization tokens — match before generic JWT pattern.
+  [/\bBearer\s+[A-Za-z0-9._~+/-]{8,}=*/g, '<bearer>'],
+  // JSON Web Tokens. Three dot-separated base64url segments, the first
+  // starting with `eyJ` (the canonical JWT header prefix).
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, '<jwt>'],
+  // Slack bot / user / app tokens.
+  [/\bxox[bpoars]-[A-Za-z0-9-]{10,}\b/g, '<slack-token>'],
+  // Our own API keys.
+  [/\bxfa_[a-z]+_[A-Za-z0-9]{16,}\b/g, '<xfa-key>'],
+  // Generic 32+ char hex (api keys / hashes).
+  [/\b[a-f0-9]{32,}\b/gi, '<hex>'],
+  // Emails.
+  [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, '<email>'],
+  // POSIX absolute paths under /Users, /home, /var, /opt, /tmp, /etc, /private.
+  [/\/(?:Users|home|var|opt|tmp|etc|private)\/[^\s'"`)\]]+/g, '<path>'],
+  // Windows absolute paths.
+  [/[A-Za-z]:\\[^\s'"`)\]]+/g, '<path>'],
+];
+
+// Strip the well-known low-signal noise an inline 4xx surface message
+// could carry: leading "xlsx-for-ai API error 4xx: " prefix from
+// lib/client.js, scrub PII via PII_SCRUBBERS, bound the length so a
+// pathological payload can't blow up the conversation log.
+const INLINE_4XX_MAX_LEN = 280;
+function shapeInline4xxMessage(raw) {
+  if (typeof raw !== 'string') return '';
+  let s = raw.replace(/^xlsx-for-ai API error \d+:\s*/i, '').trim();
+  for (const [pattern, replacement] of PII_SCRUBBERS) {
+    s = s.replace(pattern, replacement);
+  }
+  if (s.length > INLINE_4XX_MAX_LEN) {
+    s = s.slice(0, INLINE_4XX_MAX_LEN - 1) + '…';
+  }
+  return s;
+}
+
+function friendlyErrorMessage(toolName, err) {
+  // err may be undefined (defensive) or any thrown value. Extract the
+  // fields we care about safely.
+  const code = err && err.code;
+  const status = err && err.status;
+  const payload = err && err.payload;
+
+  // Known client-side / mcp.js error codes — keep their pre-existing
+  // short text. Ordered before the 4xx default so the specific message
+  // wins.
   switch (code) {
     case 'DISALLOWED_EXTENSION':
       return `${toolName}: file path must point at a workbook (allowed: .xlsx/.xls/.xlsm/.xlsb/.csv/.ods/.fods/.numbers/.tsv).`;
@@ -1359,8 +1498,6 @@ function friendlyErrorMessage(toolName, code) {
       return `${toolName}: required token env var is not set (see tool docs for which one).`;
     case 'API_UNREACHABLE':
       return `${toolName}: API is unreachable — check network connectivity.`;
-    case 'API_SERVER_ERROR':
-      return `${toolName}: API returned a server error — retry shortly.`;
     case 'TIER_UPGRADE_REQUIRED':
       return `${toolName}: this capability requires a paid tier.`;
     case 'RATE_LIMITED':
@@ -1368,8 +1505,57 @@ function friendlyErrorMessage(toolName, code) {
     case 'FALLBACK_ENGINE_MISSING':
       return `${toolName}: local fallback engine not installed (\`npm install @protobi/exceljs\`).`;
     default:
-      return `${toolName} failed — see server-side logs (request_id in response _meta) for details.`;
+      break;
+  }
+
+  // 4xx client-error class: surface the server's validation message
+  // inline. SPM 2026-06-06 wild-adoption SPEC. The 4xx surface
+  // describes the CALLER'S OWN INPUT shape ("spec.sheets must be an
+  // array", "cells[3].address is not a valid Excel address"); the
+  // caller needs that message to fix their call. 5xx stays generic
+  // (it can carry upstream internals).
+  //
+  // Known specific HTTP statuses are mapped first so they keep their
+  // short curated text:
+  if (code === 'API_CLIENT_ERROR') {
+    if (status === 429) {
+      return `${toolName}: free-tier monthly cap reached — see xlsx-for-ai.dev/pricing.`;
+    }
+    if (status === 402) {
+      return `${toolName}: this capability requires a paid tier.`;
+    }
+    // Generic 4xx: surface the server message. Prefer the structured
+    // shape, fall through to the flat message, fall through to the
+    // wrapped err.message (stripped of the "API error 4xx:" prefix).
+    let inline = '';
+    if (payload && typeof payload === 'object') {
+      const structured = payload.error;
+      if (structured && typeof structured === 'object' && typeof structured.message === 'string') {
+        inline = structured.message;
+      } else if (typeof payload.message === 'string') {
+        inline = payload.message;
+      } else if (typeof payload.error === 'string') {
+        inline = payload.error;
+      }
+    }
+    if (!inline && err && typeof err.message === 'string') {
+      inline = err.message;
+    }
+    const shaped = shapeInline4xxMessage(inline);
+    if (shaped) {
+      return `${toolName}: ${shaped}`;
+    }
+    // Graceful fallback when no message is available (empty/absent
+    // payload, non-string fields): generic with tool name, no
+    // `undefined`, no `[object Object]`.
+    return `${toolName}: invalid request (no detail provided).`;
+  }
+
+  // 5xx and everything else — stay generic. Security boundary preserved.
+  if (code === 'API_SERVER_ERROR') {
+    return `${toolName}: API returned a server error — retry shortly.`;
   }
+  return `${toolName} failed — see server-side logs (request_id in response _meta) for details.`;
 }
 
 // ---------------------------------------------------------------------------
@@ -1861,8 +2047,7 @@ async function main() {
       // generic "tool failed" with the tool name so callers can still
       // route on it without leaking path/server detail. Pre-Friday-
       // external CRITICAL per the Tier-1 audit.
-      const code = err && err.code;
-      const safeMessage = friendlyErrorMessage(name, code);
+      const safeMessage = friendlyErrorMessage(name, err);
       return {
         content: [{ type: 'text', text: `xlsx-for-ai error: ${safeMessage}` }],
         isError: true,
@@ -1969,4 +2154,4 @@ if (require.main === module) {
 // 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 };
+module.exports = { applyFileB64, dispatchTool, TOOLS, friendlyErrorMessage };

package/package.json

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