apple-numbers-mcp 0.5.0

package/build/utils/applescript.js

@@ -0,0 +1,248 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Output cap for osascript. Node's execFileSync defaults to ~1 MB, which a large
+ * table read (getCellStyle round-trips, big batch operations) can blow past —
+ * execFileSync then throws ENOBUFS and the failure surfaces with no useful detail.
+ * 64 MB headroom, overridable via APPLE_NUMBERS_MCP_MAX_BUFFER.
+ */
+const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+function getMaxBuffer() {
+    const raw = process.env.APPLE_NUMBERS_MCP_MAX_BUFFER;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_MAX_BUFFER_BYTES;
+}
+/**
+ * Headroom (ms) between the in-AppleScript `with timeout` and the outer osascript
+ * process timeout. The script-level timeout should fire first so Numbers.app
+ * aborts from inside its own AppleScript dispatch before Node SIGKILLs osascript.
+ * Killing osascript alone does not stop work already dispatched into Numbers.app,
+ * which is what wedges it for subsequent calls.
+ */
+const SCRIPT_TIMEOUT_HEADROOM_MS = 5000;
+/**
+ * Wrap a full `tell application "Numbers" ... end tell` script in an AppleScript
+ * `with timeout` block so an Apple Event that honors timeouts aborts cleanly
+ * rather than holding Numbers.app's single-threaded dispatch open. The seconds
+ * value is set below the process timeout so the in-app abort wins the race
+ * against the outer SIGKILL.
+ */
+function wrapWithTimeout(script, processTimeoutMs) {
+    const seconds = Math.max(1, Math.ceil((processTimeoutMs - SCRIPT_TIMEOUT_HEADROOM_MS) / 1000));
+    return `with timeout of ${seconds} seconds\n${script}\nend timeout`;
+}
+/**
+ * Convert 0-based row/col indices to A1 notation (e.g., 0,0 → "A1", 2,3 → "D3").
+ */
+export function toA1(row, col) {
+    let letters = "";
+    let c = col;
+    while (true) {
+        letters = String.fromCharCode(65 + (c % 26)) + letters;
+        c = Math.floor(c / 26) - 1;
+        if (c < 0)
+            break;
+    }
+    return `${letters}${row + 1}`;
+}
+/**
+ * Run an AppleScript string via osascript and return stdout.
+ */
+export function runAppleScript(script, timeoutMs = 60000) {
+    try {
+        return execFileSync("osascript", ["-e", wrapWithTimeout(script, timeoutMs)], {
+            encoding: "utf-8",
+            timeout: timeoutMs,
+            // SIGKILL (not the default SIGTERM): a wedged osascript blocked on an
+            // unresponsive Numbers.app can ignore SIGTERM and leak. SIGKILL guarantees
+            // the process is reaped on timeout.
+            killSignal: "SIGKILL",
+            // Raise the output cap above Node's ~1 MB default so large reads aren't
+            // truncated into an ENOBUFS failure.
+            maxBuffer: getMaxBuffer(),
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+    }
+    catch (err) {
+        // osascript writes its real diagnostic to stderr; Node's default error
+        // message ("Command failed: osascript ...") buries it. Surface stderr so the
+        // thrown Error carries the actual AppleScript error.
+        const error = err;
+        const stderr = error.stderr?.toString().trim();
+        if (stderr) {
+            error.message = `${error.message}\n${stderr}`;
+        }
+        throw error;
+    }
+}
+/**
+ * Escape a string for use inside AppleScript double quotes.
+ */
+function escapeAS(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * Generate the AppleScript preamble that opens a document (or finds it if already open)
+ * and navigates to a sheet/table. The caller provides the body commands.
+ */
+function buildScript(filePath, sheet, table, body, returnExpr = '"done"') {
+    return `
+tell application "Numbers"
+  set docFound to false
+  repeat with d in documents
+    set dPath to POSIX path of (file of d as text)
+    if dPath is "${escapeAS(filePath)}" then
+      set docFound to true
+      set targetDoc to d
+      exit repeat
+    end if
+  end repeat
+  if not docFound then
+    set targetDoc to open POSIX file "${escapeAS(filePath)}"
+    delay 1
+  end if
+  tell targetDoc
+    tell sheet "${escapeAS(sheet)}"
+      tell table "${escapeAS(table)}"
+${body}
+      end tell
+    end tell
+    save
+  end tell
+  return ${returnExpr}
+end tell`;
+}
+export function setFormula(filePath, sheet, table, row, col, formula) {
+    const cellRef = toA1(row, col);
+    const body = `        set the value of cell "${cellRef}" to "${escapeAS(formula)}"
+        delay 0.3
+        set computedVal to the value of cell "${cellRef}"`;
+    const computedValue = runAppleScript(buildScript(filePath, sheet, table, body, "(computedVal as text)"));
+    return {
+        path: filePath,
+        sheetName: sheet,
+        tableName: table,
+        cell: cellRef,
+        formula,
+        computedValue,
+    };
+}
+export function setFormulasBatch(filePath, sheet, table, formulas) {
+    const cmds = formulas
+        .map((f) => `        set the value of cell "${toA1(f.row, f.col)}" to "${escapeAS(f.formula)}"`)
+        .join("\n");
+    runAppleScript(buildScript(filePath, sheet, table, cmds));
+    return { path: filePath, sheetName: sheet, tableName: table, cellsSet: formulas.length };
+}
+function colorToAS(c) {
+    return `{${c.red}, ${c.green}, ${c.blue}}`;
+}
+function buildStyleCommands(cellRef, style) {
+    const cmds = [];
+    const c = `cell "${cellRef}"`;
+    if (style.fontName !== undefined)
+        cmds.push(`        set font name of ${c} to "${escapeAS(style.fontName)}"`);
+    if (style.fontSize !== undefined)
+        cmds.push(`        set font size of ${c} to ${style.fontSize}`);
+    if (style.textColor !== undefined)
+        cmds.push(`        set text color of ${c} to ${colorToAS(style.textColor)}`);
+    if (style.backgroundColor !== undefined)
+        cmds.push(`        set background color of ${c} to ${colorToAS(style.backgroundColor)}`);
+    if (style.format !== undefined)
+        cmds.push(`        set format of ${c} to ${style.format}`);
+    if (style.alignment !== undefined)
+        cmds.push(`        set alignment of ${c} to ${style.alignment}`);
+    if (style.verticalAlignment !== undefined)
+        cmds.push(`        set vertical alignment of ${c} to ${style.verticalAlignment}`);
+    if (style.textWrap !== undefined)
+        cmds.push(`        set text wrap of ${c} to ${style.textWrap}`);
+    return cmds;
+}
+export function setCellStyle(filePath, sheet, table, row, col, style) {
+    const cellRef = toA1(row, col);
+    const cmds = buildStyleCommands(cellRef, style);
+    if (cmds.length === 0)
+        return { path: filePath, sheetName: sheet, tableName: table, cell: cellRef };
+    runAppleScript(buildScript(filePath, sheet, table, cmds.join("\n")));
+    return { path: filePath, sheetName: sheet, tableName: table, cell: cellRef };
+}
+export function setCellsStyleBatch(filePath, sheet, table, entries) {
+    const allCmds = [];
+    for (const entry of entries) {
+        const cellRef = toA1(entry.row, entry.col);
+        allCmds.push(...buildStyleCommands(cellRef, entry.style));
+    }
+    if (allCmds.length > 0) {
+        runAppleScript(buildScript(filePath, sheet, table, allCmds.join("\n")));
+    }
+    return { path: filePath, sheetName: sheet, tableName: table, cellsStyled: entries.length };
+}
+export function setColumnWidth(filePath, sheet, table, col, width) {
+    // Column letters for AppleScript
+    const colLetter = toA1(0, col).replace("1", "");
+    const body = `        set width of column "${colLetter}" to ${width}`;
+    runAppleScript(buildScript(filePath, sheet, table, body));
+    return { path: filePath, sheetName: sheet, tableName: table };
+}
+export function setRowHeight(filePath, sheet, table, row, height) {
+    // AppleScript rows are 1-based
+    const body = `        set height of row ${row + 1} to ${height}`;
+    runAppleScript(buildScript(filePath, sheet, table, body));
+    return { path: filePath, sheetName: sheet, tableName: table };
+}
+export function mergeCells(filePath, sheet, table, startRow, startCol, endRow, endCol) {
+    const rangeStr = `${toA1(startRow, startCol)}:${toA1(endRow, endCol)}`;
+    const body = `        merge range "${rangeStr}"`;
+    runAppleScript(buildScript(filePath, sheet, table, body));
+    return { path: filePath, sheetName: sheet, tableName: table, range: rangeStr };
+}
+export function unmergeCells(filePath, sheet, table, startRow, startCol, endRow, endCol) {
+    const rangeStr = `${toA1(startRow, startCol)}:${toA1(endRow, endCol)}`;
+    const body = `        unmerge range "${rangeStr}"`;
+    runAppleScript(buildScript(filePath, sheet, table, body));
+    return { path: filePath, sheetName: sheet, tableName: table, range: rangeStr };
+}
+export function getCellStyle(filePath, sheet, table, row, col) {
+    const cellRef = toA1(row, col);
+    const body = `        set c to cell "${cellRef}"
+        set fn to font name of c
+        if fn is missing value then set fn to ""
+        set fs to font size of c
+        set tc to text color of c
+        if tc is missing value then
+          set tcStr to "0,0,0"
+        else
+          set tcStr to (item 1 of tc) & "," & (item 2 of tc) & "," & (item 3 of tc)
+        end if
+        set bg to background color of c
+        if bg is missing value then
+          set bgStr to "65535,65535,65535"
+        else
+          set bgStr to (item 1 of bg) & "," & (item 2 of bg) & "," & (item 3 of bg)
+        end if
+        set fmt to format of c
+        set al to alignment of c
+        set va to vertical alignment of c
+        set tw to text wrap of c`;
+    const returnExpr = `fn & "|" & fs & "|" & tcStr & "|" & bgStr & "|" & fmt & "|" & al & "|" & va & "|" & tw`;
+    const raw = runAppleScript(buildScript(filePath, sheet, table, body, returnExpr));
+    const parts = raw.split("|");
+    const parseColor = (s) => {
+        const [r, g, b] = s.split(",").map(Number);
+        return { red: r, green: g, blue: b };
+    };
+    return {
+        fontName: parts[0],
+        fontSize: parseFloat(parts[1]),
+        textColor: parseColor(parts[2]),
+        backgroundColor: parseColor(parts[3]),
+        format: parts[4],
+        alignment: parts[5],
+        verticalAlignment: parts[6],
+        textWrap: parts[7] === "true",
+    };
+}
+//# sourceMappingURL=applescript.js.map

package/build/utils/applescript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applescript.js","sourceRoot":"","sources":["../../src/utils/applescript.ts"],"names":[],"mappings":"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"}

package/build/utils/python.d.ts

@@ -0,0 +1,12 @@
+export interface PythonResult<T = unknown> {
+    data?: T;
+    error?: string;
+}
+/** Reset the cached Python path (useful for testing). */
+export declare function _resetPythonCache(): void;
+export declare function runNumbersReader<T = unknown>(command: string, args: string[], timeoutMs?: number): PythonResult<T>;
+export declare function checkDependencies(): {
+    ok: boolean;
+    message: string;
+};
+//# sourceMappingURL=python.d.ts.map

package/build/utils/python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.d.ts","sourceRoot":"","sources":["../../src/utils/python.ts"],"names":[],"mappings":"AA+CA,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,yDAAyD;AACzD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAcD,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,SAAQ,GAChB,YAAY,CAAC,CAAC,CAAC,CAiCjB;AAED,wBAAgB,iBAAiB,IAAI;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAcpE"}

package/build/utils/python.js

@@ -0,0 +1,101 @@
+import { execSync, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function getProjectRoot() {
+    // Walk up from build/utils/ or src/utils/ to project root
+    return join(__dirname, "..", "..");
+}
+// Resolve path to the Python helper script
+function getScriptPath() {
+    return join(getProjectRoot(), "src", "utils", "numbers_reader.py");
+}
+/**
+ * Find the best Python executable. Preference order:
+ *   1. Project-local venv (./venv/bin/python3)
+ *   2. System python3
+ *   3. System python
+ */
+function findPython() {
+    const projectRoot = getProjectRoot();
+    const venvPython = join(projectRoot, "venv", "bin", "python3");
+    // Prefer the project venv — it has numbers-parser installed
+    if (existsSync(venvPython)) {
+        return venvPython;
+    }
+    // Fall back to system Python
+    for (const cmd of ["python3", "python"]) {
+        try {
+            execSync(`${cmd} --version`, { stdio: "pipe" });
+            return cmd;
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error('Python 3 not found. Run "npm run setup" to create a venv, or ensure python3 is on PATH.');
+}
+let cachedPython = null;
+/** Reset the cached Python path (useful for testing). */
+export function _resetPythonCache() {
+    cachedPython = null;
+}
+const DEFAULT_MAX_BUFFER_BYTES = 50 * 1024 * 1024; // 50MB for large spreadsheets
+/** Max stdout bytes from the Python sidecar, overridable via env for huge files. */
+function getMaxBuffer() {
+    const raw = process.env.APPLE_NUMBERS_MCP_MAX_BUFFER;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_MAX_BUFFER_BYTES;
+}
+export function runNumbersReader(command, args, timeoutMs = 30000) {
+    const python = cachedPython ?? (cachedPython = findPython());
+    const scriptPath = getScriptPath();
+    const fullArgs = [scriptPath, command, ...args];
+    const debug = process.env.DEBUG || process.env.VERBOSE;
+    if (debug) {
+        console.error(`[numbers-mcp] ${python} ${fullArgs.join(" ")}`);
+    }
+    try {
+        const stdout = execFileSync(python, fullArgs, {
+            encoding: "utf-8",
+            timeout: timeoutMs,
+            maxBuffer: getMaxBuffer(),
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const result = JSON.parse(stdout.trim());
+        if (result.error) {
+            return { error: result.error };
+        }
+        return { data: result };
+    }
+    catch (err) {
+        const error = err;
+        if (error.stderr?.includes("numbers-parser not installed")) {
+            return { error: "numbers-parser not installed. Run: npm run setup" };
+        }
+        if (error.message?.includes("ETIMEDOUT") || error.message?.includes("timed out")) {
+            return { error: `Operation timed out after ${timeoutMs}ms. File may be very large.` };
+        }
+        return { error: error.message || "Unknown error executing Python script" };
+    }
+}
+export function checkDependencies() {
+    try {
+        const python = cachedPython ?? (cachedPython = findPython());
+        const version = execSync(`${python} -c "import numbers_parser; print(numbers_parser.__version__)"`, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        return { ok: true, message: `All dependencies available (numbers-parser ${version})` };
+    }
+    catch {
+        return {
+            ok: false,
+            message: "numbers-parser not installed. Run: npm run setup",
+        };
+    }
+}
+//# sourceMappingURL=python.js.map

package/build/utils/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../../src/utils/python.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "apple-numbers-mcp",
+  "version": "0.5.0",
+  "description": "MCP server for reading and writing Apple Numbers (.numbers) spreadsheet files",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "bin": {
+    "apple-numbers-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "src/utils/numbers_reader.py",
+    "scripts/setup.sh",
+    "requirements.txt",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "setup": "bash scripts/setup.sh",
+    "build": "tsc && tsc-alias",
+    "start": "node build/index.js",
+    "dev": "tsc --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:all": "vitest run && vitest run --config vitest.integration.config.ts",
+    "test:watch": "vitest",
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json",
+    "prepublishOnly": "npm run lint && npm run test && npm run build",
+    "prepare": "husky; npm run build"
+  },
+  "volta": {
+    "node": "22.13.1"
+  },
+  "keywords": [
+    "mcp",
+    "apple-numbers",
+    "claude",
+    "ai",
+    "spreadsheet",
+    "macos",
+    "numbers-parser",
+    "model-context-protocol"
+  ],
+  "author": "Rob Sweet <rob@superiortech.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sweetrb/apple-numbers-mcp.git"
+  },
+  "homepage": "https://github.com/sweetrb/apple-numbers-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/sweetrb/apple-numbers-mcp/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.4.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "@vitest/coverage-v8": "^2.1.9",
+    "eslint": "^9.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.0.0",
+    "tsc-alias": "^1.8.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

package/requirements.txt

@@ -0,0 +1 @@
+numbers-parser>=4.0.0

package/scripts/setup.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+#
+# Create a Python venv and install numbers-parser.
+# Run via: npm run setup
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+VENV_DIR="$PROJECT_ROOT/venv"
+
+echo "==> Setting up Python venv in $VENV_DIR"
+
+# Find python3
+PYTHON=""
+for cmd in python3 python; do
+  if command -v "$cmd" &>/dev/null; then
+    PYTHON="$cmd"
+    break
+  fi
+done
+
+if [ -z "$PYTHON" ]; then
+  echo "ERROR: Python 3 not found. Install Python 3 first." >&2
+  exit 1
+fi
+
+echo "    Using: $PYTHON ($($PYTHON --version))"
+
+# Create venv if it doesn't exist
+if [ ! -d "$VENV_DIR" ]; then
+  echo "==> Creating virtual environment..."
+  "$PYTHON" -m venv "$VENV_DIR"
+else
+  echo "    Venv already exists, updating..."
+fi
+
+# Install dependencies
+echo "==> Installing numbers-parser..."
+"$VENV_DIR/bin/pip" install --upgrade pip -q
+"$VENV_DIR/bin/pip" install -r "$PROJECT_ROOT/requirements.txt" -q
+
+echo "==> Verifying installation..."
+"$VENV_DIR/bin/python3" -c "import numbers_parser; print(f'    numbers-parser {numbers_parser.__version__} installed')"
+
+echo "==> Done! Python venv ready."