apple-numbers-mcp 1.1.18 → 1.2.0

package/README.md

@@ -303,7 +303,7 @@ 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.
+**⚠️ 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. Paths are bounded: `outputPath` must resolve — after `~` expansion and symlink resolution — to a location under your **home directory**, `/tmp`, `/private/tmp`, or `/Volumes`; anything else is rejected with an error naming those roots.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -321,7 +321,7 @@ Export a table to CSV, TSV, or JSON.
 
 Create a new `.numbers` file with one sheet and table.
 
-**⚠️ Safety:** Overwrites the file at `path` if it already exists — confirm the destination first.
+**⚠️ Safety:** Overwrites the file at `path` if it already exists — confirm the destination first. Paths are bounded: `path` must resolve — after `~` expansion and symlink resolution — to a location under your **home directory**, `/tmp`, `/private/tmp`, or `/Volumes`; anything else is rejected with an error naming those roots.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -573,7 +573,7 @@ Merge a rectangular range of cells, or undo a merge.
 
 Import a CSV, TSV, or JSON file into a new `.numbers` spreadsheet. Auto-detects format from extension, or pass `format` explicitly.
 
-**⚠️ Safety:** Overwrites the file at `outputPath` if it already exists — confirm the destination first.
+**⚠️ Safety:** Overwrites the file at `outputPath` if it already exists — confirm the destination first. Paths are bounded: both `inputPath` and `outputPath` must resolve — after `~` expansion and symlink resolution — to locations under your **home directory**, `/tmp`, `/private/tmp`, or `/Volumes`; anything else is rejected with an error naming those roots.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -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
@@ -774,6 +775,12 @@ These are tracked for future releases. The underlying `numbers-parser` library h
 - Check the path; expand `~` if your shell isn't doing it.
 - Ensure the file extension is `.numbers`.
 
+### "Output path … is outside the allowed roots" / "Input path … is outside the allowed roots"
+- 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.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.
 - Verify in **System Settings → Privacy & Security → Automation**, or reset with `tccutil reset AppleEvents`.

package/build/index.js

@@ -2985,7 +2985,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve2.call(this, root, ref);
+      let _sch = resolve3.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3012,7 +3012,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve2(root, ref) {
+    function resolve3(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3643,7 +3643,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve2(baseURI, relativeURI, options) {
+    function resolve3(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
       const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
@@ -3927,7 +3927,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve2,
+      resolve: resolve3,
       resolveComponent,
       equal,
       serialize,
@@ -19023,7 +19023,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -19040,7 +19040,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const earlyReject = (error2) => {
         reject(error2);
       };
@@ -19118,7 +19118,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve2(parseResult.data);
+            resolve3(parseResult.data);
           }
         } catch (error2) {
           reject(error2);
@@ -19379,12 +19379,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve2, interval);
+      const timeoutId = setTimeout(resolve3, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -20697,7 +20697,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+      await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -21385,12 +21385,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve2();
+        resolve3();
       } else {
-        this._stdout.once("drain", resolve2);
+        this._stdout.once("drain", resolve3);
       }
     });
   }
@@ -21399,7 +21399,7 @@ var StdioServerTransport = class {
 // src/index.ts
 import { readFileSync as readFileSync3 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { dirname as dirname2, join as join3 } from "node:path";
+import { dirname as dirname3, join as join4 } from "node:path";
 
 // src/utils/python.ts
 import { execSync, execFileSync } from "node:child_process";
@@ -21812,14 +21812,138 @@ function unmergeCells(filePath, sheet, table, startRow, startCol, endRow, endCol
 }
 
 // src/services/numbersManager.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { resolve, extname } from "node:path";
-import { homedir } from "node:os";
+import { existsSync as existsSync3 } from "node:fs";
+import { extname } from "node:path";
+
+// src/utils/exportPath.ts
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname as dirname2, isAbsolute, join as join2, resolve, sep } from "node:path";
+var ALLOWED_EXPORT_ROOTS = [
+  homedir(),
+  // os.tmpdir() is the canonical per-user temp dir on macOS (/var/folders/<hash>/T,
+  // real path /private/var/folders/...). It is what Node's os.tmpdir(), Python's
+  // tempfile and $TMPDIR all return — and what this repo's own fixtures use — so
+  // omitting it refuses the most ordinary scratch destination there is.
+  tmpdir(),
+  "/private/var/folders",
+  "/tmp",
+  "/private/tmp",
+  "/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, ...extraRoots()]) {
+    if (!roots.includes(root)) roots.push(root);
+    try {
+      const canonical = canonicalize(root);
+      if (!roots.includes(canonical)) roots.push(canonical);
+    } catch {
+    }
+  }
+  return roots;
+}
+function isPathWithinAllowedRoots(resolvedPath) {
+  return allowedRoots().some((root) => {
+    const base = root.endsWith(sep) ? root.slice(0, -1) : root;
+    return resolvedPath === base || resolvedPath.startsWith(base + sep);
+  });
+}
+function expandTilde(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith(`~${sep}`) || p.startsWith("~/")) return join2(homedir(), p.slice(2));
+  return p;
+}
+function entryPresent(p) {
+  try {
+    lstatSync(p);
+    return true;
+  } catch (e) {
+    const code = e.code;
+    return !(code === "ENOENT" || code === "ENOTDIR");
+  }
+}
+function canonicalizeCandidate(p, depth = 0) {
+  if (depth > 32) throw new Error(`Too many symbolic links resolving "${p}"`);
+  let existing = p;
+  const tail = [];
+  while (!entryPresent(existing)) {
+    const parent = dirname2(existing);
+    if (parent === existing) break;
+    tail.unshift(basename(existing));
+    existing = parent;
+  }
+  let real;
+  try {
+    real = canonicalize(existing);
+  } catch {
+    const viaLink = resolveDanglingLink(existing, depth);
+    if (viaLink !== null) {
+      return canonicalizeCandidate(tail.length ? join2(viaLink, ...tail) : viaLink, depth + 1);
+    }
+    real = existing;
+  }
+  return tail.length ? join2(real, ...tail) : real;
+}
+function resolveDanglingLink(p, depth) {
+  try {
+    if (!lstatSync(p).isSymbolicLink()) return null;
+    const target = readlinkSync(p);
+    if (isAbsolute(target)) return target;
+    return resolve(canonicalizeCandidate(dirname2(p), depth + 1), target);
+  } catch {
+    return null;
+  }
+}
+function resolveWithinAllowedRoots(path, label) {
+  const resolved = canonicalizeCandidate(resolve(expandTilde(path)));
+  if (!isPathWithinAllowedRoots(resolved)) {
+    throw new Error(
+      `${label} "${path}" resolves to "${resolved}", which is outside the allowed roots (${ALLOWED_EXPORT_ROOTS_TEXT}). Choose a path under one of those roots.`
+    );
+  }
+  return resolved;
+}
+
+// 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(/^~/, homedir()) : filePath;
-    const resolved = resolve(expanded);
-    if (!existsSync2(resolved)) {
+    const resolved = resolveWithinAllowedRoots(filePath, "Input path");
+    if (!existsSync3(resolved)) {
       throw new Error(`File not found: ${resolved}`);
     }
     if (extname(resolved).toLowerCase() !== ".numbers") {
@@ -21829,22 +21953,33 @@ var NumbersManager = class {
   }
   /**
    * Resolve and validate an output path for new files.
-   * Expands ~ and checks .numbers extension, but does NOT require the file to exist.
+   * Expands ~, enforces the allowed-roots boundary, and checks the .numbers
+   * extension, but does NOT require the file to exist. The extension is checked
+   * on the CANONICAL path so a symlink can't present a .numbers name for a
+   * target that is something else entirely.
    */
   validateOutputPath(filePath) {
-    const expanded = filePath.startsWith("~") ? filePath.replace(/^~/, homedir()) : filePath;
-    const resolved = resolve(expanded);
+    const resolved = resolveWithinAllowedRoots(filePath, "Output path");
     if (extname(resolved).toLowerCase() !== ".numbers") {
       throw new Error(`Not a Numbers file path: ${resolved}. Expected .numbers extension.`);
     }
     return resolved;
   }
   /**
-   * Resolve a generic path (expand ~ and resolve).
+   * Resolve a path that will be WRITTEN (export destinations), enforcing the
+   * allowed-roots boundary. Symlinks are resolved before the check, so a link
+   * inside an allowed directory cannot escape to a system location.
    */
-  resolvePath(filePath) {
-    const expanded = filePath.startsWith("~") ? filePath.replace(/^~/, homedir()) : filePath;
-    return resolve(expanded);
+  resolveWritePath(filePath) {
+    return resolveWithinAllowedRoots(filePath, "Output path");
+  }
+  /**
+   * Resolve a path that will be READ (import sources), enforcing the same
+   * allowed-roots boundary so this server can't be turned into an arbitrary
+   * local-file reader.
+   */
+  resolveReadPath(filePath) {
+    return resolveWithinAllowedRoots(filePath, "Input path");
   }
   /**
    * Get file structure: sheets, tables, dimensions, headers.
@@ -21886,7 +22021,7 @@ var NumbersManager = class {
    */
   exportTable(filePath, format, outputPath, sheet, table) {
     const resolved = this.validatePath(filePath);
-    const outputResolved = this.resolvePath(outputPath);
+    const outputResolved = this.resolveWritePath(outputPath);
     const args = [resolved, format, outputResolved];
     if (sheet) args.push("--sheet", sheet);
     if (table) args.push("--table", table);
@@ -22000,8 +22135,8 @@ var NumbersManager = class {
    * Import a CSV/TSV/JSON file into a new .numbers file.
    */
   importFile(inputPath, outputPath, options) {
-    const inputResolved = this.resolvePath(inputPath);
-    if (!existsSync2(inputResolved)) {
+    const inputResolved = this.resolveReadPath(inputPath);
+    if (!existsSync3(inputResolved)) {
       throw new Error(`Input file not found: ${inputResolved}`);
     }
     const outputResolved = this.validateOutputPath(outputPath);
@@ -22139,7 +22274,7 @@ function withErrorHandling(handler, prefix) {
 
 // src/tools/doctor.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 var NUMBERS_APP_PATHS = [
   "/Applications/Numbers.app",
   "/System/Applications/Numbers.app",
@@ -22148,7 +22283,7 @@ var NUMBERS_APP_PATHS = [
 ];
 var NUMBERS_BUNDLE_IDS = ["com.apple.Numbers", "com.apple.iWork.Numbers"];
 function findNumbersApp() {
-  const byPath = NUMBERS_APP_PATHS.find((p) => existsSync3(p));
+  const byPath = NUMBERS_APP_PATHS.find((p) => existsSync4(p));
   if (byPath) return byPath;
   for (const id of NUMBERS_BUNDLE_IDS) {
     try {
@@ -22158,7 +22293,7 @@ function findNumbersApp() {
         { encoding: "utf8", timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }
       ).trim();
       const path = out.endsWith("/") ? out.slice(0, -1) : out;
-      if (path && existsSync3(path)) return path;
+      if (path && existsSync4(path)) return path;
     } catch {
     }
   }
@@ -22335,18 +22470,18 @@ First use get-file-info and read-table to read the relevant table(s) so you know
 }
 
 // src/services/fileConfig.ts
-import { existsSync as existsSync4, readFileSync as readFileSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
 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 join2(homedir2(), "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 = [];
   try {
-    if (!existsSync4(path)) return applied;
+    if (!existsSync5(path)) return applied;
     const parsed = JSON.parse(readFileSync2(path, "utf8"));
     if (!parsed || typeof parsed !== "object") return applied;
     for (const [k, v] of Object.entries(parsed)) {
@@ -22476,8 +22611,8 @@ function withJsonSchema2020_12(transport) {
 // src/index.ts
 loadFileConfig();
 var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname2 = dirname2(__filename2);
-var pkg = JSON.parse(readFileSync3(join3(__dirname2, "..", "package.json"), "utf-8"));
+var __dirname2 = dirname3(__filename2);
+var pkg = JSON.parse(readFileSync3(join4(__dirname2, "..", "package.json"), "utf-8"));
 var version2 = pkg.version;
 var manager = new NumbersManager();
 var MAX_INDEX = 1e6;
@@ -22661,7 +22796,7 @@ ${lines.join("\n")}`, {
 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.\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.",
+    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. outputPath must resolve \u2014 after ~ expansion and symlink resolution \u2014 to a path under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected with an error naming those roots.",
     inputSchema: {
       path: external_exports.string().describe("Path to the .numbers file"),
       format: external_exports.enum(["csv", "tsv", "json"]).describe("Output format"),
@@ -22725,7 +22860,7 @@ Merged: yes`;
 registerTool(
   "create-spreadsheet",
   {
-    description: "Use when: you want to create a brand-new .numbers file with a single sheet and table from a list of headers, optionally with initial data rows.\nReturns: the file path, sheet name, table name, header count, and data-row count.\nDo not use when: you want to build the file from an existing CSV/TSV/JSON source \u2014 use import-csv; or you want to add to a file that already exists \u2014 use add-sheet / add-table / add-rows.\nSafety: writes a .numbers file via the numbers-parser sidecar (does not require Numbers.app). The target path is written unconditionally \u2014 if a file already exists at that path it is OVERWRITTEN in place; choose a fresh path or confirm overwrite first.",
+    description: "Use when: you want to create a brand-new .numbers file with a single sheet and table from a list of headers, optionally with initial data rows.\nReturns: the file path, sheet name, table name, header count, and data-row count.\nDo not use when: you want to build the file from an existing CSV/TSV/JSON source \u2014 use import-csv; or you want to add to a file that already exists \u2014 use add-sheet / add-table / add-rows.\nSafety: writes a .numbers file via the numbers-parser sidecar (does not require Numbers.app). The target path is written unconditionally \u2014 if a file already exists at that path it is OVERWRITTEN in place; choose a fresh path or confirm overwrite first. path must resolve \u2014 after ~ expansion and symlink resolution \u2014 to a location under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected with an error naming those roots.",
     inputSchema: {
       path: external_exports.string().describe("Path for the new .numbers file"),
       headers: external_exports.array(headerCellSchema).min(1).max(MAX_BATCH).describe("Column header names"),
@@ -22931,7 +23066,7 @@ registerTool(
 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; 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.',
+    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. Both inputPath and outputPath must resolve \u2014 after ~ expansion and symlink resolution \u2014 to locations under your home directory, /tmp, /private/tmp, or /Volumes; anything else is rejected with an error naming those roots.',
     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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-numbers-mcp",
-  "version": "1.1.18",
+  "version": "1.2.0",
   "description": "MCP server for Apple Numbers - read, write, search, and format .numbers spreadsheets via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",