@xlvane/mcp 1.2.3 → 1.3.0

package/README.md

@@ -61,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-Lws8m9Ct.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.js

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

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

@@ -4,7 +4,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 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 { lstat, open, readlink, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+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";
@@ -48,59 +48,79 @@ 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.
+* 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;
+	let real = null;
+	let failure = null;
 	try {
 		real = await realpath(target);
 	} catch (error) {
-		if (await leadsOutside(roots, target, 0)) throw notAllowed(roots, path, "");
-		throw onMissing(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 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.
+* 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).
 */
-async function leadsOutside(roots, path, depth) {
-	if (depth > 40) return true;
-	let ancestor = path;
-	const rest = [];
-	for (;;) {
+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(ancestor);
+			info = await lstat(next);
 		} catch {
-			const parent = dirname(ancestor);
-			if (parent === ancestor) return false;
-			rest.unshift(basename(ancestor));
-			ancestor = parent;
-			continue;
+			return !inside(roots, resolve(next, ...pending));
 		}
-		if (info.isSymbolicLink()) {
-			let text;
-			try {
-				text = await readlink(ancestor);
-			} catch {
-				return true;
-			}
-			return leadsOutside(roots, join(resolve(dirname(ancestor), text), ...rest), depth + 1);
+		if (!info.isSymbolicLink()) {
+			current = next;
+			continue;
 		}
-		let real;
+		if (++links > 40) return true;
+		let text;
 		try {
-			real = await realpath(ancestor);
+			text = await readlink(next);
 		} catch {
 			return true;
 		}
-		return !inside(roots, join(real, ...rest));
+		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}.`, {
@@ -129,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, {});
@@ -152,7 +187,21 @@ async function readAllowedWith(roots, path, hooks) {
 		hint: "Pass the path of a file.",
 		details: { path }
 	});
-	if (!(await stat(await resolveInside())).isFile()) throw notAFile();
+	const statOf = async () => {
+		const real = await resolveInside();
+		try {
+			return await stat(real);
+		} catch (error) {
+			throw new XlvError("XLV_E_FILE_READ", `Cannot read "${path}" (${errorCode(error)}).`, {
+				hint: "Check that the file still exists.",
+				details: {
+					path,
+					code: errorCode(error)
+				}
+			});
+		}
+	};
+	if (!(await statOf()).isFile()) throw notAFile();
 	await hooks.afterCheck?.();
 	let handle;
 	try {
@@ -169,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 }
@@ -238,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: {
@@ -284,7 +339,7 @@ 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 {
 		const handle = await open(temp, "wx", 384);
@@ -473,6 +528,31 @@ async function book(roots, limits, 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).
@@ -563,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: {
@@ -744,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;
@@ -816,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"] } : {},
@@ -889,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 {
@@ -970,7 +1054,14 @@ 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",
 					maxCells: limits.maxCells
@@ -998,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.3";
+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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xlvane/mcp",
-  "version": "1.2.3",
+  "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.3"
+    "xlvane": "^1.3.0"
   },
   "publishConfig": {
     "access": "public",