@xlvane/mcp 1.2.1 → 1.2.3

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.
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as runCli } from "./server-XuY-Hgpe.js";
+import { n as runCli } from "./server-Lws8m9Ct.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-XuY-Hgpe.js";
+export { t as createServer, n as runCli } from "./server-Lws8m9Ct.js";

package/dist/{server-XuY-Hgpe.js → server-Lws8m9Ct.js}

@@ -1,9 +1,9 @@
 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 { lstat, open, readlink, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 // src/paths.ts
 function errorCode(error) {
@@ -47,6 +47,61 @@ function within(dirs, path) {
 function inside(roots, real) {
 	return within(roots.dirs, real);
 }
+/**
+* The real path of `target`. When it cannot be resolved (it does not exist, or a file stands where
+* a directory should), the nearest ancestor that exists is resolved instead: if that leads outside
+* the roots, the path is refused as outside, so the answer does not depend on what exists behind a
+* symbolic link inside a root (D-J01). Otherwise `onMissing` gives the error for the missing path.
+*/
+async function realInside(roots, path, target, onMissing) {
+	let real;
+	try {
+		real = await realpath(target);
+	} catch (error) {
+		if (await leadsOutside(roots, target, 0)) throw notAllowed(roots, path, "");
+		throw onMissing(error);
+	}
+	if (!inside(roots, real)) throw notAllowed(roots, path, "");
+	return real;
+}
+/**
+* Whether a path that does not resolve would lead outside the roots: its nearest existing
+* ancestor is found with `lstat`; a symbolic link there (also one whose target is missing) is
+* followed by its text, anything else by its real path, and the rest of the path is added.
+*/
+async function leadsOutside(roots, path, depth) {
+	if (depth > 40) return true;
+	let ancestor = path;
+	const rest = [];
+	for (;;) {
+		let info;
+		try {
+			info = await lstat(ancestor);
+		} catch {
+			const parent = dirname(ancestor);
+			if (parent === ancestor) return false;
+			rest.unshift(basename(ancestor));
+			ancestor = parent;
+			continue;
+		}
+		if (info.isSymbolicLink()) {
+			let text;
+			try {
+				text = await readlink(ancestor);
+			} catch {
+				return true;
+			}
+			return leadsOutside(roots, join(resolve(dirname(ancestor), text), ...rest), depth + 1);
+		}
+		let real;
+		try {
+			real = await realpath(ancestor);
+		} catch {
+			return true;
+		}
+		return !inside(roots, join(real, ...rest));
+	}
+}
 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.`,
@@ -86,22 +141,13 @@ function readAllowed(roots, path) {
 */
 async function readAllowedWith(roots, path, hooks) {
 	const target = absolute(roots, path);
-	const resolveInside = async () => {
-		let real;
-		try {
-			real = await realpath(target);
-		} 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.",
-				details: {
-					path,
-					code: errorCode(error)
-				}
-			});
+	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)
 		}
-		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 }
@@ -172,19 +218,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)}.`, {
@@ -247,9 +287,14 @@ async function writeAllowed(roots, path, data, overwrite) {
 	const temp = join(dir, `.${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 +464,39 @@ 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);
 	}
 }
+/**
+* `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,
@@ -503,7 +573,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 +608,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 +680,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 +725,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();
@@ -827,13 +897,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 +953,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" ? "	" : ",")
 			});
@@ -899,10 +972,12 @@ function registerTools(server, roots, allowWrite, limits) {
 			try {
 				data = from === "json" ? fromJSON(text, {
 					...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 +998,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.1";
+const SERVER_VERSION = "1.2.3";
 /** 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 +1029,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 +1068,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 +1079,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 +1106,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 +1134,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 +1155,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,7 +1,7 @@
 {
   "name": "@xlvane/mcp",
-  "version": "1.2.1",
-  "mcpName": "io.github.devxord/xlvane",
+  "version": "1.2.3",
+  "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": [
     "xlsx",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.4.0",
-    "xlvane": "^1.2.1"
+    "xlvane": "^1.2.3"
   },
   "publishConfig": {
     "access": "public",