apple-numbers-mcp 1.1.19 → 1.2.1

package/README.md

@@ -675,6 +675,7 @@ All configuration is optional — the server works out of the box.
 | `APPLE_NUMBERS_MCP_MAX_BUFFER` | 50 MB (Python reader) / 64 MB (AppleScript) | Max bytes captured from a subprocess's stdout, applied to both the Python reader and the AppleScript layer. Raise it if a very large spreadsheet is truncated; lower it to cap memory. |
 | `APPLE_NUMBERS_MCP_CONFIG_FILE` | `~/Library/Application Support/apple-numbers-mcp/config.json` | Path to the JSON config file (see below). |
 | `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_EXTRA_ROOTS` | unset | Colon-separated **absolute** directories to add to the allowed-path roots, e.g. `/Data/Finance:/srv/shared`. The built-in roots already cover your home directory, the temp dirs and `/Volumes` (where external and network mounts appear), so this is for genuinely unusual layouts rather than routine configuration. Entries are canonicalized like the built-ins, so a symlinked entry cannot smuggle in a wider parent; relative and empty entries are ignored. **Widening a security boundary — set it deliberately.** |
 | `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
@@ -775,9 +776,10 @@ These are tracked for future releases. The underlying `numbers-parser` library h
 - Ensure the file extension is `.numbers`.
 
 ### "Output path … is outside the allowed roots" / "Input path … is outside the allowed roots"
-- `export-table`, `create-spreadsheet` and `import-csv` read and write ordinary files, so their paths are restricted to your **home directory**, `/tmp`, `/private/tmp`, and `/Volumes` — the server will not write into `/etc`, `/Library`, an app bundle, or any other system location, and will not read a source file from one.
+- Every tool that touches a file on disk is bounded to your **home directory**, `/tmp`, `/private/tmp`, and `/Volumes` — the server will not write into `/etc`, `/Library`, an app bundle, or any other system location, and will not read from one.
+- **As of 1.2.0 this covers the `.numbers` file itself**, not just export/import destinations. `get-file-info`, `read-table`, `search` and the in-place writes (`set-cell`, `add-rows`, `set-formula`, …) previously accepted a path anywhere on disk.
 - Symlinks are resolved **before** the check, so a link inside an allowed directory that points outside it is rejected too; the error reports the resolved path, which is usually the quickest way to see where a path really went.
-- Fix: choose a path under one of those roots (`~/Documents/report.csv`, `/tmp/report.csv`). There is no override setting.
+- Fix: choose a path under one of those roots (`~/Documents/report.numbers`, `/tmp/report.csv`). If your spreadsheets genuinely live somewhere else, add that directory to `APPLE_NUMBERS_MCP_EXTRA_ROOTS` — see [Environment variables](#environment-variables).
 
 ### 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.

package/build/index.js

@@ -21813,8 +21813,7 @@ function unmergeCells(filePath, sheet, table, startRow, startCol, endRow, endCol
 
 // src/services/numbersManager.ts
 import { existsSync as existsSync3 } from "node:fs";
-import { resolve as resolve2, extname } from "node:path";
-import { homedir as homedir2 } from "node:os";
+import { extname } from "node:path";
 
 // src/utils/exportPath.ts
 import { lstatSync, readlinkSync, realpathSync } from "node:fs";
@@ -21833,12 +21832,18 @@ var ALLOWED_EXPORT_ROOTS = [
   "/Volumes"
 ];
 var ALLOWED_EXPORT_ROOTS_TEXT = "your home directory, /tmp, /private/tmp, or /Volumes";
+var EXTRA_ROOTS_ENV = "APPLE_NUMBERS_MCP_EXTRA_ROOTS";
+function extraRoots() {
+  const raw = process.env[EXTRA_ROOTS_ENV];
+  if (!raw) return [];
+  return raw.split(":").map((s) => s.trim()).filter((s) => s.length > 0 && isAbsolute(s));
+}
 function canonicalize(path) {
   return realpathSync.native(path);
 }
 function allowedRoots() {
   const roots = [];
-  for (const root of ALLOWED_EXPORT_ROOTS) {
+  for (const root of [...ALLOWED_EXPORT_ROOTS, ...extraRoots()]) {
     if (!roots.includes(root)) roots.push(root);
     try {
       const canonical = canonicalize(root);
@@ -21912,9 +21917,32 @@ function resolveWithinAllowedRoots(path, label) {
 
 // src/services/numbersManager.ts
 var NumbersManager = class {
+  /**
+   * Resolve and validate the path of an EXISTING `.numbers` file.
+   *
+   * This is the resolver behind `get-file-info`, `read-table`, `search` and
+   * every in-place write (`set-cell`, `add-rows`, `set-formula`, …). It used to
+   * expand `~`, `resolve()` and check the extension — and nothing else — so
+   * those tools could read and modify a `.numbers` file **anywhere on disk**,
+   * while its sibling `validateOutputPath` had enforced the allowed-roots
+   * boundary since 1.1.19. That asymmetry was the largest remaining gap here.
+   *
+   * It now goes through the same `resolveWithinAllowedRoots` as the write side,
+   * which also brings the hardening that came with it: canonicalization via
+   * `realpathSync.native` (so a case-respelled segment cannot defeat the check
+   * on case-insensitive APFS) and symlink resolution BEFORE the comparison (so
+   * a link inside an allowed directory cannot point out of it).
+   *
+   * The extension is checked on the CANONICAL path for the same reason it is on
+   * the output side: a symlink must not be able to present a `.numbers` name
+   * for a target that is something else entirely.
+   *
+   * The built-in roots cover home, the temp dirs and `/Volumes`, so a file the
+   * user could plausibly want to open is almost always already inside them.
+   * `APPLE_NUMBERS_MCP_EXTRA_ROOTS` exists for the layouts they are not.
+   */
   validatePath(filePath) {
-    const expanded = filePath.startsWith("~") ? filePath.replace(/^~/, homedir2()) : filePath;
-    const resolved = resolve2(expanded);
+    const resolved = resolveWithinAllowedRoots(filePath, "Input path");
     if (!existsSync3(resolved)) {
       throw new Error(`File not found: ${resolved}`);
     }
@@ -22444,11 +22472,11 @@ First use get-file-info and read-table to read the relevant table(s) so you know
 // src/services/fileConfig.ts
 import { existsSync as existsSync5, readFileSync as readFileSync2 } from "node:fs";
 import { join as join3 } from "node:path";
-import { homedir as homedir3 } from "node:os";
+import { homedir as homedir2 } from "node:os";
 function fileConfigPath(env = process.env) {
   const override = env.APPLE_NUMBERS_MCP_CONFIG_FILE;
   if (override && override.trim()) return override.trim();
-  return join3(homedir3(), "Library", "Application Support", "apple-numbers-mcp", "config.json");
+  return join3(homedir2(), "Library", "Application Support", "apple-numbers-mcp", "config.json");
 }
 function loadFileConfig(env = process.env, path = fileConfigPath(env)) {
   const applied = [];
@@ -22595,6 +22623,8 @@ var MAX_NAME_LEN = 1024;
 var MAX_QUERY_LEN = 1e4;
 var MAX_HEADER_LEN = 1024;
 var headerCellSchema = external_exports.string().max(MAX_HEADER_LEN);
+var PATH_BOUNDARY_NOTE = `
+Paths: the file must resolve \u2014 after ~ expansion and symlink resolution \u2014 to a location under ${ALLOWED_EXPORT_ROOTS_TEXT}; anything else is rejected with an error naming those roots. Add directories with the ${EXTRA_ROOTS_ENV} environment variable.`;
 var server = new McpServer({
   name: "apple-numbers",
   version: version2,
@@ -22649,7 +22679,7 @@ registerTool(
 registerTool(
   "get-file-info",
   {
-    description: "Use when: you need to discover the structure of a .numbers file before reading or writing \u2014 the exact sheet and table names, their dimensions, and header rows. Call this first when sheet/table names are unknown.\nReturns: each sheet with its tables, per-table row\xD7col counts, and the header row (row 0) cells.\nDo not use when: you want the actual cell data \u2014 use read-table; or a single cell \u2014 use get-cell.",
+    description: "Use when: you need to discover the structure of a .numbers file before reading or writing \u2014 the exact sheet and table names, their dimensions, and header rows. Call this first when sheet/table names are unknown.\nReturns: each sheet with its tables, per-table row\xD7col counts, and the header row (row 0) cells.\nDo not use when: you want the actual cell data \u2014 use read-table; or a single cell \u2014 use get-cell." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Absolute or ~-relative path to the .numbers file")
     },
@@ -22693,7 +22723,7 @@ ${summary}`,
 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, 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().optional().describe("Sheet name (default: first sheet)"),
@@ -22729,7 +22759,7 @@ ${dataRows}`,
 registerTool(
   "search",
   {
-    description: "Use when: you need to locate where a text value appears across every cell in a .numbers file (case-insensitive partial match), optionally limited to one sheet.\nReturns: a match count and each match's sheet, table, row, column header, and value.\nDo not use when: you already know the cell's coordinates \u2014 use get-cell; or you want a whole table's contents \u2014 use read-table.",
+    description: "Use when: you need to locate where a text value appears across every cell in a .numbers file (case-insensitive partial match), optionally limited to one sheet.\nReturns: a match count and each match's sheet, table, row, column header, and value.\nDo not use when: you already know the cell's coordinates \u2014 use get-cell; or you want a whole table's contents \u2014 use read-table." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       query: external_exports.string().max(MAX_QUERY_LEN).describe("Text to search for (case-insensitive)"),
@@ -22795,7 +22825,7 @@ registerTool(
 registerTool(
   "get-cell",
   {
-    description: "Use when: you need a single cell's value by 0-based row and column index (header is row 0). Set verbose=true to also get the formula, formatted value, and merge info.\nReturns: the cell's value and type, plus formula/formatted-value/merge details when verbose.\nDo not use when: you want many cells or whole rows \u2014 use read-table; or you don't know the coordinates \u2014 use search.",
+    description: "Use when: you need a single cell's value by 0-based row and column index (header is row 0). Set verbose=true to also get the formula, formatted value, and merge info.\nReturns: the cell's value and type, plus formula/formatted-value/merge details when verbose.\nDo not use when: you want many cells or whole rows \u2014 use read-table; or you don't know the coordinates \u2014 use search." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -22864,7 +22894,7 @@ 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 via the numbers-parser sidecar (does not require Numbers.app) 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.` + PATH_BOUNDARY_NOTE,
     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)"),
@@ -22896,7 +22926,7 @@ Safety: modifies the .numbers file in place via the numbers-parser sidecar (does
 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 via the numbers-parser sidecar (does not require Numbers.app) 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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       updates: external_exports.array(
@@ -22930,7 +22960,7 @@ registerTool(
 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 via the numbers-parser sidecar (does not require Numbers.app). 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." + PATH_BOUNDARY_NOTE,
     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(
@@ -22959,7 +22989,7 @@ registerTool(
 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 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.",
+    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." + PATH_BOUNDARY_NOTE,
     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)"),
@@ -22986,7 +23016,7 @@ registerTool(
 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. 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.",
+    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." + PATH_BOUNDARY_NOTE,
     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"),
@@ -23012,7 +23042,7 @@ registerTool(
 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. 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().optional().describe("Sheet name (default: first sheet)"),
@@ -23070,7 +23100,7 @@ Sheet: "${result.sheetName}" | Table: "${result.tableName}"`,
 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 via the numbers-parser sidecar (does not require Numbers.app) 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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       updates: external_exports.array(
@@ -23102,7 +23132,7 @@ registerTool(
 registerTool(
   "rename-sheet",
   {
-    description: "Use when: you want to change a sheet's name in a .numbers file. Defaults to the first sheet if the current name is omitted.\nReturns: the old and new sheet names.\nDo not use when: renaming a table \u2014 use rename-table.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app).",
+    description: "Use when: you want to change a sheet's name in a .numbers file. Defaults to the first sheet if the current name is omitted.\nReturns: the old and new sheet names.\nDo not use when: renaming a table \u2014 use rename-table.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app)." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       newName: external_exports.string().max(MAX_NAME_LEN).describe("New name for the sheet"),
@@ -23125,7 +23155,7 @@ registerTool(
 registerTool(
   "rename-table",
   {
-    description: "Use when: you want to change a table's name in a .numbers file. Defaults to the first sheet/table if omitted.\nReturns: the old and new table names and the sheet it belongs to.\nDo not use when: renaming a sheet \u2014 use rename-sheet.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app).",
+    description: "Use when: you want to change a table's name in a .numbers file. Defaults to the first sheet/table if omitted.\nReturns: the old and new table names and the sheet it belongs to.\nDo not use when: renaming a sheet \u2014 use rename-sheet.\nSafety: modifies the .numbers file in place via the numbers-parser sidecar (does not require Numbers.app)." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       newName: external_exports.string().max(MAX_NAME_LEN).describe("New name for the table"),
@@ -23150,7 +23180,7 @@ registerTool(
 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 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.',
+    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.' + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23181,7 +23211,7 @@ Computed value: ${result.computedValue}`,
 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 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23239,7 +23269,7 @@ var cellStyleSchema = external_exports.object({
 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 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23266,7 +23296,7 @@ registerTool(
 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 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23297,7 +23327,7 @@ registerTool(
 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 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23327,7 +23357,7 @@ registerTool(
 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 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23357,7 +23387,7 @@ registerTool(
 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 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.",
+    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." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),
@@ -23384,7 +23414,7 @@ registerTool(
 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 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).",
+    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)." + PATH_BOUNDARY_NOTE,
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       sheet: external_exports.string().describe("Sheet name"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-numbers-mcp",
-  "version": "1.1.19",
+  "version": "1.2.1",
   "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",