apple-numbers-mcp 1.1.14 → 1.1.16

package/build/index.js

@@ -22382,7 +22382,15 @@ var server = new McpServer({
   version: version2,
   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(
+function registerTool(name, config2, cb) {
+  const { outputSchema, ...rest } = config2;
+  return server.registerTool(
+    name,
+    outputSchema ? { ...rest, outputSchema: external_exports.object(outputSchema).passthrough() } : rest,
+    cb
+  );
+}
+registerTool(
   "health-check",
   {
     description: "Use when: you want a quick check that the Python 3 read sidecar (numbers-parser) is installed and reports its version.\nReturns: ok/not-ok plus the numbers-parser version string.\nDo not use when: you need a full setup diagnostic including Numbers.app and Automation permission \u2014 use doctor instead.",
@@ -22399,7 +22407,7 @@ server.registerTool(
     });
   }, "health-check")
 );
-server.registerTool(
+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 (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.",
@@ -22420,7 +22428,7 @@ server.registerTool(
     return successResponse(formatDoctorReport(report), { ...report });
   }, "doctor")
 );
-server.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.",
@@ -22464,7 +22472,7 @@ ${summary}`,
     );
   }, "get-file-info")
 );
-server.registerTool(
+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.",
@@ -22500,7 +22508,7 @@ ${dataRows}`,
     );
   }, "read-table")
 );
-server.registerTool(
+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.",
@@ -22539,7 +22547,7 @@ ${lines.join("\n")}`, {
     });
   }, "search")
 );
-server.registerTool(
+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.",
@@ -22566,7 +22574,7 @@ server.registerTool(
     );
   }, "export-table")
 );
-server.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.",
@@ -22603,7 +22611,7 @@ Merged: yes`;
     return successResponse(text, { ...cell });
   }, "get-cell")
 );
-server.registerTool(
+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.",
@@ -22632,7 +22640,7 @@ ${result.numHeaders} columns, ${result.numRows} data rows`,
     );
   }, "create-spreadsheet")
 );
-server.registerTool(
+registerTool(
   "set-cell",
   {
     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.
@@ -22667,7 +22675,7 @@ Safety: modifies the .numbers file in place via the numbers-parser sidecar (does
     );
   }, "set-cell")
 );
-server.registerTool(
+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.",
@@ -22701,7 +22709,7 @@ server.registerTool(
     );
   }, "set-cells-batch")
 );
-server.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.",
@@ -22730,7 +22738,7 @@ server.registerTool(
     );
   }, "add-rows")
 );
-server.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.",
@@ -22757,7 +22765,7 @@ server.registerTool(
     );
   }, "delete-rows")
 );
-server.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.",
@@ -22783,7 +22791,7 @@ server.registerTool(
     );
   }, "add-sheet")
 );
-server.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.",
@@ -22809,7 +22817,7 @@ server.registerTool(
     );
   }, "add-table")
 );
-server.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.',
@@ -22841,7 +22849,7 @@ Sheet: "${result.sheetName}" | Table: "${result.tableName}"`,
     );
   }, "import-csv")
 );
-server.registerTool(
+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.",
@@ -22873,7 +22881,7 @@ server.registerTool(
     );
   }, "update-rows")
 );
-server.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).",
@@ -22896,7 +22904,7 @@ server.registerTool(
     });
   }, "rename-sheet")
 );
-server.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).",
@@ -22921,7 +22929,7 @@ server.registerTool(
     );
   }, "rename-table")
 );
-server.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.',
@@ -22952,7 +22960,7 @@ Computed value: ${result.computedValue}`,
     );
   }, "set-formula")
 );
-server.registerTool(
+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.",
@@ -23010,7 +23018,7 @@ var cellStyleSchema = external_exports.object({
   verticalAlignment: external_exports.enum(["top", "center", "bottom"]).optional().describe("Vertical alignment"),
   textWrap: external_exports.boolean().optional().describe("Enable text wrapping")
 });
-server.registerTool(
+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.",
@@ -23037,7 +23045,7 @@ server.registerTool(
     );
   }, "set-cell-style")
 );
-server.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.",
@@ -23068,7 +23076,7 @@ server.registerTool(
     );
   }, "set-cells-style-batch")
 );
-server.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.",
@@ -23098,7 +23106,7 @@ server.registerTool(
     });
   }, "set-column-width")
 );
-server.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.",
@@ -23128,7 +23136,7 @@ server.registerTool(
     });
   }, "set-row-height")
 );
-server.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.",
@@ -23155,7 +23163,7 @@ server.registerTool(
     });
   }, "merge-cells")
 );
-server.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).",

package/package.json

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

package/requirements.txt

@@ -1 +1 @@
-numbers-parser==4.18.5
+numbers-parser==4.19.0