apple-numbers-mcp 1.1.5 → 1.1.7

package/README.md

@@ -12,7 +12,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that e
 [![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">
+  <img src="https://raw.githubusercontent.com/sweetrb/apple-numbers-mcp/main/codex/assets/screenshot.png" alt="Apple Numbers MCP — read, write, search, and format spreadsheets from Codex, Claude, and other AI assistants" width="680">
 </p>
 
 ## What is This?
@@ -41,6 +41,12 @@ Install the sweetrb/apple-numbers-mcp MCP server so you can help me work with my
 
 Claude will handle the installation and configuration automatically. After install, you'll need to install `numbers-parser` (Python) — see [Requirements](#requirements) below.
 
+Or register it yourself in one deterministic line (no clone needed):
+
+```bash
+claude mcp add apple-numbers -s user -- npx -y apple-numbers-mcp
+```
+
 ### Using the Plugin Marketplace
 
 Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:
@@ -52,6 +58,8 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 This method also installs a **skill** that teaches Claude when and how to use Apple Numbers effectively.
 
+The plugin runs straight from its marketplace clone under `~/.claude/plugins/` (the clone lives at `~/.claude/plugins/marketplaces/apple-numbers-mcp/`). On the **first tool call** the server auto-bootstraps a project-local Python venv inside that directory with `numbers-parser` — a one-time setup that takes about a minute and **requires Python >= 3.11 on PATH** (stock macOS ships 3.9 — `brew install python@3.12` first). To pre-warm it instead of waiting on the first call, run `scripts/setup.sh` inside that install directory.
+
 ### Using the Codex Marketplace
 
 Install the same public marketplace in Codex:
@@ -71,14 +79,14 @@ numbers-parser`); see [Requirements](#requirements).
 
 Configuration for two more hosts is included — each registers the same `apple-numbers` MCP server (`npx -y apple-numbers-mcp`). All paths still need the `numbers-parser` Python sidecar available; see [Requirements](#requirements).
 
-- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-numbers --command npx --args -y apple-numbers-mcp`, or merge [`.hermes-plugin/config.yaml`](.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](.hermes-plugin/README.md).
-- **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
+- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with `hermes mcp add apple-numbers --command npx --args -y apple-numbers-mcp`, or merge [`.hermes-plugin/config.yaml`](https://github.com/sweetrb/apple-numbers-mcp/blob/main/.hermes-plugin/config.yaml) into `~/.hermes/config.yaml`. Details: [`.hermes-plugin/README.md`](https://github.com/sweetrb/apple-numbers-mcp/blob/main/.hermes-plugin/README.md).
+- **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](https://github.com/sweetrb/apple-numbers-mcp/blob/main/.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
 
 ### Manual Installation
 
-**1. Install the server:**
+**1. Install the server** (from the npm registry):
 ```bash
-npm install -g github:sweetrb/apple-numbers-mcp
+npm install -g apple-numbers-mcp
 ```
 
 **2. Install numbers-parser** (the Python library this server depends on):
@@ -130,10 +138,10 @@ The entrypoint is written as:
 
 ## Requirements
 
-- **macOS or Linux** — `numbers-parser` reads the file format directly, so most tools work anywhere. **Formatting and formula tools require macOS with Numbers.app.**
+- **macOS** — the npm package is macOS-only (it declares `os: ["darwin"]`). Reads go through `numbers-parser` directly (no Numbers.app needed); **formatting and formula tools additionally require Numbers.app.**
 - **Node.js 20+** — Required for the MCP server
 - **Python 3.11+** — the `numbers-parser` library installs automatically into a project-local venv on first use (or pre-warm with `pnpm 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.
+- **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](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/AUTOMATION-PERMISSION.md). Run the **`doctor`** tool to verify your setup.
 
 ## Features
 
@@ -179,7 +187,7 @@ The entrypoint is written as:
 |---------|-------------|
 | **Import CSV/TSV/JSON** | Convert a tabular file into a new `.numbers` spreadsheet |
 | **Health Check** | Verify Python 3 and numbers-parser are installed |
-| **Doctor** | Richer setup diagnostic — read sidecar, Numbers.app, and Automation permission, each reported ok / warn / fail with actionable advice |
+| **Doctor** | Richer setup diagnostic — Python interpreter (path + version), read sidecar, Numbers.app, and Automation permission, each reported ok / warn / fail with actionable advice |
 
 All tools also return **structured JSON** (`structuredContent`) alongside the human-readable text, so agents can consume results without parsing prose.
 
@@ -210,11 +218,11 @@ Verify Python 3 and `numbers-parser` are installed and reachable from the server
 
 #### `doctor`
 
-Run a full setup diagnostic with three separate checks: `numbers_parser` (the read sidecar — required for all reads/exports), `numbers_app` (Numbers.app present — required for write/format tools), and `automation_permission` (an informational reminder that write tools need Automation permission for Numbers.app). Each is reported as ok / warn / fail with actionable advice. This is the richer counterpart to `health-check`; reach for it first when a tool returns a permission or setup error.
+Run a full setup diagnostic with four separate checks: `python_interpreter` (the resolved Python's path and version — warns when it's older than 3.11, the most common setup failure since stock macOS ships 3.9), `numbers_parser` (the read sidecar — required for all reads/exports), `numbers_app` (Numbers.app present — required for write/format tools), and `automation_permission` (an informational reminder that write tools need Automation permission for Numbers.app). Each is reported as ok / warn / fail with actionable advice. This is the richer counterpart to `health-check`; reach for it first when a tool returns a permission or setup error.
 
 **Parameters:** None
 
-**Returns:** A per-check report. The `structuredContent` carries the raw `{ healthy, checks[] }`, where each check has `name`, `status` (`ok`/`warn`/`fail`), and `detail`. Reads don't need Automation permission, but writes do — see [docs/AUTOMATION-PERMISSION.md](docs/AUTOMATION-PERMISSION.md).
+**Returns:** A per-check report. The `structuredContent` carries the raw `{ healthy, checks[] }`, where each check has `name`, `status` (`ok`/`warn`/`fail`), and `detail`. Reads don't need Automation permission, but writes do — see [docs/AUTOMATION-PERMISSION.md](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/AUTOMATION-PERMISSION.md).
 
 ---
 
@@ -595,7 +603,7 @@ AI: [calls import-csv with inputPath, outputPath]
 ### npm (Recommended)
 
 ```bash
-npm install -g github:sweetrb/apple-numbers-mcp
+npm install -g apple-numbers-mcp
 pip3 install numbers-parser
 ```
 
@@ -609,6 +617,8 @@ pnpm run setup    # creates ./venv and installs numbers-parser
 pnpm run build
 ```
 
+Installing the repo directly from GitHub (`npm install -g github:sweetrb/apple-numbers-mcp`) also counts as a from-source install: it runs the repo's build on your machine and **requires pnpm**. Prefer the published npm package above unless you specifically want unreleased code.
+
 If installed from source, use this configuration:
 ```json
 {
@@ -683,7 +693,7 @@ This is the same Python-sidecar pattern used by [apple-photos-mcp](https://githu
 ## Known Limitations
 
 For the full rundown — the read-vs-write split, AppleScript-only formulas/styles,
-indexing, dates, format lag, and concurrent edits — see **[docs/LIMITATIONS.md](docs/LIMITATIONS.md)**.
+indexing, dates, format lag, and concurrent edits — see **[docs/LIMITATIONS.md](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/LIMITATIONS.md)**.
 The summary below is the quick version.
 
 | Limitation | Reason |
@@ -702,8 +712,10 @@ These are tracked for future releases. The underlying `numbers-parser` library h
 
 ## Troubleshooting
 
-### "numbers-parser not installed. Run: npm run setup"
-- Run `pip3 install numbers-parser` (global) or `npm run setup` (project-local venv).
+### "numbers-parser not installed"
+- **Most common cause: your `python3` is older than 3.11** — stock macOS ships Python 3.9, which `numbers-parser` can't run on. Install a newer Python (`brew install python@3.12`), then simply retry the tool call: the venv rebuilds automatically.
+- Otherwise, install the library directly: `pip3 install numbers-parser` (global Python), or run `scripts/setup.sh` from a repo checkout (`pnpm run setup`) to build the project-local venv.
+- Run the **`doctor`** tool — it reports the resolved Python interpreter path and version, so a too-old stock Python is visible at a glance.
 - If you used a virtualenv, make sure it's the one at `./venv/` in the project directory.
 
 ### `apple-numbers` server fails to connect when run from a clone
@@ -719,7 +731,7 @@ These are tracked for future releases. The underlying `numbers-parser` library h
 ### Formatting / formula tools fail with "Numbers.app not running" or "Not authorized to send Apple events to Numbers"
 - Open Numbers.app at least once. macOS will prompt for automation permission — accept it.
 - Verify in **System Settings → Privacy & Security → Automation**, or reset with `tccutil reset AppleEvents`.
-- Run the **`doctor`** tool to confirm your setup — it reports the Numbers.app and Automation-permission checks separately. See the [Automation Permission guide](docs/AUTOMATION-PERMISSION.md). Reads don't need this permission; only writes do.
+- Run the **`doctor`** tool to confirm your setup — it reports the Numbers.app and Automation-permission checks separately. See the [Automation Permission guide](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/AUTOMATION-PERMISSION.md). Reads don't need this permission; only writes do.
 
 ### Output looks wrong (dates as ISO, floats with decimals)
 - The server normalizes dates to ISO 8601 and rounds floats that are within `1e-9` of an integer. If you want raw values, file an issue.
@@ -766,7 +778,7 @@ A software consulting, contracting, and development company.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details. This project is not affiliated with Apple Inc. or the [numbers-parser](https://pypi.org/project/numbers-parser/) project.
+MIT License - see [LICENSE](https://github.com/sweetrb/apple-numbers-mcp/blob/main/LICENSE) for details. This project is not affiliated with Apple Inc. or the [numbers-parser](https://pypi.org/project/numbers-parser/) project.
 
 ## Contributing
 
@@ -783,4 +795,4 @@ Part of a family of macOS MCP servers:
 
 ## Recurring macOS permission prompts
 
-If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), see [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md) — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.
+If macOS keeps re-prompting for Full Disk Access or Automation for `node` (often after a `brew upgrade`), see [docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md) — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.

package/build/index.js

@@ -21421,7 +21421,7 @@ function findSystemPython() {
     }
   }
   throw new Error(
-    'Python 3 not found. Run "npm run setup" to create a venv, or ensure python3 is on PATH.'
+    "Python 3 not found on PATH. Install Python >= 3.11 (stock macOS ships 3.9 - brew install python@3.12), or run scripts/setup.sh from a repo checkout. See https://github.com/sweetrb/apple-numbers-mcp#troubleshooting"
   );
 }
 function resolvePython() {
@@ -21496,7 +21496,7 @@ function looksLikeMissingDep(message) {
   return /not installed|No module named|ModuleNotFoundError/i.test(message);
 }
 function setupHint() {
-  return `Run: npm run setup (or set ${ENV_PREFIX}_NO_AUTO_SETUP=0 to allow automatic setup).`;
+  return `Install it with: pip3 install numbers-parser (requires Python >= 3.11; stock macOS ships 3.9 - brew install python@3.12), or run scripts/setup.sh from a repo checkout. Run the doctor tool to diagnose, and see https://github.com/sweetrb/apple-numbers-mcp#troubleshooting (set ${ENV_PREFIX}_NO_AUTO_SETUP=0 to allow automatic setup).`;
 }
 var DEFAULT_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
 function getMaxBuffer() {
@@ -21529,12 +21529,27 @@ function execReader(command, args, timeoutMs) {
   } catch (err) {
     const error2 = err;
     const stderr = error2.stderr?.toString().trim() ?? "";
-    if (stderr.includes(`${PACKAGE} not installed`) || looksLikeMissingDep(stderr)) {
+    const stdout = error2.stdout?.toString().trim() ?? "";
+    let sidecarError = null;
+    if (stdout) {
+      try {
+        const parsed = JSON.parse(stdout);
+        if (typeof parsed === "object" && parsed !== null && typeof parsed.error === "string") {
+          sidecarError = parsed.error;
+        }
+      } catch {
+      }
+    }
+    const missingDep = (s) => s.includes(`${PACKAGE} not installed`) || looksLikeMissingDep(s);
+    if (sidecarError !== null && missingDep(sidecarError) || missingDep(stderr)) {
       return { error: `${PACKAGE} not installed. ${setupHint()}` };
     }
     if (error2.message?.includes("ETIMEDOUT") || error2.message?.includes("timed out")) {
       return { error: `Operation timed out after ${timeoutMs}ms. File may be very large.` };
     }
+    if (sidecarError !== null) {
+      return { error: sidecarError };
+    }
     if (stderr) {
       return { error: stderr };
     }
@@ -21551,6 +21566,18 @@ function runNumbersReader(command, args, timeoutMs = 3e4) {
   }
   return result;
 }
+function getPythonInfo() {
+  try {
+    const python = resolvePython();
+    const version3 = execFileSync(python, ["--version"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    return { path: python, version: version3 };
+  } catch {
+    return null;
+  }
+}
 function checkDependencies() {
   ensureReady();
   try {
@@ -22067,18 +22094,42 @@ import { existsSync as existsSync3 } from "node:fs";
 var NUMBERS_APP_PATHS = ["/Applications/Numbers.app", "/System/Applications/Numbers.app"];
 function runDoctor(_manager) {
   const checks = [];
+  try {
+    const info = getPythonInfo();
+    if (info) {
+      const m = /Python (\d+)\.(\d+)/.exec(info.version);
+      const tooOld = m !== null && (Number(m[1]) < 3 || Number(m[1]) === 3 && Number(m[2]) < 11);
+      checks.push({
+        name: "python_interpreter",
+        status: tooOld ? "warn" : "ok",
+        detail: tooOld ? `${info.version} at ${info.path} \u2014 numbers-parser requires Python >= 3.11 (stock macOS ships 3.9). Install a newer Python (brew install python@3.12) and retry \u2014 the venv rebuilds automatically. See https://github.com/sweetrb/apple-numbers-mcp#troubleshooting` : `${info.version} (${info.path})`
+      });
+    } else {
+      checks.push({
+        name: "python_interpreter",
+        status: "fail",
+        detail: "Python 3 not found on PATH. Install Python >= 3.11 (e.g. brew install python@3.12). See https://github.com/sweetrb/apple-numbers-mcp#troubleshooting"
+      });
+    }
+  } catch (e) {
+    checks.push({
+      name: "python_interpreter",
+      status: "warn",
+      detail: `could not resolve the Python interpreter: ${String(e)}`
+    });
+  }
   try {
     const dep = checkDependencies();
     checks.push({
       name: "numbers_parser",
       status: dep.ok ? "ok" : "fail",
-      detail: dep.ok ? dep.message : `${dep.message} Run: npm run setup`
+      detail: dep.message
     });
   } catch (e) {
     checks.push({
       name: "numbers_parser",
       status: "fail",
-      detail: `could not verify numbers-parser: ${String(e)}. Run: npm run setup`
+      detail: `could not verify numbers-parser: ${String(e)}. ${setupHint()}`
     });
   }
   try {
@@ -22279,7 +22330,7 @@ server.registerTool(
 server.registerTool(
   "doctor",
   {
-    description: "Use when: a tool returns a permission or setup error, or you want the full setup diagnostic before writing/formatting.\nReturns: three checks \u2014 numbers-parser (read sidecar), Numbers.app (needed for writes), and Automation permission \u2014 each as ok/warn/fail with actionable advice.\nDo not use when: you only need the lightweight read-sidecar version check \u2014 use health-check instead.",
+    description: "Use when: a tool returns a permission or setup error, or you want the full setup diagnostic before writing/formatting.\nReturns: four checks \u2014 the resolved Python interpreter (path + version), numbers-parser (read sidecar), Numbers.app (needed for writes), and Automation permission \u2014 each as ok/warn/fail with actionable advice.\nDo not use when: you only need the lightweight read-sidecar version check \u2014 use health-check instead.",
     inputSchema: {},
     outputSchema: {
       healthy: external_exports.boolean().optional(),

package/docs/AUTOMATION-PERMISSION.md

@@ -0,0 +1,147 @@
+# Automation Permission for Write & Format Operations
+
+Apple Numbers MCP has **two distinct backends**, and only one of them needs a
+special macOS permission:
+
+- **Reads** go through [numbers-parser](https://pypi.org/project/numbers-parser/)
+  (Python). They open the `.numbers` file **directly** off disk and need **no**
+  special permission — just normal file access.
+- **Writes and formatting** go through **AppleScript driving Numbers.app**.
+  numbers-parser can't write styles or formulas, so the server scripts Numbers.app
+  to do it. macOS gates one app controlling another behind the **Automation**
+  permission, so these tools require it.
+
+This page explains which tools need Automation permission, how the prompt appears,
+how to grant or reset it, what failure looks like, and how to verify.
+
+## Which tools need Automation permission
+
+**Need it** (AppleScript → Numbers.app — writes, formulas, formatting, structure
+changes, CSV import, file creation):
+
+- `set-cell`, `set-cells-batch`
+- `add-rows`, `update-rows`, `delete-rows`
+- `add-sheet`, `add-table`, `rename-sheet`, `rename-table`
+- `set-formula`, `set-formulas-batch`
+- `set-cell-style`, `set-cells-style-batch`
+- `set-column-width`, `set-row-height`
+- `merge-cells`, `unmerge-cells`
+- `create-spreadsheet`
+- `import-csv`
+
+**Do NOT need it** (pure numbers-parser, file read directly off disk):
+
+- `get-file-info`
+- `read-table`
+- `get-cell`
+- `search`
+- `export-table`
+- `health-check` / `doctor` (these only probe the environment)
+
+So you can fully inspect, search, and export a spreadsheet with no Automation
+permission at all. The permission only matters the moment you try to **change or
+format** a file.
+
+> **Numbers.app must be installed.** The write/format path scripts Numbers.app, so
+> the app has to be present at `/Applications/Numbers.app` (or
+> `/System/Applications/Numbers.app`). Reads don't need it. If Numbers.app is
+> missing, `doctor` reports `numbers_app: warn` and the write tools fail.
+
+## How the permission prompt appears
+
+The **first time** a write/format tool runs, macOS shows a one-time dialog:
+
+> **"<Host App>" wants access to control "Numbers". Allowing control will provide
+> access to documents and data in "Numbers", and to perform actions within that
+> app.**
+
+Click **OK / Allow**. The grant is remembered, so subsequent writes don't prompt
+again. The "host app" is whatever process launched the MCP server — Claude
+Desktop, Terminal, iTerm, or VS Code — **not** `node` and **not** Numbers.app.
+
+If the host app runs headless or the dialog is dismissed/denied, the write fails
+(see below) and you must grant the permission manually.
+
+## How to grant it manually
+
+1. Open **System Settings** (or **System Preferences** on older macOS).
+2. Go to **Privacy & Security → Automation**.
+3. Find the **host app** that runs the MCP server (Claude, Terminal, iTerm, or
+   VS Code) in the list.
+4. Expand it and enable the toggle next to **Numbers**.
+
+| Host | App to allow |
+|------|--------------|
+| Claude Desktop | `Claude.app` |
+| Claude Code in Terminal | `Terminal.app` |
+| Claude Code in iTerm | `iTerm.app` |
+| Claude Code in VS Code | `Visual Studio Code.app` |
+
+> **Grant it to the right app.** Automation permission applies to the process that
+> *spawns* the server, not to `node` or to Numbers.app. If you launch Claude Code
+> from iTerm, allow iTerm to control Numbers; if you use Claude Desktop, allow
+> Claude. Granting it to the wrong app has no effect.
+
+## What failure looks like
+
+When the host app lacks Automation permission for Numbers, the AppleScript layer
+fails and the write/format tool returns an error containing:
+
+```
+Not authorized to send Apple events to Numbers.
+```
+
+(or, equivalently, an `errAEEventNotPermitted` / `-1743` error.) You may also see
+`"Numbers got an error: ..."` style messages if Numbers.app itself can't be
+driven. In all of these cases the underlying `.numbers` file is **not** modified.
+
+If you instead see **"Numbers.app not running"** or a message that Numbers.app
+can't be found, the problem is that the app isn't installed/openable — open
+Numbers.app once and retry.
+
+## Resetting the permission
+
+If the grant got into a bad state (e.g. you clicked **Don't Allow** the first
+time, and macOS now won't re-prompt), reset the Automation permissions and let the
+prompt appear again on the next write:
+
+```bash
+tccutil reset AppleEvents
+```
+
+This clears Apple-event (Automation) grants for **all** apps; macOS will re-prompt
+on the next attempt. To be more surgical you can scope it to the host bundle id,
+e.g.:
+
+```bash
+tccutil reset AppleEvents com.apple.Terminal
+```
+
+After resetting, **fully quit and reopen the host app**, then run any write tool
+(e.g. `set-cell`) and click **OK** when the dialog appears.
+
+## Verifying
+
+Run the **`doctor`** tool — it's the richest diagnostic and reports four checks
+as `ok` / `warn` / `fail`:
+
+- **`python_interpreter`** — the resolved Python's path and version (warns when
+  older than 3.11; stock macOS ships 3.9).
+- **`numbers_parser`** — is the Python read sidecar installed (powers all reads).
+- **`numbers_app`** — is Numbers.app present (required for any write/format tool).
+- **`automation_permission`** — an informational reminder that write tools need
+  Automation permission, granted on first use.
+
+> **Note:** Automation permission can't be probed without actually trying to
+> control Numbers (that would itself trigger the prompt), so `doctor` reports it
+> **informationally** rather than testing it live. The definitive test is to run a
+> real write — e.g. `set-cell` on a scratch file. If it succeeds, the permission
+> is in place; if it returns *"Not authorized to send Apple events to Numbers,"*
+> grant or reset it as above.
+
+## See also
+
+- [docs/LIMITATIONS.md](./LIMITATIONS.md) — the full read-vs-write split and other
+  limits.
+- [Known Limitations](../README.md#known-limitations) and
+  [Security and Privacy](../README.md#security-and-privacy) in the README.

package/docs/LIMITATIONS.md

@@ -0,0 +1,145 @@
+# Limitations
+
+Apple Numbers MCP is a **hybrid** bridge to `.numbers` spreadsheets: it **reads**
+them offline with [numbers-parser](https://pypi.org/project/numbers-parser/)
+(Python, no app required), and **writes/formats** them by scripting **Numbers.app**
+via AppleScript (because numbers-parser can't write styles or formulas). That split
+is the source of most of the limitations below.
+
+This page documents the real limitations — what the server can't do and why — so
+they aren't re-investigated every release. These agree with the README's
+[Known Limitations](../README.md#known-limitations); this page adds the *why* and
+*what to do* for each.
+
+## Writes & formatting require Numbers.app + Automation permission (reads don't)
+
+**Why:** numbers-parser can read a `.numbers` file directly off disk, but it does
+**not** write styles, formulas, or cell-dimension changes reliably. To do those,
+the server scripts **Numbers.app** through AppleScript. That means every
+write/format tool needs (a) **Numbers.app installed** and (b) the host app to have
+**Automation** permission to control Numbers. Read tools (`get-file-info`,
+`read-table`, `get-cell`, `search`, `export-table`) use only numbers-parser and
+need **neither** — they work on macOS or Linux with no Automation grant.
+
+**What to do:** For inspection/search/export, nothing special is needed. For any
+write — `set-cell(s)`, `add/update/delete-rows`, `add-sheet`/`add-table`,
+`rename-*`, `set-formula(s)`, `set-*-style`, `set-column-width`/`set-row-height`,
+`merge`/`unmerge`, `create-spreadsheet`, `import-csv` — install Numbers.app and
+grant Automation permission. Full steps in
+[AUTOMATION-PERMISSION.md](./AUTOMATION-PERMISSION.md). Verify with `doctor`.
+
+## Formulas and styling are AppleScript-only
+
+**Why:** Writing a formula (`set-formula`, `set-formulas-batch`) or a style
+(`set-cell-style`, `set-cells-style-batch`, `set-column-width`, `set-row-height`,
+`merge-cells`/`unmerge-cells`) cannot be done through the Python read path —
+numbers-parser doesn't expose reliable writes for these. They go exclusively
+through Numbers.app via AppleScript, so they inherit the macOS-only + Automation
+requirements above and can't run on Linux.
+
+**What to do:** Run formula/format tools on macOS with Numbers.app. If you only
+have the Python path available (e.g. Linux), you can still read formulas and
+formatted values (via `get-cell verbose: true`) — you just can't set them.
+
+## Values vs. formulas
+
+**Why:** The value-writing tools (`set-cell`, `set-cells-batch`, `add-rows`,
+`update-rows`) write **computed values**, not formulas. Passing `"=SUM(...)"` as a
+value writes the literal string, not a live formula.
+
+**What to do:** Use `set-formula` / `set-formulas-batch` to write actual formulas
+(these require Numbers.app). Use the value tools for plain data.
+
+## No charts, images, or conditional formatting
+
+**Why:** numbers-parser doesn't expose charts, embedded images, or
+conditional-formatting rules, and the AppleScript layer here doesn't implement
+them either. There is no tool to create, read, or edit a chart, an image, or a
+conditional-format rule.
+
+**What to do:** Build charts / conditional formatting by hand in Numbers.app on the
+data this server writes. The server can populate and format the underlying cells;
+the visualization layer stays manual.
+
+## Sheet deletion is not supported
+
+**Why:** numbers-parser doesn't expose sheet removal, so there's no `delete-sheet`
+tool. (Rows can be deleted with `delete-rows`; whole sheets cannot.)
+
+**What to do:** Delete a sheet manually in Numbers.app.
+
+## Indexing is 0-based for rows and columns
+
+**Why:** Every tool that takes a `row`/`col` (or `startRow`/`endRow`/`startCol`/
+`endCol`) uses **0-based** indices — verified throughout `src/index.ts` (e.g.
+`row: z.number().int().min(0).describe("Row index (0-based)")`). The header row is
+**row 0**, so the first data row is **row 1**. This is why `read-table` defaults
+`startRow` to `1` (i.e. "skip the header"). Ranges are **inclusive** on both ends
+(e.g. `delete-rows startRow: 1 endRow: 3` deletes three rows).
+
+**What to do:** Treat the header as row 0. A spreadsheet "row 5" that a human sees
+in Numbers.app (1-based, header included) is index `4` here. When in doubt, call
+`read-table` or `get-cell` first to confirm what's at a given index.
+
+## Dates are ISO 8601
+
+**Why:** The Python layer normalizes all dates to **ISO 8601** on read
+(`val.isoformat()`), collapsing a pure date with no time to `YYYY-MM-DD` and
+keeping the full datetime otherwise. On write, a value typed as `date` is parsed
+with `datetime.fromisoformat`, so date inputs must be ISO 8601 too.
+
+**What to do:** Pass dates as `"2025-06-01"` or a full ISO datetime, and expect ISO
+8601 back. Locale-formatted dates (e.g. `"6/1/25"`) are not parsed as dates.
+
+## numbers-parser may lag the newest Numbers file format
+
+**Why:** Apple periodically changes the `.numbers` on-disk format with new
+Numbers.app releases. numbers-parser is a third-party library that has to catch up
+to each new format version. A file saved by a very new Numbers.app can occasionally
+read incompletely (or error) on an older numbers-parser.
+
+**What to do:** Keep numbers-parser current (`pip3 install -U numbers-parser`, or
+re-run `pnpm run setup`). If a read fails or looks wrong on a freshly-saved file,
+upgrade numbers-parser first. Check the installed version with `health-check` /
+`doctor`.
+
+## Concurrent edits while Numbers.app has the file open
+
+**Why:** Two backends can touch the same file. The read path (numbers-parser) reads
+whatever is on disk, and the write path drives Numbers.app. If Numbers.app has the
+file **open with unsaved changes**, what numbers-parser reads off disk can be
+stale, and a write through AppleScript targets the app's in-memory copy — the two
+can disagree, and saves can race.
+
+**What to do:** Prefer to **close the file in Numbers.app** before reading or doing
+bulk writes through the server, so disk and app agree. If you must keep it open,
+read back with `read-table` / `get-cell` after writes to confirm the result landed,
+and avoid editing the same cells by hand in Numbers.app at the same time.
+
+## Concurrent writes to the same file are last-writer-wins
+
+**Why:** Each write tool opens the `.numbers` file, applies its change to an
+in-memory document, and saves the **whole document** back. The save itself is
+**atomic** — every mutating command writes to a sibling temp file and `os.replace()`s
+it onto the target — so an interrupted or crashed write can never leave a torn or
+half-written file. But atomicity protects against *corruption*, **not** against
+*lost updates*: if two writes to the same file overlap (two agents, two server
+instances, or a server write racing a hand edit in Numbers.app), each loaded the
+document independently, and whichever saves **last** overwrites the other's change
+wholesale. There is no file locking, no merge, and no optimistic-concurrency check.
+
+**What to do:** **Serialize writes to a given file** — don't fan out concurrent
+mutations against the same `.numbers` file from multiple agents or sessions. Batch
+related edits into a single call (`set-cells-batch`, `update-rows`,
+`set-formulas-batch`) instead of many overlapping ones, finish one tool call before
+starting the next on the same file, and after a burst of writes read back with
+`read-table` / `get-cell` to confirm the final state is what you intended.
+
+## macOS-only for writes; reads are cross-platform
+
+**Why:** Reads run anywhere numbers-parser runs (macOS or Linux). Writes/formatting
+script Numbers.app, which only exists on macOS.
+
+**What to do:** Run write/format workloads on a Mac with Numbers.app installed and
+Automation permission granted. See
+[AUTOMATION-PERMISSION.md](./AUTOMATION-PERMISSION.md).

package/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md

@@ -0,0 +1,109 @@
+# Node runtime & TCC permission stability
+
+macOS gates this MCP server's access to your data behind **TCC** permissions —
+**Full Disk Access** (to read app data such as Mail, Notes, or Photos) and
+**Automation / Apple Events** (to drive an app like Mail.app or Notes.app via
+AppleScript). See this repo's Full Disk Access / Automation notes for *which*
+operations need which permission.
+
+This page is about a **separate, recurring annoyance**: being asked to approve
+those permissions **over and over**, often right after a routine `brew upgrade`.
+
+## Symptom
+
+- You granted Full Disk Access (and/or Automation) to "node", but days later
+  macOS prompts again — `"node" wants access to ...` or `"node" wants to control
+  "Mail"`.
+- System Settings → Privacy & Security → Full Disk Access shows **several
+  identical "node" rows**, usually only one enabled.
+- It tends to happen immediately after you update Node.
+
+## Cause
+
+TCC binds a permission grant to the **code identity of the binary that performs
+the access** — here, the `node` executable that launches the MCP server. For a
+binary that is only **ad-hoc signed** (no Developer ID / Team ID), TCC keys the
+grant to the binary's **cdhash**, a hash of its contents.
+
+Homebrew's `node` formula is ad-hoc signed:
+
+```bash
+$ codesign -dvvv "$(which node)" 2>&1 | grep -E 'Signature|TeamIdentifier'
+Signature=adhoc
+TeamIdentifier=not set
+```
+
+Every Node update **replaces the binary**, which **changes the cdhash**, so TCC
+no longer recognizes it as the thing you approved — and re-prompts. The extra
+"node" rows are stale cdhashes from previous versions.
+
+By contrast, properly signed apps (Chrome, Slack, …) keep their permissions
+across auto-updates because TCC matches them on a stable **Designated
+Requirement** derived from their Developer ID, not on the cdhash.
+
+## Fix: run the MCP under the official, Developer-ID-signed Node
+
+Node binaries distributed from **nodejs.org** are signed with a real Developer
+ID (`Node.js Foundation`, Team `HX7739G8FX`), notarized, and self-contained.
+Pointing the MCP server at one gives TCC a **stable** identity to match, so a
+permission you grant **persists across future Node updates**. It also decouples
+the MCP runtime from your Homebrew/dev Node, which can keep updating freely.
+
+### Steps (Apple Silicon shown; use `darwin-x64` on Intel)
+
+1. Install a current LTS to a stable path (kept off `PATH` so it won't shadow
+   your dev Node):
+
+   ```bash
+   VER=v24.17.0 ARCH=darwin-arm64
+   mkdir -p ~/mcp-runtime && cd ~/mcp-runtime
+   curl -O https://nodejs.org/dist/$VER/node-$VER-$ARCH.tar.gz
+   curl -O https://nodejs.org/dist/$VER/SHASUMS256.txt
+   grep "  node-$VER-$ARCH.tar.gz$" SHASUMS256.txt | shasum -a 256 -c -   # must print OK
+   tar -xzf node-$VER-$ARCH.tar.gz
+   ln -sfn node-$VER-$ARCH node-current
+   ```
+
+2. Confirm it's Developer-ID signed:
+
+   ```bash
+   codesign -dvvv ~/mcp-runtime/node-current/bin/node 2>&1 | grep -E 'Authority=Developer ID|TeamIdentifier'
+   # Authority=Developer ID Application: Node.js Foundation (HX7739G8FX)
+   # TeamIdentifier=HX7739G8FX
+   ```
+
+3. Point this MCP server's launcher at it. For Claude Desktop, edit
+   `~/Library/Application Support/Claude/claude_desktop_config.json` and set this
+   server's `command` to the absolute path:
+
+   ```json
+   {
+     "mcpServers": {
+       "apple-numbers": {
+         "command": "/Users/<you>/mcp-runtime/node-current/bin/node",
+         "args": ["/path/to/apple-numbers-mcp/build/index.js"]
+       }
+     }
+   }
+   ```
+
+   Servers launched via `npx` that don't need Full Disk Access can stay on
+   Homebrew Node.
+
+4. **Restart your MCP client** so the server relaunches under the new Node.
+
+5. **Grant the permissions once** to the new binary:
+   - *Full Disk Access*: System Settings → Privacy & Security → Full Disk Access
+     → **+** → ⌘⇧G → paste `~/mcp-runtime/node-current/bin/node`.
+   - *Automation*: the first time the server drives an app you'll get a one-time
+     `"node" wants to control "<App>"` prompt — click **Allow**.
+
+   Both grants are keyed to the official Node's stable signature, so you should
+   not be asked again — including after future Node updates. You can delete the
+   stale "node" rows from the Full Disk Access list.
+
+### Updating the dedicated Node later
+
+Drop a newer official LTS tarball into `~/mcp-runtime/`, repoint the
+`node-current` symlink, and restart your client. The signing identity is
+unchanged, so existing grants carry over — no re-approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-numbers-mcp",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "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",
@@ -12,6 +12,7 @@
     "src/utils/numbers_reader.py",
     "scripts/setup.sh",
     "requirements.txt",
+    "docs",
     "README.md",
     "LICENSE"
   ],

package/scripts/setup.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 #
 # Create a Python venv and install numbers-parser.
-# Run via: npm run setup
+# Run via: pnpm run setup (or: bash scripts/setup.sh)
 #
 set -euo pipefail
 
@@ -32,7 +32,7 @@ echo "    Using: $PYTHON ($($PYTHON --version))"
 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 "         brew install python@3.12     # then re-run: scripts/setup.sh" >&2
   echo "       or from https://www.python.org/downloads/" >&2
   exit 1
 fi

package/src/utils/numbers_reader.py

@@ -14,7 +14,12 @@ try:
     from numbers_parser import Document
 except ImportError:
     print(json.dumps({
-        "error": "numbers-parser not installed. Run: npm run setup"
+        "error": (
+            "numbers-parser not installed. Install it with: pip3 install numbers-parser "
+            "(requires Python >= 3.11; stock macOS ships 3.9 - brew install python@3.12), "
+            "or run scripts/setup.sh from a repo checkout. Run the doctor tool to diagnose. "
+            "See https://github.com/sweetrb/apple-numbers-mcp#troubleshooting"
+        )
     }))
     sys.exit(1)