apple-numbers-mcp 0.6.1 → 1.0.0

package/README.md

@@ -3,8 +3,12 @@
 A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude to read, write, search, and modify Apple Numbers (`.numbers`) spreadsheet files. Backed by the [numbers-parser](https://pypi.org/project/numbers-parser/) Python library.
 
 [![npm version](https://img.shields.io/npm/v/apple-numbers-mcp)](https://www.npmjs.com/package/apple-numbers-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/apple-numbers-mcp)](https://www.npmjs.com/package/apple-numbers-mcp)
+[![node](https://img.shields.io/node/v/apple-numbers-mcp)](https://www.npmjs.com/package/apple-numbers-mcp)
 [![CI](https://github.com/sweetrb/apple-numbers-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sweetrb/apple-numbers-mcp/actions/workflows/ci.yml)
+[![platform: macOS](https://img.shields.io/badge/platform-macOS-111?logo=apple&logoColor=white)](https://www.apple.com/macos/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
 
 <p align="center">
   <img src="codex/assets/screenshot.png" alt="Apple Numbers MCP — read, write, search, and format spreadsheets from Codex, Claude, and other AI assistants" width="680">
@@ -124,7 +128,7 @@ The entrypoint is written as:
 
 - **macOS or Linux** — `numbers-parser` reads the file format directly, so most tools work anywhere. **Formatting and formula tools require macOS with Numbers.app.**
 - **Node.js 20+** — Required for the MCP server
-- **Python 3.9+ with numbers-parser** — Install via `pip3 install numbers-parser` or via `npm run setup` if installing from source
+- **Python 3.11+** — the `numbers-parser` library installs automatically into a project-local venv on first use (or pre-warm with `npm run setup`). numbers-parser requires Python ≥ 3.10; macOS ships 3.9, so install a newer Python first (e.g. `brew install python@3.12`).
 - **Automation permission (writes only)** — Reads and exports need no special permission, but write/format tools drive Numbers.app via AppleScript and require the host app to have Automation permission for Numbers, granted on first use. See the [Automation Permission guide](docs/AUTOMATION-PERMISSION.md). Run the **`doctor`** tool to verify your setup.
 
 ## Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-numbers-mcp",
-  "version": "0.6.1",
+  "version": "1.0.0",
   "description": "MCP server for Apple Numbers - read, write, search, and format .numbers spreadsheets via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",
@@ -66,7 +66,7 @@
     "darwin"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.4.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.22.4"
   },
   "devDependencies": {

package/requirements.txt

@@ -1 +1 @@
-numbers-parser>=4.0.0
+numbers-parser>=4.0.0,<5.0

package/scripts/setup.sh

@@ -13,7 +13,7 @@ echo "==> Setting up Python venv in $VENV_DIR"
 
 # Find python3
 PYTHON=""
-for cmd in python3 python; do
+for cmd in python3.14 python3.13 python3.12 python3.11 python3 python; do
   if command -v "$cmd" &>/dev/null; then
     PYTHON="$cmd"
     break
@@ -27,6 +27,16 @@ fi
 
 echo "    Using: $PYTHON ($($PYTHON --version))"
 
+# Require Python >= 3.11 (numbers-parser needs >=3.10; full ISO-8601 date
+# parsing in the date filters needs 3.11). macOS ships 3.9 — fail early.
+if ! "$PYTHON" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)'; then
+  echo "ERROR: Python >= 3.11 required, but '$PYTHON' is $($PYTHON --version 2>&1)." >&2
+  echo "       macOS ships Python 3.9. Install a newer one, e.g.:" >&2
+  echo "         brew install python@3.12     # then re-run: npm run setup" >&2
+  echo "       or from https://www.python.org/downloads/" >&2
+  exit 1
+fi
+
 # Create venv if it doesn't exist
 if [ ! -d "$VENV_DIR" ]; then
   echo "==> Creating virtual environment..."

package/src/utils/numbers_reader.py

@@ -7,17 +7,42 @@ Called by the TypeScript MCP server via child_process.
 import sys
 import json
 import argparse
+import os
 from pathlib import Path
 
 try:
     from numbers_parser import Document
 except ImportError:
     print(json.dumps({
-        "error": "numbers-parser not installed. Run: pip3 install numbers-parser"
+        "error": "numbers-parser not installed. Run: npm run setup"
     }))
     sys.exit(1)
 
 
+def _atomic_save(doc, path):
+    """Save a .numbers document atomically.
+
+    numbers-parser's Document.save() rewrites the entire .numbers archive; an
+    interrupted or failed save in place can leave the user's only copy
+    truncated or corrupt (and several mutations, e.g. delete-rows, are not
+    undoable). Because a .numbers file is a single zip archive, we write to a
+    sibling temp file and os.replace() it onto the target — atomic on the same
+    filesystem — so on any failure the original file is left untouched.
+    """
+    target = Path(path)
+    tmp = target.parent / f".{target.stem}.tmp-{os.getpid()}.numbers"
+    try:
+        doc.save(str(tmp))
+        os.replace(str(tmp), str(target))
+    except BaseException:
+        try:
+            if tmp.exists():
+                tmp.unlink()
+        except OSError:
+            pass
+        raise
+
+
 def cell_to_serializable(cell):
     """Convert a numbers-parser cell to a JSON-serializable dict."""
     val = cell.value
@@ -307,7 +332,7 @@ def cmd_create(args):
                 table.write(row_idx, col_idx, coerced)
         rows_written += 1
 
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -327,7 +352,7 @@ def cmd_set_cell(args):
     value = _coerce_value(json.loads(args.value), args.type)
     if value is not None:
         table.write(row, col, value)
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -352,7 +377,7 @@ def cmd_set_cells(args):
         if value is not None:
             table.write(row, col, value)
         cells_written += 1
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -379,7 +404,7 @@ def cmd_add_rows(args):
         # Ensure empty rows still expand the table
         if not has_value:
             table.write(start_row + row_offset, 0, "")
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -406,7 +431,7 @@ def cmd_delete_rows(args):
     # delete_row(num_rows, start_row) deletes num_rows starting at start_row
     table.delete_row(num_to_delete, start_row)
     rows_deleted = num_to_delete
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -432,7 +457,7 @@ def cmd_add_sheet(args):
         for col_idx, header in enumerate(headers):
             if header is not None:
                 table.write(0, col_idx, str(header))
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -457,7 +482,7 @@ def cmd_add_table(args):
         for col_idx, header in enumerate(headers):
             if header is not None:
                 table.write(0, col_idx, str(header))
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -522,7 +547,7 @@ def cmd_import(args):
             if coerced is not None:
                 table.write(row_idx, col_idx, coerced)
 
-    doc.save(args.output)
+    _atomic_save(doc, args.output)
     result = {
         "path": str(Path(args.output).resolve()),
         "inputPath": str(input_path.resolve()),
@@ -569,7 +594,7 @@ def cmd_update_rows(args):
             if coerced is not None:
                 table.write(row_idx, col_idx, coerced)
         rows_updated += 1
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,
@@ -585,7 +610,7 @@ def cmd_rename_sheet(args):
     sheet = _find_sheet(doc, args.sheet)
     old_name = sheet.name
     sheet.name = args.new_name
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "oldName": old_name,
@@ -601,7 +626,7 @@ def cmd_rename_table(args):
     table = _find_table(sheet, args.table)
     old_name = table.name
     table.name = args.new_name
-    doc.save(args.file)
+    _atomic_save(doc, args.file)
     result = {
         "path": str(Path(args.file).resolve()),
         "sheetName": sheet.name,