apple-numbers-mcp 1.1.9 → 1.1.11

package/README.md

@@ -77,9 +77,24 @@ numbers-parser`); see [Requirements](#requirements).
 
 ### Other Hosts (Hermes, Antigravity)
 
-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).
+Two more hosts can run 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`](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).
+- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:
+
+  ```bash
+  hermes mcp add apple-numbers --command npx --args -y apple-numbers-mcp
+  ```
+
+  Or add it to `~/.hermes/config.yaml` by hand:
+
+  ```yaml
+  mcp_servers:
+    apple-numbers:
+      command: npx
+      args: ["-y", "apple-numbers-mcp"]
+  ```
+
+  Restart your Hermes session afterward so the tools load.
 - **[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
@@ -138,10 +153,10 @@ The entrypoint is written as:
 
 ## Requirements
 
-- **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.**
+- **macOS** — the npm package is macOS-only (it declares `os: ["darwin"]`). Reads **and value/structure writes** 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](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/AUTOMATION-PERMISSION.md). Run the **`doctor`** tool to verify your setup.
+- **Automation permission (formulas & formatting only)** — Reads, exports and ordinary value/structure writes (`set-cell(s)`, `add`/`update`/`delete-rows`, `add-sheet`/`add-table`, `rename-*`, `create-spreadsheet`, `import-csv`) need no special permission and no Numbers.app. Only the eight formula/format tools — `set-formula(s)`, `set-cell(s)-style`, `set-column-width`/`set-row-height`, `merge-cells`/`unmerge-cells` — 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
 
@@ -218,11 +233,11 @@ Verify Python 3 and `numbers-parser` are installed and reachable from the server
 
 #### `doctor`
 
-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.
+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 the formula/format tools only), and `automation_permission` (an informational reminder that those 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](https://github.com/sweetrb/apple-numbers-mcp/blob/main/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`. Only the formula/format tools need Automation permission — see [docs/AUTOMATION-PERMISSION.md](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/AUTOMATION-PERMISSION.md).
 
 ---
 
@@ -251,6 +266,8 @@ Read data from a table. Returns headers and rows. Defaults to the first sheet an
 | `endRow` | number | No | 0-based end row, inclusive (default: last row) |
 | `columns` | (string \| number)[] | No | Column filter: header names or 0-based indices |
 
+**Returns:** Sheet name, table name, the headers and rows selected, and `numRows` / `numCols` describing **the selection** — not the table. When you pass `startRow`/`endRow`/`columns`, those counts describe what came back; use [`get-file-info`](#get-file-info) for the table's real dimensions.
+
 ---
 
 #### `get-cell`
@@ -286,6 +303,8 @@ Case-insensitive partial match across every cell in a `.numbers` file.
 
 Export a table to CSV, TSV, or JSON.
 
+**⚠️ Safety:** Writes a file to disk at `outputPath`. The path is written unconditionally — any existing file there is **overwritten** — so confirm the destination before calling.
+
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | string | Yes | Path to the `.numbers` file |
@@ -404,6 +423,8 @@ Add a new sheet, optionally with headers for the default table.
 | `tableName` | string | No | Name for the default table |
 | `headers` | string[] | No | Headers for the default table |
 
+**Table geometry:** pass `headers` and the new table is created **1 row × `headers.length` columns**; omit them and you get a **12 × 8** grid of empty cells. There is no way to override the size through MCP — delete the extra rows with `delete-rows` if you don't want them. The response reports the dimensions that were created.
+
 ---
 
 #### `add-table`
@@ -417,6 +438,8 @@ Add a new table to an existing sheet.
 | `tableName` | string | No | Name for the new table |
 | `headers` | string[] | No | Column headers |
 
+**Table geometry:** same rule as [`add-sheet`](#add-sheet) — with `headers` the table is **1 × `headers.length`**, without them **12 × 8**.
+
 ---
 
 #### `rename-sheet` / `rename-table`
@@ -468,7 +491,7 @@ Write multiple formulas in a single operation.
 | `path` | string | Yes | Path to the `.numbers` file |
 | `sheet` | string | Yes | Sheet name |
 | `table` | string | Yes | Table name |
-| `entries` | array | Yes | Array of `{row, col, formula}` objects |
+| `formulas` | array | Yes | Array of `{row, col, formula}` objects |
 
 ---
 
@@ -560,6 +583,12 @@ Import a CSV, TSV, or JSON file into a new `.numbers` spreadsheet. Auto-detects
 | `sheetName` | string | No | Default: `"Sheet 1"` |
 | `tableName` | string | No | Default: `"Table 1"` |
 
+**CSV/TSV fields are auto-typed.** Every field from a `csv`/`tsv` source is converted before it is written: `""` → empty cell, `true`/`false` → boolean, and anything Python's `int()`/`float()` parses → number. So a zip code `01234` becomes the number `1234`, `007` becomes `7`, and `1e5` becomes the number `100000`. This is deliberately less conservative than `set-cell`/`add-rows`, which keep leading-zero strings intact, and there is no per-column type control on import. For zero-padded identifiers, import from JSON instead (JSON values are passed through untouched) or repair the column afterwards with `set-cells-batch` using `type: "string"`.
+
+**JSON column sets come from the first object.** For an array of objects, the columns are the keys of `data[0]`; a key that appears only in a later object is dropped and objects missing an early key get blank cells — normalize the keys first. For an array of arrays, columns are named `Column_0`, `Column_1`, … and the first row is kept as data.
+
+**`format: "auto"` falls back to CSV.** Any extension that isn't `.csv`, `.tsv` or `.json` is parsed as comma-separated rather than erroring, so pass `format` explicitly for unusual extensions. The format actually used is echoed back in the result.
+
 ---
 
 ## Usage Patterns
@@ -584,7 +613,7 @@ AI: [calls search with query='Acme Corp']
 
 ```
 User: "Set B5 to =SUM(B2:B4) and bold the header row"
-AI: [calls set-formula] [calls set-cells-style-batch with bold:true on row 0]
+AI: [calls set-formula] [calls set-cells-style-batch with style {fontName: "Helvetica-Bold"} on row 0]
     "Done — B5 is =SUM(B2:B4) and the header row is bold."
 ```
 
@@ -648,6 +677,15 @@ All configuration is optional — the server works out of the box.
 | `APPLE_NUMBERS_MCP_NO_AUTO_SETUP` | unset (auto-setup on) | Set to a truthy value (`1`, `true`) to disable the one-time automatic creation of the Python venv. When set, the server will not run `setup.sh` on its own — you must provide `numbers-parser` yourself (`pip3 install numbers-parser` or `pnpm run setup`). |
 | `APPLE_NUMBERS_MCP_SETUP_TIMEOUT` | `300000` (5 minutes) | Timeout in milliseconds for the automatic venv bootstrap (`setup.sh`). Raise it on a slow network where the `numbers-parser` pip install would otherwise time out. |
 
+> **Per-call timeouts are not configurable.** Every `numbers-parser` sidecar call
+> runs under a fixed **30-second** timeout and every AppleScript call under a fixed
+> **60-second** one; there is no environment variable for either.
+> `APPLE_NUMBERS_MCP_SETUP_TIMEOUT` above governs only the one-time venv bootstrap,
+> and `APPLE_NUMBERS_MCP_MAX_BUFFER` caps stdout size, not wall-clock time. If you
+> hit `Operation timed out after 30000ms`, narrow the request — use `read-table`'s
+> `startRow`/`endRow` and `columns`, split large batches — rather than looking for
+> a knob.
+
 ### Configuration file (when the host strips `env`)
 
 Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed
@@ -686,19 +724,22 @@ This is the same Python-sidecar pattern used by [apple-photos-mcp](https://githu
 - **Local only** — All operations happen on the local machine. No data is sent to external servers.
 - **No credential storage** — The server doesn't store any passwords or authentication tokens.
 - **File-system access** — Tools take explicit paths; the server only reads or writes files you name.
-- **Numbers.app automation** — Formatting and formula tools drive Numbers.app via AppleScript. macOS will prompt for automation permission on first use.
+- **Numbers.app automation** — Formatting and formula tools drive Numbers.app via AppleScript. macOS will prompt for automation permission on first use. These tools **open the file in Numbers.app** (launching it if it isn't running), **save the whole document** — including any unsaved edits you have open in it — and **leave it open** afterwards. Everything else, including all value and structure writes, runs entirely in the Python sidecar and never touches the app.
 
 ---
 
 ## 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](https://github.com/sweetrb/apple-numbers-mcp/blob/main/docs/LIMITATIONS.md)**.
+For the full rundown — the values-vs-formatting backend split, AppleScript-only
+formulas/styles, `import-csv` auto-typing, fixed per-call timeouts, 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 |
 |------------|--------|
-| Formatting / formulas / dimensions need Numbers.app | `numbers-parser` doesn't write styles or formulas; the AppleScript layer fills that gap (macOS only) |
+| Formatting / formulas / dimensions need Numbers.app | `numbers-parser` doesn't write styles or formulas; the AppleScript layer fills that gap (macOS only). Value and structure writes do **not** need it |
+| `import-csv` auto-types CSV/TSV fields | Leading zeros are lost (`01234` → `1234`); JSON input is passed through untouched |
+| Per-call timeouts are fixed | 30 s for sidecar calls, 60 s for AppleScript; neither is configurable — narrow the request instead |
 | No conditional formatting | Not exposed by `numbers-parser` |
 | No charts or images | Not exposed by `numbers-parser` |
 | Sheet deletion not supported | Not exposed by `numbers-parser` |

package/build/index.js

@@ -3104,9 +3104,9 @@ var require_data = __commonJS({
   }
 });
 
-// node_modules/.pnpm/fast-uri@3.1.2/node_modules/fast-uri/lib/utils.js
+// node_modules/.pnpm/fast-uri@3.1.4/node_modules/fast-uri/lib/utils.js
 var require_utils = __commonJS({
-  "node_modules/.pnpm/fast-uri@3.1.2/node_modules/fast-uri/lib/utils.js"(exports, module) {
+  "node_modules/.pnpm/fast-uri@3.1.4/node_modules/fast-uri/lib/utils.js"(exports, module) {
     "use strict";
     var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
     var isIPv4 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
@@ -3417,9 +3417,9 @@ var require_utils = __commonJS({
   }
 });
 
-// node_modules/.pnpm/fast-uri@3.1.2/node_modules/fast-uri/lib/schemes.js
+// node_modules/.pnpm/fast-uri@3.1.4/node_modules/fast-uri/lib/schemes.js
 var require_schemes = __commonJS({
-  "node_modules/.pnpm/fast-uri@3.1.2/node_modules/fast-uri/lib/schemes.js"(exports, module) {
+  "node_modules/.pnpm/fast-uri@3.1.4/node_modules/fast-uri/lib/schemes.js"(exports, module) {
     "use strict";
     var { isUUID } = require_utils();
     var URN_REG = /([\da-z][\d\-a-z]{0,31}):((?:[\w!$'()*+,\-.:;=@]|%[\da-f]{2})+)/iu;
@@ -3627,9 +3627,9 @@ var require_schemes = __commonJS({
   }
 });
 
-// node_modules/.pnpm/fast-uri@3.1.2/node_modules/fast-uri/index.js
+// node_modules/.pnpm/fast-uri@3.1.4/node_modules/fast-uri/index.js
 var require_fast_uri = __commonJS({
-  "node_modules/.pnpm/fast-uri@3.1.2/node_modules/fast-uri/index.js"(exports, module) {
+  "node_modules/.pnpm/fast-uri@3.1.4/node_modules/fast-uri/index.js"(exports, module) {
     "use strict";
     var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
@@ -3770,6 +3770,7 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
+    var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
     function getParseError(parsed, matches) {
       if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
         return 'URI path must start with "/" when authority is present.';
@@ -3799,6 +3800,11 @@ var require_fast_uri = __commonJS({
           uri = "//" + uri;
         }
       }
+      const authorityMatch = uri.match(AUTHORITY_PREFIX);
+      if (authorityMatch !== null && authorityMatch[1].indexOf("\\") !== -1) {
+        parsed.error = "URI authority must not contain a literal backslash.";
+        malformedAuthorityOrPort = true;
+      }
       const matches = uri.match(URI_PARSE);
       if (matches) {
         parsed.scheme = matches[1];
@@ -3842,7 +3848,7 @@ var require_fast_uri = __commonJS({
         if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport)) {
           if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
             try {
-              parsed.host = URL.domainToASCII(parsed.host.toLowerCase());
+              parsed.host = new URL("http://" + parsed.host).hostname;
             } catch (e) {
               parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e;
             }
@@ -21421,7 +21427,7 @@ function findSystemPython() {
     }
   }
   throw new Error(
-    "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"
+    "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. Run the doctor tool to diagnose, and see https://github.com/sweetrb/apple-numbers-mcp#troubleshooting"
   );
 }
 function resolvePython() {
@@ -22138,27 +22144,27 @@ function runDoctor(_manager) {
       checks.push({
         name: "numbers_app",
         status: "ok",
-        detail: `Numbers.app present \u2014 write operations available (${found})`
+        detail: `Numbers.app present \u2014 formula and formatting tools available (${found})`
       });
     } else {
       checks.push({
         name: "numbers_app",
         status: "warn",
-        detail: "Numbers.app not found. Reads/exports via numbers-parser still work, but write, formatting, and other AppleScript tools need Numbers.app installed."
+        detail: "Numbers.app not found. Reads, exports and value/structure writes via numbers-parser still work; only the formula and formatting tools (set-formula(s), set-cell(s)-style, set-column-width/set-row-height, merge-cells/unmerge-cells) need Numbers.app installed."
       });
     }
   } catch (e) {
     checks.push({
       name: "numbers_app",
       status: "warn",
-      detail: `could not verify Numbers.app: ${String(e)}. Reads/exports still work; write/formatting tools need Numbers.app.`
+      detail: `could not verify Numbers.app: ${String(e)}. Reads, exports and value/structure writes still work; only the formula/formatting tools need Numbers.app.`
     });
   }
   try {
     checks.push({
       name: "automation_permission",
       status: "ok",
-      detail: "AppleScript write tools require Automation permission for Numbers.app, granted on first use (System Settings > Privacy & Security > Automation)."
+      detail: "The AppleScript formula/formatting tools require Automation permission for Numbers.app, granted on first use (System Settings > Privacy & Security > Automation). Reads and value/structure writes do not."
     });
   } catch (e) {
     checks.push({
@@ -22308,7 +22314,7 @@ var headerCellSchema = external_exports.string().max(MAX_HEADER_LEN);
 var server = new McpServer({
   name: "apple-numbers",
   version: version2,
-  description: "MCP server for reading and writing Apple Numbers (.numbers) spreadsheet files. Provides tools to inspect file structure, read table data, search cells, export to CSV/JSON/TSV, read individual cell values, create new spreadsheets, update cells, and append rows."
+  description: "MCP server for reading and writing Apple Numbers (.numbers) spreadsheet files. Inspect file structure, read/search/export table data and individual cells, create spreadsheets, write cells and add/update/delete rows, manage sheets and tables, import CSV/TSV/JSON \u2014 all offline via the numbers-parser sidecar \u2014 and, via Numbers.app, write live formulas, cell styling, column/row dimensions, and merges."
 });
 server.registerTool(
   "health-check",
@@ -22330,7 +22336,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: 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.",
+    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 (the read/write sidecar), Numbers.app (needed only for the formula/formatting tools), 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(),
@@ -22395,7 +22401,7 @@ ${summary}`,
 server.registerTool(
   "read-table",
   {
-    description: "Use when: you want the data from a table \u2014 headers plus rows, optionally limited to a row range (0-based inclusive indices; header is row 0, so data starts at row 1) and/or a subset of columns. Defaults to the first sheet and first table if sheet/table are omitted.\nReturns: sheet name, table name, dimensions, headers, and the selected rows.\nDo not use when: you only need one cell \u2014 use get-cell; you need the file's structure/names \u2014 use get-file-info; or you want to find a value's location \u2014 use search.",
+    description: "Use when: you want the data from a table \u2014 headers plus rows, optionally limited to a row range (0-based inclusive indices; header is row 0, so data starts at row 1) and/or a subset of columns. Defaults to the first sheet and first table if sheet/table are omitted.\nReturns: sheet name, table name, the headers and rows selected, and numRows/numCols describing the SELECTION \u2014 not the table. Use get-file-info for the table's full dimensions.\nDo not use when: you only need one cell \u2014 use get-cell; you need the file's structure/names \u2014 use get-file-info; or you want to find a value's location \u2014 use search.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().optional().describe("Sheet name (default: first sheet)"),
@@ -22470,7 +22476,7 @@ ${lines.join("\n")}`, {
 server.registerTool(
   "export-table",
   {
-    description: "Use when: you want to write a table's data out to a CSV, TSV, or JSON file on disk. Defaults to the first sheet and first table if sheet/table are omitted.\nReturns: the exported row count, format, and output path.\nDo not use when: you want the data inline in the response rather than a file \u2014 use read-table; or you want to build a new .numbers file from a CSV/TSV/JSON source \u2014 use import-csv.",
+    description: "Use when: you want to write a table's data out to a CSV, TSV, or JSON file on disk. Defaults to the first sheet and first table if sheet/table are omitted.\nReturns: the exported row count, format, and output path.\nDo not use when: you want the data inline in the response rather than a file \u2014 use read-table; or you want to build a new .numbers file from a CSV/TSV/JSON source \u2014 use import-csv.\nSafety: writes a file to disk at outputPath. The path is written unconditionally \u2014 any existing file there is OVERWRITTEN \u2014 so confirm the destination before calling.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       format: external_exports.enum(["csv", "tsv", "json"]).describe("Output format"),
@@ -22566,7 +22572,7 @@ server.registerTool(
     description: `Use when: you need to write a computed value to one cell in an existing .numbers file, addressed by 0-based row and column (header is row 0). Defaults to the first sheet/table if omitted.
 Returns: the written coordinates, value, and the sheet/table affected.
 Do not use when: you're writing many cells \u2014 use set-cells-batch; replacing whole rows \u2014 use update-rows; or writing a live formula \u2014 use set-formula (passing "=SUM(...)" here writes literal text, not a formula).
-Safety: modifies the .numbers file in place and OVERWRITES any existing data in the target cell.`,
+Safety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app) and OVERWRITES any existing data in the target cell.`,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       row: external_exports.number().int().min(0).max(MAX_INDEX).describe("Row index (0-based)"),
@@ -22598,7 +22604,7 @@ Safety: modifies the .numbers file in place and OVERWRITES any existing data in
 server.registerTool(
   "set-cells-batch",
   {
-    description: "Use when: you need to write computed values to multiple cells at once (each with 0-based row/col); more efficient than many set-cell calls. Defaults to the first sheet/table if omitted.\nReturns: the number of cells written and the sheet/table affected.\nDo not use when: replacing whole rows by index \u2014 use update-rows; appending new rows \u2014 use add-rows; or writing live formulas \u2014 use set-formulas-batch.\nSafety: modifies the .numbers file in place and OVERWRITES any existing data in the targeted cells.",
+    description: "Use when: you need to write computed values to multiple cells at once (each with 0-based row/col); more efficient than many set-cell calls. Defaults to the first sheet/table if omitted.\nReturns: the number of cells written and the sheet/table affected.\nDo not use when: replacing whole rows by index \u2014 use update-rows; appending new rows \u2014 use add-rows; or writing live formulas \u2014 use set-formulas-batch.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app) and OVERWRITES any existing data in the targeted cells.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       updates: external_exports.array(
@@ -22632,7 +22638,7 @@ server.registerTool(
 server.registerTool(
   "add-rows",
   {
-    description: "Use when: you want to append new rows of data to the end of an existing table; rows are added after the last existing row. Defaults to the first sheet/table if omitted.\nReturns: the number of rows added, the starting row index, and the new total row count.\nDo not use when: overwriting existing rows by index \u2014 use update-rows; setting individual cells \u2014 use set-cell / set-cells-batch.\nSafety: modifies the .numbers file in place. Additive (appends rows) and does not overwrite existing data, but still mutates the file.",
+    description: "Use when: you want to append new rows of data to the end of an existing table; rows are added after the last existing row. Defaults to the first sheet/table if omitted.\nReturns: the number of rows added, the starting row index, and the new total row count.\nDo not use when: overwriting existing rows by index \u2014 use update-rows; setting individual cells \u2014 use set-cell / set-cells-batch.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app). Additive (appends rows) and does not overwrite existing data, but still mutates the file.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       rows: external_exports.array(external_exports.array(external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]))).min(1).max(MAX_BATCH).describe(
@@ -22661,7 +22667,7 @@ server.registerTool(
 server.registerTool(
   "delete-rows",
   {
-    description: "Use when: you need to permanently remove a contiguous range of rows from a table; both startRow and endRow are 0-based inclusive indices (header is row 0). Defaults to the first sheet/table if omitted.\nReturns: the number of rows deleted and the new total row count.\nDo not use when: you only want to clear values while keeping the rows \u2014 use set-cells-batch with empty values; or overwrite rows in place \u2014 use update-rows.\nSafety: DESTRUCTIVE \u2014 requires explicit user confirmation; not undoable; the .numbers file is modified in place and the deleted rows cannot be recovered. Double-check the 0-based inclusive range before calling.",
+    description: "Use when: you need to permanently remove a contiguous range of rows from a table; both startRow and endRow are 0-based inclusive indices (header is row 0). Defaults to the first sheet/table if omitted.\nReturns: the number of rows deleted and the new total row count.\nDo not use when: you only want to clear values while keeping the rows \u2014 use set-cells-batch with empty values; or overwrite rows in place \u2014 use update-rows.\nSafety: DESTRUCTIVE \u2014 requires explicit user confirmation; not undoable; the .numbers file is modified in place via the numbers-parser sidecar (does not require Numbers.app) and the deleted rows cannot be recovered. Double-check the 0-based inclusive range before calling.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       startRow: external_exports.number().int().min(0).max(MAX_INDEX).describe("First row to delete (0-based, inclusive)"),
@@ -22688,7 +22694,7 @@ server.registerTool(
 server.registerTool(
   "add-sheet",
   {
-    description: "Use when: you want to add a new sheet to an existing .numbers file, optionally naming its default table and providing its headers.\nReturns: the new sheet name, its default table name, and the table's dimensions.\nDo not use when: adding a table to an existing sheet \u2014 use add-table; or creating a whole new file \u2014 use create-spreadsheet.\nSafety: modifies the .numbers file in place. Additive (adds a new sheet) and does not overwrite existing data, but still mutates the file.",
+    description: "Use when: you want to add a new sheet to an existing .numbers file, optionally naming its default table and providing its headers. Geometry depends on headers: with headers the table is created 1 row x headers.length columns; without them it is a 12 x 8 grid of empty cells (not overridable through MCP).\nReturns: the new sheet name, its default table name, and the table's dimensions.\nDo not use when: adding a table to an existing sheet \u2014 use add-table; or creating a whole new file \u2014 use create-spreadsheet.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app). Additive (adds a new sheet) and does not overwrite existing data, but still mutates the file.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheetName: external_exports.string().max(MAX_NAME_LEN).describe("Name for the new sheet"),
@@ -22714,7 +22720,7 @@ server.registerTool(
 server.registerTool(
   "add-table",
   {
-    description: "Use when: you want to add a new table to an existing sheet, optionally naming it and providing its headers. Defaults to the first sheet if omitted.\nReturns: the new table name, the sheet it was added to, and the table's dimensions.\nDo not use when: adding a whole new sheet \u2014 use add-sheet; or creating a new file \u2014 use create-spreadsheet.\nSafety: modifies the .numbers file in place. Additive (adds a new table) and does not overwrite existing data, but still mutates the file.",
+    description: "Use when: you want to add a new table to an existing sheet, optionally naming it and providing its headers. Defaults to the first sheet if omitted. Geometry depends on headers: with headers the table is created 1 row x headers.length columns; without them it is a 12 x 8 grid of empty cells (not overridable through MCP).\nReturns: the new table name, the sheet it was added to, and the table's dimensions.\nDo not use when: adding a whole new sheet \u2014 use add-sheet; or creating a new file \u2014 use create-spreadsheet.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app). Additive (adds a new table) and does not overwrite existing data, but still mutates the file.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().optional().describe("Sheet name (default: first sheet)"),
@@ -22740,7 +22746,7 @@ server.registerTool(
 server.registerTool(
   "import-csv",
   {
-    description: "Use when: you want to convert an existing CSV, TSV, or JSON file into a new .numbers spreadsheet. Format is auto-detected from the input file extension unless you specify it explicitly.\nReturns: the imported row and column counts, detected format, and the input/output paths plus sheet/table names.\nDo not use when: building a file from headers/rows you already have in hand \u2014 use create-spreadsheet; or exporting a .numbers table out to CSV/TSV/JSON \u2014 use export-table.\nSafety: writes the output .numbers file via the numbers-parser sidecar (does not require Numbers.app). The output path is written unconditionally \u2014 if a file already exists there it is OVERWRITTEN in place; choose a fresh output path or confirm overwrite first.",
+    description: 'Use when: you want to convert an existing CSV, TSV, or JSON file into a new .numbers spreadsheet. Format is auto-detected from the input file extension unless you specify it explicitly; any unrecognized extension falls back to CSV. CSV/TSV fields are auto-typed (numbers, booleans, empty cells), so zero-padded identifiers LOSE their leading zeros \u2014 "01234" becomes 1234. JSON values are passed through untouched, but an array of objects takes its column set from the FIRST object only, silently dropping keys that appear later.\nReturns: the imported row and column counts, detected format, and the input/output paths plus sheet/table names.\nDo not use when: building a file from headers/rows you already have in hand \u2014 use create-spreadsheet; or exporting a .numbers table out to CSV/TSV/JSON \u2014 use export-table.\nSafety: writes the output .numbers file via the numbers-parser sidecar (does not require Numbers.app). The output path is written unconditionally \u2014 if a file already exists there it is OVERWRITTEN in place; choose a fresh output path or confirm overwrite first.',
     inputSchema: {
       inputPath: external_exports.string().describe("Path to the CSV/TSV/JSON input file"),
       outputPath: external_exports.string().describe("Path for the output .numbers file"),
@@ -22772,7 +22778,7 @@ Sheet: "${result.sheetName}" | Table: "${result.tableName}"`,
 server.registerTool(
   "update-rows",
   {
-    description: "Use when: you need to replace whole rows by 0-based index in an existing file; each update carries a row index and a complete array of column values. Carrying multiple {row, values} entries is more efficient than per-row writes. Defaults to the first sheet/table if omitted.\nReturns: the number of rows updated and the sheet/table affected.\nDo not use when: appending new rows \u2014 use add-rows; writing individual cells \u2014 use set-cell / set-cells-batch; or writing live formulas \u2014 use set-formulas-batch.\nSafety: modifies the .numbers file in place and OVERWRITES the entire contents of each targeted row.",
+    description: "Use when: you need to replace whole rows by 0-based index in an existing file; each update carries a row index and a complete array of column values. Carrying multiple {row, values} entries is more efficient than per-row writes. Defaults to the first sheet/table if omitted.\nReturns: the number of rows updated and the sheet/table affected.\nDo not use when: appending new rows \u2014 use add-rows; writing individual cells \u2014 use set-cell / set-cells-batch; or writing live formulas \u2014 use set-formulas-batch.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app) and OVERWRITES the entire contents of each targeted row.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       updates: external_exports.array(
@@ -22852,7 +22858,7 @@ server.registerTool(
 server.registerTool(
   "set-formula",
   {
-    description: 'Use when: you need to write a live formula (e.g. "=SUM(A2:A10)") into a cell so it computes in Numbers, addressed by 0-based row/col. Requires explicit sheet and table.\nReturns: the cell, the formula set, and its computed value.\nDo not use when: writing a plain computed value \u2014 use set-cell (this tool is for live formulas); or setting many formulas \u2014 use set-formulas-batch.\nSafety: drives Numbers.app via AppleScript and requires Numbers.app to be running plus Automation permission. The file is opened if not already open, the formula OVERWRITES any existing content in the target cell, and the file is saved in place.',
+    description: 'Use when: you need to write a live formula (e.g. "=SUM(A2:A10)") into a cell so it computes in Numbers, addressed by 0-based row/col. Requires explicit sheet and table.\nReturns: the cell, the formula set, and its computed value.\nDo not use when: writing a plain computed value \u2014 use set-cell (this tool is for live formulas); or setting many formulas \u2014 use set-formulas-batch.\nSafety: drives Numbers.app via AppleScript and requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. The file is opened in Numbers.app if not already open, launching the app; the formula OVERWRITES any existing content in the target cell; the WHOLE document is saved, which commits any unsaved edits the user has open in it; and the document is left open afterwards.',
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -22883,7 +22889,7 @@ Computed value: ${result.computedValue}`,
 server.registerTool(
   "set-formulas-batch",
   {
-    description: "Use when: you need to write live formulas to multiple cells at once (each with 0-based row/col); more efficient than many set-formula calls. Requires explicit sheet and table.\nReturns: the number of formulas set and the sheet/table affected.\nDo not use when: writing plain computed values \u2014 use set-cells-batch; or setting a single formula \u2014 use set-formula.\nSafety: drives Numbers.app via AppleScript and requires Numbers.app to be running plus Automation permission. Modifies the file in place and OVERWRITES any existing content in the targeted cells.",
+    description: "Use when: you need to write live formulas to multiple cells at once (each with 0-based row/col); more efficient than many set-formula calls. Requires explicit sheet and table.\nReturns: the number of formulas set and the sheet/table affected.\nDo not use when: writing plain computed values \u2014 use set-cells-batch; or setting a single formula \u2014 use set-formula.\nSafety: drives Numbers.app via AppleScript and requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. Opens the file in Numbers.app if it isn't open already, launching the app; OVERWRITES any existing content in the targeted cells; saves the WHOLE document, which commits any unsaved edits the user has open in it; and leaves the document open afterwards.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -22941,7 +22947,7 @@ var cellStyleSchema = external_exports.object({
 server.registerTool(
   "set-cell-style",
   {
-    description: "Use when: you need to format one cell \u2014 font, text/background color, number format, alignment, text wrap \u2014 addressed by 0-based row/col. Requires explicit sheet and table.\nReturns: the styled cell and the sheet/table affected.\nDo not use when: styling many cells \u2014 use set-cells-style-batch; or writing a value/formula rather than formatting \u2014 use set-cell / set-formula.\nSafety: drives Numbers.app via AppleScript \u2014 modifies the file in place and requires Numbers.app to be running plus Automation permission.",
+    description: "Use when: you need to format one cell \u2014 font, text/background color, number format, alignment, text wrap \u2014 addressed by 0-based row/col. Requires explicit sheet and table.\nReturns: the styled cell and the sheet/table affected.\nDo not use when: styling many cells \u2014 use set-cells-style-batch; or writing a value/formula rather than formatting \u2014 use set-cell / set-formula.\nSafety: drives Numbers.app via AppleScript \u2014 requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. Opens the file in Numbers.app if it isn't open already, launching the app; modifies it in place; saves the WHOLE document, which commits any unsaved edits the user has open in it; and leaves the document open afterwards.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -22968,7 +22974,7 @@ server.registerTool(
 server.registerTool(
   "set-cells-style-batch",
   {
-    description: "Use when: you need to format multiple cells at once (each with 0-based row/col); more efficient than many set-cell-style calls. Requires explicit sheet and table.\nReturns: the number of cells styled and the sheet/table affected.\nDo not use when: styling a single cell \u2014 use set-cell-style; or writing values/formulas rather than formatting \u2014 use set-cells-batch / set-formulas-batch.\nSafety: drives Numbers.app via AppleScript \u2014 modifies the file in place and requires Numbers.app to be running plus Automation permission.",
+    description: "Use when: you need to format multiple cells at once (each with 0-based row/col); more efficient than many set-cell-style calls. Requires explicit sheet and table.\nReturns: the number of cells styled and the sheet/table affected.\nDo not use when: styling a single cell \u2014 use set-cell-style; or writing values/formulas rather than formatting \u2014 use set-cells-batch / set-formulas-batch.\nSafety: drives Numbers.app via AppleScript \u2014 requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. Opens the file in Numbers.app if it isn't open already, launching the app; modifies it in place; saves the WHOLE document, which commits any unsaved edits the user has open in it; and leaves the document open afterwards.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -22999,7 +23005,7 @@ server.registerTool(
 server.registerTool(
   "set-column-width",
   {
-    description: "Use when: you need to set a column's width in pixels, addressed by 0-based column index. Requires explicit sheet and table.\nReturns: the column index and the width applied.\nDo not use when: setting a row's height \u2014 use set-row-height.\nSafety: drives Numbers.app via AppleScript \u2014 modifies the file in place and requires Numbers.app to be running plus Automation permission.",
+    description: "Use when: you need to set a column's width in pixels, addressed by 0-based column index. Requires explicit sheet and table.\nReturns: the column index and the width applied.\nDo not use when: setting a row's height \u2014 use set-row-height.\nSafety: drives Numbers.app via AppleScript \u2014 requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. Opens the file in Numbers.app if it isn't open already, launching the app; modifies it in place; saves the WHOLE document, which commits any unsaved edits the user has open in it; and leaves the document open afterwards.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23029,7 +23035,7 @@ server.registerTool(
 server.registerTool(
   "set-row-height",
   {
-    description: "Use when: you need to set a row's height in pixels, addressed by 0-based row index. Requires explicit sheet and table.\nReturns: the row index and the height applied.\nDo not use when: setting a column's width \u2014 use set-column-width.\nSafety: drives Numbers.app via AppleScript \u2014 modifies the file in place and requires Numbers.app to be running plus Automation permission.",
+    description: "Use when: you need to set a row's height in pixels, addressed by 0-based row index. Requires explicit sheet and table.\nReturns: the row index and the height applied.\nDo not use when: setting a column's width \u2014 use set-column-width.\nSafety: drives Numbers.app via AppleScript \u2014 requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. Opens the file in Numbers.app if it isn't open already, launching the app; modifies it in place; saves the WHOLE document, which commits any unsaved edits the user has open in it; and leaves the document open afterwards.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23059,7 +23065,7 @@ server.registerTool(
 server.registerTool(
   "merge-cells",
   {
-    description: "Use when: you need to merge a rectangular range of cells into one, given 0-based inclusive top-left and bottom-right coordinates. Requires explicit sheet and table.\nReturns: the merged range and the sheet/table affected.\nDo not use when: undoing a merge \u2014 use unmerge-cells.\nSafety: drives Numbers.app via AppleScript \u2014 modifies the file in place and requires Numbers.app to be running plus Automation permission. Merging keeps only the top-left cell's content and can DROP the values in the other cells of the range.",
+    description: "Use when: you need to merge a rectangular range of cells into one, given 0-based inclusive top-left and bottom-right coordinates. Requires explicit sheet and table.\nReturns: the merged range and the sheet/table affected.\nDo not use when: undoing a merge \u2014 use unmerge-cells.\nSafety: drives Numbers.app via AppleScript \u2014 requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. Opens the file in Numbers.app if it isn't open already, launching the app; modifies it in place; saves the WHOLE document, which commits any unsaved edits the user has open in it; and leaves the document open afterwards. Merging keeps only the top-left cell's content and can DROP the values in the other cells of the range.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23086,7 +23092,7 @@ server.registerTool(
 server.registerTool(
   "unmerge-cells",
   {
-    description: "Use when: you need to split a previously merged range back into individual cells, given 0-based inclusive top-left and bottom-right coordinates. Requires explicit sheet and table.\nReturns: the unmerged range and the sheet/table affected.\nDo not use when: creating a merge \u2014 use merge-cells.\nSafety: drives Numbers.app via AppleScript \u2014 modifies the file in place and requires Numbers.app to be running plus Automation permission. Previously merged cells stay empty (the original non-top-left values are not restored).",
+    description: "Use when: you need to split a previously merged range back into individual cells, given 0-based inclusive top-left and bottom-right coordinates. Requires explicit sheet and table.\nReturns: the unmerged range and the sheet/table affected.\nDo not use when: creating a merge \u2014 use merge-cells.\nSafety: drives Numbers.app via AppleScript \u2014 requires Numbers.app INSTALLED (it need not already be running) plus Automation permission. Opens the file in Numbers.app if it isn't open already, launching the app; modifies it in place; saves the WHOLE document, which commits any unsaved edits the user has open in it; and leaves the document open afterwards. Previously merged cells stay empty (the original non-top-left values are not restored).",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),

package/docs/AUTOMATION-PERMISSION.md

@@ -1,12 +1,15 @@
-# Automation Permission for Write & Format Operations
+# Automation Permission for Formula & Formatting 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**.
+special macOS permission. The split is **values vs. formatting**, not read vs.
+write:
+
+- **Reads and value/structure writes** 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. No Apple event is ever sent, so Numbers.app doesn't
+  even have to be installed.
+- **Formulas 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.
@@ -16,51 +19,50 @@ 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):
+**Need it** (AppleScript → Numbers.app — formulas, styles, dimensions, merges):
 
-- `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):
+**Do NOT need it** (pure numbers-parser, the file opened directly off disk):
 
-- `get-file-info`
-- `read-table`
-- `get-cell`
-- `search`
-- `export-table`
+- Reads — `get-file-info`, `read-table`, `get-cell`, `search`, `export-table`
+- Value writes — `set-cell`, `set-cells-batch`, `add-rows`, `update-rows`,
+  `delete-rows`
+- Structure writes — `add-sheet`, `add-table`, `rename-sheet`, `rename-table`
+- File creation — `create-spreadsheet`, `import-csv`
 - `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.
+So you can inspect, search, export **and edit** a spreadsheet — cell values, whole
+rows, sheets and tables, new files from CSV — with no Automation permission at all,
+and with Numbers.app not installed. The permission only matters the moment you
+write a **live formula** or change **formatting** (font, color, number format,
+alignment, column width, row height, merges).
 
-> **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.
+> **Numbers.app must be installed for the formula/format tools.** Only that path
+> scripts Numbers.app, so the app has to be present at `/Applications/Numbers.app`
+> (or `/System/Applications/Numbers.app`). Reads and the numbers-parser writes
+> don't need it. If Numbers.app is missing, `doctor` reports `numbers_app: warn`
+> and only the formula/format tools fail.
 
 ## How the permission prompt appears
 
-The **first time** a write/format tool runs, macOS shows a one-time dialog:
+The **first time** a formula or formatting 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
+Click **OK / Allow**. The grant is remembered, so subsequent calls 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.
+If the host app runs headless or the dialog is dismissed/denied, the
+formula/format call fails (see below) and you must grant the permission manually.
+Value and structure writes are unaffected — they never send an Apple event.
 
 ## How to grant it manually
 
@@ -85,7 +87,7 @@ If the host app runs headless or the dialog is dismissed/denied, the write fails
 ## 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:
+fails and the formula/format tool returns an error containing:
 
 ```
 Not authorized to send Apple events to Numbers.
@@ -95,9 +97,10 @@ Not authorized to send Apple events to Numbers.
 `"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.
+If you instead see an error saying Numbers can't be found or isn't running, the
+problem is that the app isn't installed/openable — install Numbers.app and retry.
+(The tools do **not** require Numbers.app to already be running: the AppleScript
+layer launches it and opens the file itself. It does have to be *installed*.)
 
 ## Resetting the permission
 
@@ -117,8 +120,10 @@ e.g.:
 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.
+After resetting, **fully quit and reopen the host app**, then run any
+formula/format tool (e.g. `set-cell-style`) and click **OK** when the dialog
+appears. A value write such as `set-cell` will *not* re-trigger the prompt — it
+never crosses the AppleScript boundary.
 
 ## Verifying
 
@@ -128,20 +133,26 @@ 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.
+- **`numbers_app`** — is Numbers.app present (required for the formula/format
+  tools; everything else works without it).
+- **`automation_permission`** — an informational reminder that the formula/format
+  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.
+> tool that actually crosses the AppleScript boundary — e.g. `set-cell-style` (or
+> `set-formula`) 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.
+>
+> **Don't test with `set-cell`** (or any other value/structure write). Those run
+> on the numbers-parser sidecar and succeed whether or not the grant exists, so
+> they always "pass" and tell you nothing about the permission.
 
 ## See also
 
-- [docs/LIMITATIONS.md](./LIMITATIONS.md) — the full read-vs-write split and other
+- [docs/LIMITATIONS.md](./LIMITATIONS.md) — the full backend 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

@@ -1,32 +1,38 @@
 # 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.
+them *and writes their values and structure* offline with
+[numbers-parser](https://pypi.org/project/numbers-parser/) (Python, no app
+required), and **formats** them — styles, live formulas, column/row dimensions,
+merges — by scripting **Numbers.app** via AppleScript (because numbers-parser
+can't write those). That split is the source of most of the limitations below.
+Note it is a **values-vs-formatting** split, not a read-vs-write one.
 
 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 & formatting require Numbers.app + Automation permission (nothing else does)
+
+**Why:** numbers-parser can read a `.numbers` file directly off disk *and* write
+values, rows, sheets and tables into it — but it does **not** write styles,
+formulas, or cell-dimension changes reliably. To do those, the server scripts
+**Numbers.app** through AppleScript. That means the eight formula/format tools
+need (a) **Numbers.app installed** and (b) the host app to have **Automation**
+permission to control Numbers. Every other tool — the reads (`get-file-info`,
+`read-table`, `get-cell`, `search`, `export-table`) *and* the value/structure
+writes (`set-cell(s)`, `add/update/delete-rows`, `add-sheet`/`add-table`,
+`rename-*`, `create-spreadsheet`, `import-csv`) — uses only numbers-parser and
+needs **neither**: no Numbers.app, no Automation grant, no Apple event.
+
+**What to do:** For inspection/search/export, and for ordinary value and structure
+edits, nothing special is needed. Only for `set-formula(s)`, `set-*-style`,
+`set-column-width`/`set-row-height` and `merge`/`unmerge` do you have to install
+Numbers.app and grant Automation permission. Full steps in
+[AUTOMATION-PERMISSION.md](./AUTOMATION-PERMISSION.md). Verify with `doctor` — and
+test the grant with a *formula/format* tool, since a `set-cell` succeeds without
+it and so proves nothing.
 
 ## Formulas and styling are AppleScript-only
 
@@ -37,9 +43,11 @@ 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.
+**What to do:** Run formula/format tools on macOS with Numbers.app installed.
+Where only the Python path is available, you can still *read* formulas and
+formatted values (via `get-cell verbose: true`) — you just can't set them. Note
+the npm package declares `os: ["darwin"]`, so Linux isn't a supported install
+target even for that read-only subset (see "macOS only" below).
 
 ## Values vs. formulas
 
@@ -50,6 +58,40 @@ 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.
 
+## `import-csv` auto-types CSV/TSV fields, so leading zeros are lost
+
+**Why:** For a `csv` or `tsv` source, every field is passed through the sidecar's
+`_auto_convert()` before it is written: `""` becomes an empty cell, `true`/`false`
+become booleans, and anything Python's `int()` or `float()` accepts becomes a
+number. That is deliberately *less* conservative than the value-write tools
+(`set-cell`, `set-cells-batch`, `add-rows`, `update-rows`), which reject
+leading-zero integers so identifier-like strings keep their exact text. So a zip
+code `01234` imports as the number `1234`, `007` imports as `7`, and a part number
+`1e5` imports as the number `100000`. There is no per-column type control on import, and the
+conversion isn't reversible once the `.numbers` file is written.
+
+A `json` source does **not** do this — those values go straight through, so a JSON
+string `"01234"` survives intact.
+
+**What to do:** For CSV/TSV columns holding zero-padded identifiers, import from
+JSON instead, or repair the affected cells after import with `set-cells-batch`
+using `type: "string"`. Spot-check with `get-cell` after importing anything
+identifier-like.
+
+## `import-csv` takes its JSON columns from the first object only
+
+**Why:** For an array-of-objects JSON source the column set is the keys of the
+**first** object. A key that appears only in a later object is dropped silently,
+and objects missing an early key get blank cells. An array-of-arrays source has no
+header names at all: columns are named `Column_0`, `Column_1`, … and the first row
+is kept as data. Separately, when `format` is `auto`, any extension that isn't
+`.csv`, `.tsv` or `.json` falls back to **CSV** rather than erroring.
+
+**What to do:** Normalize a heterogeneous JSON export to a common key set before
+importing, and pass `format` explicitly for inputs whose extension isn't one of the
+three recognized ones. The tool's response reports the format it actually used and
+the column count it produced — check both when the input is unusual.
+
 ## No charts, images, or conditional formatting
 
 **Why:** numbers-parser doesn't expose charts, embedded images, or
@@ -105,24 +147,41 @@ upgrade numbers-parser first. Check the installed version with `health-check` /
 
 ## 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.
+**Why:** Two backends can touch the same file. The numbers-parser path (reads and
+value/structure writes) sees whatever is on disk; the formula/format path drives
+Numbers.app. If Numbers.app has the file **open with unsaved changes**, what
+numbers-parser reads off disk can be stale, and an AppleScript call targets the
+app's in-memory copy — the two can disagree, and saves can race.
+
+Three side effects of the AppleScript path matter here, because they apply to
+**every** formula/format tool:
+
+1. **It opens the file itself**, launching Numbers.app if it isn't running. These
+   tools don't require Numbers.app to already be running — only *installed* — so a
+   single `set-column-width` on an idle Mac can pop a window and, the first time,
+   the Automation prompt.
+2. **It saves the whole document, not just the change.** If you have the workbook
+   open in Numbers with unsaved hand edits, one formula/format call commits *all*
+   of them to disk.
+3. **It leaves the document open** afterwards — nothing ever closes it — so every
+   later numbers-parser read or write on that file races the app's in-memory copy,
+   which is exactly the hazard this section describes.
 
 **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,
+bulk writes through the server, so disk and app agree — and close it again after a
+run of formula/format calls, which will have reopened it. 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
+in-memory document, and saves the **whole document** back. On the numbers-parser
+path the save is **atomic** — every mutating sidecar 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. (The formula/format tools save
+through Numbers.app instead, so that guarantee is the app's, not this server's.)
+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
@@ -135,11 +194,33 @@ related edits into a single call (`set-cells-batch`, `update-rows`,
 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
+## Per-call timeouts are fixed (30 s sidecar, 60 s AppleScript)
+
+**Why:** Every numbers-parser sidecar call runs under a **30-second** process
+timeout, and every AppleScript call under **60 seconds** (the generated script also
+carries an in-app `with timeout` block set 5 s lower, so Numbers.app aborts cleanly
+before the process is killed). Neither is configurable — there is no
+`APPLE_NUMBERS_MCP_*` variable for either one.
+`APPLE_NUMBERS_MCP_SETUP_TIMEOUT` governs only the one-time venv bootstrap, and
+`APPLE_NUMBERS_MCP_MAX_BUFFER` caps stdout size, not wall-clock time. A very large
+workbook, or a wedged Numbers.app, surfaces as `Operation timed out after
+30000ms. File may be very large.`
+
+**What to do:** Narrow the request rather than hunting for a knob: read in slices
+with `read-table`'s `startRow`/`endRow` and `columns`, split large
+`set-cells-batch` / `update-rows` calls into smaller batches, and close the file in
+Numbers.app so the AppleScript layer isn't waiting on the app.
+
+## macOS only (the package declares `os: ["darwin"]`)
+
+**Why:** The published npm package declares `"os": ["darwin"]`, so `npm`/`pnpm`
+refuse to install it on any other platform (`EBADPLATFORM`). The numbers-parser
+path — reads plus value/structure writes — is platform-independent in principle
+(nothing in the sidecar branches on the platform), but the formula/format tools
+script Numbers.app, which exists only on macOS, so the package as a whole is
+pinned to darwin deliberately.
+
+**What to do:** Run this server on a Mac. Add Numbers.app plus Automation
+permission only if you need formulas or formatting; reads and value/structure
+writes need neither. See
 [AUTOMATION-PERMISSION.md](./AUTOMATION-PERMISSION.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-numbers-mcp",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "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",
@@ -87,6 +87,6 @@
     "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 .agents/plugins codex .hermes-plugin .antigravity-plugin"
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin .agents/plugins codex .antigravity-plugin"
   }
 }