@xlvane/mcp 1.2.2 → 1.3.0

package/README.md

@@ -29,6 +29,7 @@ Many MCP clients take a configuration like this one; check your client's documen
 | `--max-file-size <bytes>` | Largest file read or written. Default 64 MiB. |
 | `--max-rows <n>` | Largest number of rows one `read_table` call returns. Default 1000. |
 | `--max-response-chars <n>` | Largest tool result (also an error), in characters of its JSON text; the message carries the same data again as `structuredContent`. `read_table` returns the rows that fit (`truncated`, `nextOffset`); other tools return `XLV_E_LIMIT_EXCEEDED`. Default 1 Mi (1 048 576). |
+| `--max-cells <n>` | Largest number of cells in a workbook a tool reads (the `maxCells` read limit). Default 5 000 000. Lower it when the server must answer quickly: `diff` holds both workbooks in memory. |
 
 The server speaks MCP over stdin and stdout; messages for people go to stderr.
 
@@ -48,9 +49,9 @@ Every tool has a JSON Schema for its input and returns its result as `structured
 
 ## Security
 
-- **Directories:** files are read and written only inside the `--root` directories. Paths are checked after symbolic links are resolved, so `..`, absolute paths and links that lead outside are refused (`XLV_E_PATH_NOT_ALLOWED`). A file is checked again after it is opened (the path must still lead to the same file), so swapping it for a link meanwhile does not help. Writing through a symbolic link is refused. A path outside the roots gets the same answer whether or not something exists there. Only regular files are read.
-- **Read-only by default:** the write tools exist only with `--allow-write`. They create files exclusively and replace an existing file only when the call passes `"overwrite": true`, through a temporary file and a rename; the replacement keeps the file's permissions, and read-only files are not replaced. Any file name inside a root may be written, also dot files such as `.gitignore`; choose the roots accordingly.
-- **Limits:** files above `--max-file-size` are refused for reading and writing, and results above `--max-response-chars` are cut (`read_table`) or refused. The xlvane reader applies its limits for untrusted files (ZIP bombs, XML without DTDs or entities, the budgets of xlvane 1.1.1). `validate` lists at most 1 000 problems (`problemsTotal` counts all).
+- **Directories:** files are read and written only inside the `--root` directories. Paths are checked after symbolic links are resolved, so `..`, absolute paths and links that lead outside are refused (`XLV_E_PATH_NOT_ALLOWED`). A file is checked again after it is opened (the path must still lead to the same file), so swapping it for a link meanwhile does not help. Writing through a symbolic link is refused. A path outside the roots gets the same answer whether or not something exists there, also when it is reached through a symbolic link inside a root. Only regular files are read. Messages on stderr show control characters as `\uXXXX`.
+- **Read-only by default:** the write tools exist only with `--allow-write`. They create files exclusively and replace an existing file only when the call passes `"overwrite": true`, through a temporary file and a rename; the replacement keeps the file's permission bits (not setuid, setgid or sticky), and read-only files are not replaced. `edit_cells` writes formulas as given (for example `HYPERLINK(...)`); they are calculated when a spreadsheet application opens the file. Any file name inside a root may be written, also dot files such as `.gitignore`; choose the roots accordingly.
+- **Limits:** files above `--max-file-size` are refused for reading and writing (`convert` to JSON stops building the text at that size), workbooks above `--max-cells` cells are refused, and results above `--max-response-chars` are cut (`read_table`) or refused. The official MCP SDK closes the connection after a message larger than 10 MiB. The xlvane reader applies its limits for untrusted files (ZIP bombs, XML without DTDs or entities, the budgets of xlvane 1.1.1). `validate` lists at most 1 000 problems (`problemsTotal` counts all).
 - **File content is data:** values, sheet names and other text come from the files and may contain any text, also text meant to influence a model. The server returns it as data and does not interpret it.
 - **No code execution:** macros are never run, external links are never followed, and formulas are not calculated.
 
@@ -60,7 +61,7 @@ Every tool has a JSON Schema for its input and returns its result as `structured
 import { createServer, runCli } from '@xlvane/mcp';
 ```
 
-`createServer({ roots, allowWrite, maxFileBytes, maxRows, maxResponseChars })` returns an `McpServer` to connect to any transport; `runCli(args)` is the command line.
+`createServer({ roots, allowWrite, maxFileBytes, maxRows, maxResponseChars, maxCells, cwd })` returns an `McpServer` to connect to any transport; `runCli(args)` is the command line.
 
 ## Links
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as runCli } from "./server-B1Px_tvv.js";
+import { n as runCli } from "./server-BKislJBl.js";
 import process from "node:process";
 // src/bin.ts
 runCli(process.argv.slice(2)).then((code) => {

package/dist/index.d.ts

@@ -23,6 +23,8 @@ interface ServerOptions {
    * (`truncated`, `nextOffset`); other tools return `XLV_E_LIMIT_EXCEEDED`. Default 1 Mi.
    */
   readonly maxResponseChars?: number;
+  /** Largest number of cells in a workbook the tools read (the `maxCells` read limit). Default 5 000 000. */
+  readonly maxCells?: number;
   /** Directory that relative roots are resolved against. Default: the current directory. */
   readonly cwd?: string;
 }
@@ -42,7 +44,7 @@ interface ServerOptions {
 export declare function createServer(options: ServerOptions): Promise<McpServer>;
 /**
  * Runs the server from the command line: parses `--root`, `--allow-write`, `--max-file-size`,
- * `--max-rows` and `--max-response-chars`, then serves MCP over stdio until the client closes stdin. Returns the exit
+ * `--max-rows`, `--max-response-chars` and `--max-cells`, then serves MCP over stdio until the client closes stdin. Returns the exit
  * code. `xlvane mcp` calls this function.
  *
  * @example

package/dist/index.js

@@ -1 +1 @@
-export { t as createServer, n as runCli } from "./server-B1Px_tvv.js";
+export { t as createServer, n as runCli } from "./server-BKislJBl.js";

package/dist/{server-B1Px_tvv.js → server-BKislJBl.js}

@@ -1,10 +1,10 @@
 import { parseArgs } from "node:util";
 import { McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { ERROR_VALUES, XlvError, appendRows, diff, editCells, fromCSV, fromJSON, inspect, isXlvError, readTable, readWorkbook, toCSV, toJSON, writeTable } from "xlvane";
+import { DEFAULT_READ_LIMITS, ERROR_VALUES, XlvError, appendRows, diff, editCells, fromCSV, fromJSON, inspect, isXlvError, readTable, readWorkbook, toCSV, toJSON, writeTable } from "xlvane";
 import { constants } from "node:fs";
-import { chmod, lstat, open, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { lstat, open, readlink, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
 // src/paths.ts
 function errorCode(error) {
 	return typeof error === "object" && error !== null && "code" in error ? String(error.code) : "UNKNOWN";
@@ -47,6 +47,81 @@ function within(dirs, path) {
 function inside(roots, real) {
 	return within(roots.dirs, real);
 }
+/**
+* The real path of `target`. The path is refused as outside when it leads outside the roots, or when
+* a symbolic link on the way passes through a directory outside them, also when it then comes back
+* inside: so the answer does not depend on what exists outside the roots (D-J01, D-K04). Otherwise
+* `onMissing` gives the error for a path that does not exist.
+*/
+async function realInside(roots, path, target, onMissing) {
+	let real = null;
+	let failure = null;
+	try {
+		real = await realpath(target);
+	} catch (error) {
+		failure = error;
+	}
+	if (await passesOutside(roots, target)) throw notAllowed(roots, path, "");
+	if (real === null) throw onMissing(failure);
+	if (!inside(roots, real)) throw notAllowed(roots, path, "");
+	return real;
+}
+/**
+* Whether `dir` is a root, inside one, or a parent directory of one, as a real path or as given
+* (a root given through a link, such as /tmp on macOS, is reached through its given path too).
+*/
+function onTheWay(roots, dir) {
+	if (inside(roots, dir) || within(roots.given, dir)) return true;
+	const prefix = dir.endsWith(sep) ? dir : dir + sep;
+	return roots.dirs.some((root) => root.startsWith(prefix)) || roots.given.some((root) => root.startsWith(prefix));
+}
+/**
+* Whether resolving `path` leads outside the roots. The path is walked one component at a time
+* from the file system root, as the system resolves it: a symbolic link (also one whose target is
+* missing) is replaced by its text, so ".." in that text goes to the parent of the directory the
+* link leads to, not of the link (D-J01, D-K03). Once a link has been followed, every directory the
+* walk reaches, existing or not, must be a root, inside one or a parent of one; otherwise the path
+* is outside even if it ends inside (D-K04). From the first component that does not exist the rest
+* of the path is taken as written.
+*/
+async function passesOutside(roots, path) {
+	const split = (p) => p.slice(parse(p).root.length).split(sep === "\\" ? /[\\/]/ : "/").filter((part) => part !== "");
+	const pending = split(path);
+	let current = parse(path).root;
+	let links = 0;
+	while (pending.length > 0) {
+		const part = pending.shift();
+		if (part === ".") continue;
+		if (part === "..") {
+			current = dirname(current);
+			continue;
+		}
+		const next = join(current, part);
+		if (links > 0 && !onTheWay(roots, next)) return true;
+		let info;
+		try {
+			info = await lstat(next);
+		} catch {
+			return !inside(roots, resolve(next, ...pending));
+		}
+		if (!info.isSymbolicLink()) {
+			current = next;
+			continue;
+		}
+		if (++links > 40) return true;
+		let text;
+		try {
+			text = await readlink(next);
+		} catch {
+			return true;
+		}
+		if (isAbsolute(text)) {
+			current = parse(text).root;
+			pending.unshift(...split(text));
+		} else pending.unshift(...text.split(sep === "\\" ? /[\\/]/ : "/").filter((part) => part !== ""));
+	}
+	return !inside(roots, current);
+}
 function notAllowed(roots, path, why) {
 	return new XlvError("XLV_E_PATH_NOT_ALLOWED", `"${path}" is outside the directories this server may use${why}.`, {
 		hint: `Use a path inside ${roots.dirs.map((d) => `"${d}"`).join(" or ")}. Relative paths are resolved against the first one.`,
@@ -74,6 +149,21 @@ function absolute(roots, path) {
 	});
 	return full;
 }
+/**
+* The start of a file name, at most 100 bytes of UTF-8 and never cut inside a character, for the
+* name of a temporary file next to it (file systems limit names in bytes, D-K03).
+*/
+function shortName(name) {
+	let bytes = 0;
+	let end = 0;
+	for (const ch of name) {
+		const size = new TextEncoder().encode(ch).length;
+		if (bytes + size > 100) break;
+		bytes += size;
+		end += ch.length;
+	}
+	return name.slice(0, end);
+}
 /** Reads a file inside the roots, after checking its real path and size. */
 function readAllowed(roots, path) {
 	return readAllowedWith(roots, path, {});
@@ -86,27 +176,32 @@ function readAllowed(roots, path) {
 */
 async function readAllowedWith(roots, path, hooks) {
 	const target = absolute(roots, path);
-	const resolveInside = async () => {
-		let real;
+	const resolveInside = () => realInside(roots, path, target, (error) => new XlvError("XLV_E_FILE_READ", `Cannot read "${path}" (${errorCode(error)}).`, {
+		hint: errorCode(error) === "ENOENT" ? "The file does not exist. Use inspect_workbook on a file that exists, or check the name." : "Check that the path points to a readable file.",
+		details: {
+			path,
+			code: errorCode(error)
+		}
+	}));
+	const notAFile = () => new XlvError("XLV_E_FILE_READ", `"${path}" is not a file.`, {
+		hint: "Pass the path of a file.",
+		details: { path }
+	});
+	const statOf = async () => {
+		const real = await resolveInside();
 		try {
-			real = await realpath(target);
+			return await stat(real);
 		} catch (error) {
 			throw new XlvError("XLV_E_FILE_READ", `Cannot read "${path}" (${errorCode(error)}).`, {
-				hint: errorCode(error) === "ENOENT" ? "The file does not exist. Use inspect_workbook on a file that exists, or check the name." : "Check that the path points to a readable file.",
+				hint: "Check that the file still exists.",
 				details: {
 					path,
 					code: errorCode(error)
 				}
 			});
 		}
-		if (!inside(roots, real)) throw notAllowed(roots, path, real === target ? "" : " (after following symbolic links)");
-		return real;
 	};
-	const notAFile = () => new XlvError("XLV_E_FILE_READ", `"${path}" is not a file.`, {
-		hint: "Pass the path of a file.",
-		details: { path }
-	});
-	if (!(await stat(await resolveInside())).isFile()) throw notAFile();
+	if (!(await statOf()).isFile()) throw notAFile();
 	await hooks.afterCheck?.();
 	let handle;
 	try {
@@ -123,7 +218,7 @@ async function readAllowedWith(roots, path, hooks) {
 	try {
 		await hooks.afterOpen?.();
 		const opened = await handle.stat();
-		const now = await stat(await resolveInside());
+		const now = await statOf();
 		if (now.dev !== opened.dev || now.ino !== opened.ino) throw new XlvError("XLV_E_FILE_READ", `"${path}" changed while it was being read.`, {
 			hint: "Read the file again when nothing else is writing to it.",
 			details: { path }
@@ -172,19 +267,13 @@ async function writeAllowed(roots, path, data, overwrite) {
 		hint: "Pass a path that ends in a file name.",
 		details: { path }
 	});
-	let dir;
-	try {
-		dir = await realpath(dirname(target));
-	} catch (error) {
-		throw new XlvError("XLV_E_FILE_WRITE", `The directory of "${path}" does not exist (${errorCode(error)}).`, {
-			hint: "Write into an existing directory inside the allowed roots.",
-			details: {
-				path,
-				code: errorCode(error)
-			}
-		});
-	}
-	if (!inside(roots, dir)) throw notAllowed(roots, path, dir === dirname(target) ? "" : " (after following symbolic links)");
+	const dir = await realInside(roots, path, dirname(target), (error) => new XlvError("XLV_E_FILE_WRITE", `The directory of "${path}" does not exist (${errorCode(error)}).`, {
+		hint: "Write into an existing directory inside the allowed roots.",
+		details: {
+			path,
+			code: errorCode(error)
+		}
+	}));
 	const file = join(dir, name);
 	const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
 	if (bytes.length > roots.maxFileBytes) throw new XlvError("XLV_E_LIMIT_EXCEEDED", `The output would be ${String(bytes.length)} bytes, more than the server's limit of ${String(roots.maxFileBytes)}.`, {
@@ -198,7 +287,13 @@ async function writeAllowed(roots, path, data, overwrite) {
 	let existing = null;
 	try {
 		const info = await lstat(file);
-		if (info.isSymbolicLink()) throw notAllowed(roots, path, " (it is a symbolic link)");
+		if (info.isSymbolicLink()) throw new XlvError("XLV_E_PATH_NOT_ALLOWED", `"${path}" is a symbolic link; the server does not write through symbolic links.`, {
+			hint: "Write to another file name, or replace the link with a regular file.",
+			details: {
+				path,
+				roots: [...roots.dirs]
+			}
+		});
 		if (!info.isFile()) throw new XlvError("XLV_E_FILE_WRITE", `"${path}" is not a file.`, {
 			hint: "Choose a file name that is not a directory.",
 			details: {
@@ -244,12 +339,17 @@ async function writeAllowed(roots, path, data, overwrite) {
 		};
 	}
 	const random = Array.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8)), (b) => b.toString(16).padStart(2, "0")).join("");
-	const temp = join(dir, `.${name}.xlvane-${random}.tmp`);
+	const temp = join(dir, `.${shortName(name)}.xlvane-${random}.tmp`);
 	let created = false;
 	try {
-		await writeFile(temp, bytes, { flag: "wx" });
+		const handle = await open(temp, "wx", 384);
 		created = true;
-		await chmod(temp, existing.mode & 4095);
+		try {
+			await handle.writeFile(bytes);
+			await handle.chmod(existing.mode & 511);
+		} finally {
+			await handle.close();
+		}
 		await rename(temp, file);
 	} catch (error) {
 		if (created) await rm(temp, { force: true });
@@ -419,14 +519,64 @@ function handler(maxChars, run) {
 		}
 	};
 }
-async function book(roots, path) {
+async function book(roots, limits, path) {
 	const bytes = await readAllowed(roots, path);
 	try {
-		return readWorkbook(bytes);
+		return readWorkbook(bytes, { limits: { maxCells: limits.maxCells } });
 	} catch (error) {
 		throw withPath(error, path);
 	}
 }
+/**
+* Refuses rows that hold more cells than `--max-cells` (values other than null, plus one header
+* cell per key), so the write tools cannot create a workbook the read tools refuse (D-K03). For
+* `edit_cells` it checks the request; the library then counts the cells of the result (D-K04).
+*/
+function checkCells(rows, maxCells, path) {
+	let cells = 0;
+	const keys = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		if (Array.isArray(row)) {
+			for (const v of row) if (v !== null && v !== void 0) cells++;
+		} else if (typeof row === "object" && row !== null) for (const [k, v] of Object.entries(row)) {
+			keys.add(k);
+			if (v !== null && v !== void 0) cells++;
+		}
+		if (cells + keys.size > maxCells) throw new XlvError("XLV_E_LIMIT_EXCEEDED", `The rows hold more than ${String(maxCells)} cells, the server's limit (--max-cells).`, {
+			hint: "Write fewer rows per file, or start the server with a higher --max-cells.",
+			details: {
+				path,
+				limit: "maxCells",
+				value: maxCells
+			}
+		});
+	}
+}
+/**
+* `JSON.stringify(rows, null, 2)` plus a line feed, built row by row: every row repeats the header
+* names, so a small file can make a text far larger than the file limit, or than a string can be.
+* The text stops as soon as it is longer than `maxChars` characters, before encoding (D-J01).
+*/
+function jsonText(rows, maxChars, path) {
+	if (rows.length === 0) return "[]\n";
+	const parts = ["["];
+	let length = 1;
+	for (let i = 0; i < rows.length; i++) {
+		const part = `${i === 0 ? "" : ","}\n  ${JSON.stringify(rows[i], null, 2).replace(/\n/g, "\n  ")}`;
+		length += part.length;
+		if (length > maxChars) throw new XlvError("XLV_E_LIMIT_EXCEEDED", `The JSON text would be longer than the server's limit of ${String(maxChars)} bytes.`, {
+			hint: "Convert fewer rows or columns (sheet with a smaller table), or raise --max-file-size.",
+			details: {
+				path,
+				limit: "maxFileBytes",
+				value: maxChars
+			}
+		});
+		parts.push(part);
+	}
+	parts.push("\n]\n");
+	return parts.join("");
+}
 function withPath(error, path) {
 	if (error instanceof XlvError && error.details["path"] === void 0) return new XlvError(error.code, error.message, {
 		location: error.location,
@@ -493,7 +643,7 @@ function typeOf(v) {
 function registerTools(server, roots, allowWrite, limits) {
 	server.registerTool("inspect_workbook", {
 		title: "Inspect a workbook",
-		description: "Describes an XLSX file without changing it: sheets (including hidden ones), used ranges, detected header rows, column types with sample values, merged cells, example formulas, and warnings (macros, external links, damaged parts). Macros are never run and links are never followed. Use it before read_table to find the sheet and header row.",
+		description: "Describes an XLSX file without changing it: sheets (including hidden ones), used ranges, detected header rows, column types with sample values, merged cells, example formulas, pictures and charts (position, chart types, title, series count), and warnings (macros, external links, damaged parts). Macros are never run and links are never followed. Use it before read_table to find the sheet and header row.",
 		inputSchema: object({
 			path: PATH,
 			sheet: {
@@ -503,7 +653,7 @@ function registerTools(server, roots, allowWrite, limits) {
 		}, ["path"]),
 		annotations: READ
 	}, handler(limits.maxResponseChars, async (a) => {
-		const workbook = await book(roots, a["path"]);
+		const workbook = await book(roots, limits, a["path"]);
 		const report = inspect(workbook);
 		if (typeof a["sheet"] !== "string") return report;
 		const sheet = workbook.getSheet(a["sheet"]);
@@ -538,7 +688,7 @@ function registerTools(server, roots, allowWrite, limits) {
 		}, ["path"]),
 		annotations: READ
 	}, handler(limits.maxResponseChars, async (a) => {
-		const workbook = await book(roots, a["path"]);
+		const workbook = await book(roots, limits, a["path"]);
 		const table = readTable(workbook, {
 			...typeof a["sheet"] === "string" ? { sheet: a["sheet"] } : {},
 			...typeof a["range"] === "string" ? { range: a["range"] } : {},
@@ -610,8 +760,8 @@ function registerTools(server, roots, allowWrite, limits) {
 		}, ["before", "after"]),
 		annotations: READ
 	}, handler(limits.maxResponseChars, async (a) => {
-		const before = await book(roots, a["before"]);
-		const after = await book(roots, a["after"]);
+		const before = await book(roots, limits, a["before"]);
+		const after = await book(roots, limits, a["after"]);
 		const r = diff(before, after, { styles: a["styles"] === true });
 		const max = a["maxChanges"] ?? 200;
 		return {
@@ -655,7 +805,7 @@ function registerTools(server, roots, allowWrite, limits) {
 		}, ["path"]),
 		annotations: READ
 	}, handler(limits.maxResponseChars, async (a) => {
-		const workbook = await book(roots, a["path"]);
+		const workbook = await book(roots, limits, a["path"]);
 		const warnings = inspect(workbook).warnings;
 		const rules = a["columns"] ?? [];
 		const names = /* @__PURE__ */ new Set();
@@ -674,6 +824,7 @@ function registerTools(server, roots, allowWrite, limits) {
 		};
 		let sheetName = null;
 		let rowsChecked = 0;
+		if (typeof a["sheet"] === "string") workbook.getSheet(a["sheet"]);
 		if (rules.length > 0) {
 			const table = readTable(workbook, typeof a["sheet"] === "string" ? { sheet: a["sheet"] } : {});
 			sheetName = table.sheet;
@@ -746,6 +897,7 @@ function registerTools(server, roots, allowWrite, limits) {
 		}, ["path", "rows"]),
 		annotations: WRITE
 	}, handler(limits.maxResponseChars, async (a) => {
+		checkCells(a["rows"], limits.maxCells, a["path"]);
 		const rows = a["rows"].map((r) => Array.isArray(r) ? r.map(cellInput) : Object.fromEntries(Object.entries(r).map(([k, v]) => [k, cellInput(v)])));
 		const bytes = writeTable(rows, {
 			...Array.isArray(a["columns"]) ? { columns: a["columns"] } : {},
@@ -819,6 +971,8 @@ function registerTools(server, roots, allowWrite, limits) {
 		const edits = a["edits"] ?? [];
 		const append = a["append"];
 		if (edits.length === 0 && append === void 0) throw new XlvError("XLV_E_INVALID_INPUT", "Nothing to do: pass edits, append or both.", { hint: "For example {\"path\": \"report.xlsx\", \"edits\": [{\"sheet\": \"Sales\", \"cell\": \"B2\", \"value\": 1250}], \"output\": \"updated.xlsx\"}." });
+		if (edits.length > limits.maxCells) checkCells([edits.map(() => 0)], limits.maxCells, path);
+		if (append) checkCells(append.rows, limits.maxCells, path);
 		let bytes = await readAllowed(roots, path);
 		const warnings = [];
 		try {
@@ -827,13 +981,16 @@ function registerTools(server, roots, allowWrite, limits) {
 					sheet: e.sheet,
 					cell: e.cell.toUpperCase(),
 					value: cellInput(e.value)
-				})));
+				})), { limits: { maxCells: limits.maxCells } });
 				bytes = r.bytes;
 				warnings.push(...r.warnings);
 			}
 			if (append) {
 				const rows = append.rows.map((r) => Array.isArray(r) ? r.map(cellInput) : Object.fromEntries(Object.entries(r).map(([k, v]) => [k, cellInput(v)])));
-				const r = appendRows(bytes, append.sheet, rows, append.header !== void 0 ? { header: append.header } : void 0);
+				const r = appendRows(bytes, append.sheet, rows, {
+					limits: { maxCells: limits.maxCells },
+					...append.header !== void 0 ? { header: append.header } : {}
+				});
 				bytes = r.bytes;
 				warnings.push(...r.warnings);
 			}
@@ -880,8 +1037,8 @@ function registerTools(server, roots, allowWrite, limits) {
 		const sheet = typeof a["sheet"] === "string" ? { sheet: a["sheet"] } : {};
 		let data;
 		if (books.includes(from) && tables.includes(to)) {
-			const workbook = await book(roots, input);
-			data = to === "json" ? `${JSON.stringify(toJSON(workbook, sheet).rows, null, 2)}\n` : toCSV(workbook, {
+			const workbook = await book(roots, limits, input);
+			data = to === "json" ? jsonText(toJSON(workbook, sheet).rows, roots.maxFileBytes, output) : toCSV(workbook, {
 				...sheet,
 				delimiter: a["delimiter"] ?? (to === "tsv" ? "	" : ",")
 			});
@@ -897,12 +1054,21 @@ function registerTools(server, roots, allowWrite, limits) {
 				});
 			}
 			try {
-				data = from === "json" ? fromJSON(text, {
+				let parsed = text;
+				if (from === "json") {
+					try {
+						parsed = JSON.parse(text);
+					} catch {}
+					if (Array.isArray(parsed)) checkCells(parsed, limits.maxCells, input);
+				}
+				data = from === "json" ? fromJSON(parsed, {
 					...sheet,
-					preset: "plain"
+					preset: "plain",
+					maxCells: limits.maxCells
 				}) : fromCSV(text, {
 					...sheet,
-					delimiter: a["delimiter"] ?? (from === "tsv" ? "	" : ",")
+					delimiter: a["delimiter"] ?? (from === "tsv" ? "	" : ","),
+					maxCells: limits.maxCells
 				});
 			} catch (error) {
 				throw withPath(error, input);
@@ -923,7 +1089,7 @@ function registerTools(server, roots, allowWrite, limits) {
 }
 // src/server.ts
 /** Version reported in server info; kept equal to package.json by tests/mcp/server.test.ts. */
-const SERVER_VERSION = "1.2.2";
+const SERVER_VERSION = "1.3.0";
 /** Default largest file read or written by the tools: 64 MiB. */
 const DEFAULT_MAX_FILE_BYTES = 67108864;
 /** Default largest number of rows returned by one read_table call. */
@@ -954,7 +1120,8 @@ function build(roots, allowWrite, limits) {
 async function prepare(options) {
 	const limits = {
 		maxRows: options.maxRows ?? 1e3,
-		maxResponseChars: options.maxResponseChars ?? 1048576
+		maxResponseChars: options.maxResponseChars ?? 1048576,
+		maxCells: options.maxCells ?? DEFAULT_READ_LIMITS.maxCells
 	};
 	return {
 		roots: await resolveRoots(options.roots, options.cwd ?? ".", options.maxFileBytes ?? 67108864),
@@ -992,6 +1159,7 @@ Options:
   --max-rows <n>          Largest number of rows per read_table call (default ${String(DEFAULT_MAX_ROWS)})
   --max-response-chars <n>
                           Largest tool result in characters of JSON (default ${String(DEFAULT_MAX_RESPONSE_CHARS)})
+  --max-cells <n>         Largest number of cells in a workbook read (default ${String(DEFAULT_READ_LIMITS.maxCells)})
   -h, --help              Show this help
 
 The server speaks MCP over stdin and stdout; messages for people go to stderr.
@@ -1002,8 +1170,20 @@ function positive(value, name) {
 	if (!/^\d+$/.test(value) || Number(value) < 1) throw new Error(`--${name} must be a whole number of 1 or more, not "${value}".`);
 	return Number(value);
 }
+/**
+* Text for stderr with control characters (other than line feeds), C1 controls and bidirectional
+* formatting characters written as `\uXXXX`: arguments and directory names come from the client
+* configuration and must not reach the terminal as escape sequences (D-J01).
+*/
+function printable(text) {
+	return text.replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
 /** runCli with its environment passed in (tests). */
-async function runWith(args, io) {
+async function runWith(args, rawIO) {
+	const io = {
+		...rawIO,
+		stderr: (text) => rawIO.stderr(printable(text))
+	};
 	let values;
 	try {
 		values = parseArgs({
@@ -1017,6 +1197,7 @@ async function runWith(args, io) {
 				"max-file-size": { type: "string" },
 				"max-rows": { type: "string" },
 				"max-response-chars": { type: "string" },
+				"max-cells": { type: "string" },
 				help: {
 					type: "boolean",
 					short: "h"
@@ -1044,13 +1225,15 @@ async function runWith(args, io) {
 		const maxFileBytes = positive(values["max-file-size"], "max-file-size");
 		const maxRows = positive(values["max-rows"], "max-rows");
 		const maxResponseChars = positive(values["max-response-chars"], "max-response-chars");
+		const maxCells = positive(values["max-cells"], "max-cells");
 		prepared = await prepare({
 			roots,
 			cwd: io.cwd,
 			allowWrite: values["allow-write"] === true,
 			...maxFileBytes !== void 0 ? { maxFileBytes } : {},
 			...maxRows !== void 0 ? { maxRows } : {},
-			...maxResponseChars !== void 0 ? { maxResponseChars } : {}
+			...maxResponseChars !== void 0 ? { maxResponseChars } : {},
+			...maxCells !== void 0 ? { maxCells } : {}
 		});
 	} catch (error) {
 		io.stderr(`xlvane-mcp: ${error instanceof Error ? error.message : String(error)}\n${isXlvError(error) ? `${error.hint}\n` : ""}`);
@@ -1063,7 +1246,7 @@ async function runWith(args, io) {
 }
 /**
 * Runs the server from the command line: parses `--root`, `--allow-write`, `--max-file-size`,
-* `--max-rows` and `--max-response-chars`, then serves MCP over stdio until the client closes stdin. Returns the exit
+* `--max-rows`, `--max-response-chars` and `--max-cells`, then serves MCP over stdio until the client closes stdin. Returns the exit
 * code. `xlvane mcp` calls this function.
 *
 * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xlvane/mcp",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "mcpName": "io.github.DevXord/xlvane",
   "description": "MCP server for XLSX files: inspect, read, write, edit, convert, compare and validate workbooks with xlvane, limited to the directories given at start.",
   "keywords": [
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",
-    "xlvane": "^1.2.2"
+    "xlvane": "^1.3.0"
   },
   "publishConfig": {
     "access": "public",