@xlvane/mcp 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 DevXord
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @xlvane/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP (Model Context Protocol) server for XLSX files, built on [xlvane](https://www.npmjs.com/package/xlvane) and the official MCP TypeScript SDK (`@modelcontextprotocol/server` 2.4.0, protocol revision 2026-07-28). An MCP client, such as a coding agent, can inspect, read, compare and validate workbooks, and optionally write, edit and convert them, through tools instead of code.
+
+Requires Node.js 22 or later. Dependencies: `xlvane` and `@modelcontextprotocol/server` (which brings `@modelcontextprotocol/core` and `zod`).
+
+## Start
+
+```sh
+npx @xlvane/mcp --root ./data                 # read-only, files inside ./data
+npx @xlvane/mcp --root ./data --allow-write   # also write_table, edit_cells, convert
+xlvane mcp --root ./data                      # the same server, through the xlvane CLI
+```
+
+Many MCP clients take a configuration like this one; check your client's documentation for its exact format and file:
+
+```json
+{
+  "mcpServers": {
+    "xlvane": { "command": "npx", "args": ["@xlvane/mcp", "--root", "/absolute/path/to/data"] }
+  }
+}
+```
+
+| Option | Meaning |
+|---|---|
+| `--root <dir>` | A directory the tools may use; repeat for several. Required. Relative paths in tool calls are resolved against the first one. |
+| `--allow-write` | Also offer the tools that write files. Without it they are not registered at all. |
+| `--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). |
+
+The server speaks MCP over stdin and stdout; messages for people go to stderr.
+
+## Tools
+
+| Tool | Writes | What it does |
+|---|---|---|
+| `inspect_workbook` | no | Sheets (also hidden ones), used ranges, header rows, column types with samples, merged cells, formulas, warnings. |
+| `read_table` | no | Rows of a sheet as objects keyed by the header row; paging with `offset` and `limit`; dates as ISO 8601. |
+| `diff` | no | Cell-by-cell differences between two workbooks. |
+| `validate` | no | Read warnings, and column rules (`name`, `type`, `optional`) with the cell of each problem. |
+| `write_table` | yes | Rows to a new XLSX file (report preset: bold header, frozen row, autofilter, widths). |
+| `edit_cells` | yes | Set cells and append rows, keeping the rest of the file unchanged. |
+| `convert` | yes | XLSX to CSV/TSV/JSON and back; CSV output escapes formula-like text. |
+
+Every tool has a JSON Schema for its input and returns its result as `structuredContent` and as JSON text. Errors are tool results with `isError: true` and the `XlvError` data: a stable `code`, the `location`, a `hint` and `details` (docs/errors.md).
+
+## 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).
+- **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.
+
+## API
+
+```ts
+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.
+
+## Links
+
+- Changes in each version: [CHANGELOG.md](https://github.com/DevXord/xlvane/blob/main/CHANGELOG.md)
+- Bugs and questions: [GitHub issues](https://github.com/DevXord/xlvane/issues)
+- Reporting a vulnerability: [SECURITY.md](https://github.com/DevXord/xlvane/blob/main/SECURITY.md)
+
+License: MIT. The MCP SDK is licensed under Apache-2.0.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { n as runCli } from "./server-DqbH7i3w.js";
+import process from "node:process";
+// src/bin.ts
+runCli(process.argv.slice(2)).then((code) => {
+	process.exitCode = code;
+}, (error) => {
+	process.stderr.write(`xlvane-mcp: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+	process.exitCode = 3;
+});

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { McpServer } from "@modelcontextprotocol/server";
+/**
+ * Options of {@link createServer}.
+ *
+ * @example
+ * ```ts
+ * import type { ServerOptions } from '@xlvane/mcp';
+ *
+ * const options: ServerOptions = { roots: ['./data'], allowWrite: false };
+ * ```
+ */
+interface ServerOptions {
+  /** Directories the tools may use. Relative paths in tool calls are resolved against the first one. Required, at least one. */
+  readonly roots: readonly string[];
+  /** Register the tools that write files (write_table, edit_cells, convert). Default false. */
+  readonly allowWrite?: boolean;
+  /** Largest file read or written, in bytes. Default 64 MiB. */
+  readonly maxFileBytes?: number;
+  /** Largest number of rows one read_table call returns. Default 1000. */
+  readonly maxRows?: number;
+  /**
+   * Largest tool result, in characters of its JSON text. read_table returns the rows that fit
+   * (`truncated`, `nextOffset`); other tools return `XLV_E_LIMIT_EXCEEDED`. Default 1 Mi.
+   */
+  readonly maxResponseChars?: number;
+  /** Directory that relative roots are resolved against. Default: the current directory. */
+  readonly cwd?: string;
+}
+/**
+ * Creates the xlvane MCP server with its tools. Connect it to any MCP transport; `runCli` serves
+ * it over stdio. The roots are resolved (symbolic links followed) once, here.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from '@xlvane/mcp';
+ * import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+ *
+ * const server = await createServer({ roots: ['./data'] });
+ * await server.connect(new StdioServerTransport());
+ * ```
+ */
+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
+ * code. `xlvane mcp` calls this function.
+ *
+ * @example
+ * ```ts
+ * import { runCli } from '@xlvane/mcp';
+ *
+ * const code = await runCli(['--root', './data', '--allow-write']);
+ * ```
+ */
+export declare function runCli(args: readonly string[]): Promise<number>;
+export type { ServerOptions };

package/dist/index.js

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

package/dist/server-DqbH7i3w.js

@@ -0,0 +1,1093 @@
+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 { 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";
+// src/paths.ts
+function errorCode(error) {
+	return typeof error === "object" && error !== null && "code" in error ? String(error.code) : "UNKNOWN";
+}
+/** Resolves the --root directories; each must exist and be a directory. */
+async function resolveRoots(dirs, cwd, maxFileBytes) {
+	if (dirs.length === 0) throw new XlvError("XLV_E_INVALID_OPTION", "No directory was given.", {
+		hint: "Start the server with at least one directory it may use, for example: xlvane-mcp --root ./data",
+		details: { option: "roots" }
+	});
+	const out = [];
+	const given = [];
+	for (const dir of dirs) {
+		const full = resolve(cwd, dir);
+		let real;
+		try {
+			real = await realpath(full);
+		} catch (error) {
+			throw new XlvError("XLV_E_FILE_READ", `The directory "${dir}" does not exist (${errorCode(error)}).`, {
+				hint: "Pass an existing directory to --root.",
+				details: { path: dir }
+			});
+		}
+		if (!(await stat(real)).isDirectory()) throw new XlvError("XLV_E_FILE_READ", `"${dir}" is not a directory.`, {
+			hint: "Pass a directory to --root, not a file.",
+			details: { path: dir }
+		});
+		out.push(real);
+		given.push(full);
+	}
+	return {
+		dirs: out,
+		given,
+		maxFileBytes
+	};
+}
+function within(dirs, path) {
+	return dirs.some((root) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep));
+}
+function inside(roots, real) {
+	return within(roots.dirs, real);
+}
+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.`,
+		details: {
+			path,
+			roots: [...roots.dirs]
+		}
+	});
+}
+/**
+* The absolute, normalized path of a tool argument. A path that is not inside a root even before
+* symbolic links are resolved is refused here, before the file system is touched, so the answer
+* for a path outside the roots does not depend on what exists there (D-I04).
+*/
+function absolute(roots, path) {
+	if (typeof path !== "string" || path === "" || path.includes("\0")) throw new XlvError("XLV_E_INVALID_INPUT", "The path must be a non-empty string.", {
+		hint: "Pass a file name such as \"report.xlsx\".",
+		details: { path: String(path).slice(0, 200) }
+	});
+	const full = isAbsolute(path) ? resolve(path) : resolve(roots.dirs[0], path);
+	if (!within(roots.dirs, full) && !within(roots.given, full)) throw notAllowed(roots, path, "");
+	if (sep === "\\" && full.slice(2).includes(":")) throw new XlvError("XLV_E_INVALID_INPUT", `"${path}" contains ":" after the drive.`, {
+		hint: "Use a file name without \":\".",
+		details: { path }
+	});
+	return full;
+}
+/** Reads a file inside the roots, after checking its real path and size. */
+function readAllowed(roots, path) {
+	return readAllowedWith(roots, path, {});
+}
+/**
+* {@link readAllowed} with hooks for tests. The file is opened first and checked afterwards: the
+* path must still resolve inside a root to the same file (device and inode) as the one opened,
+* so a file or directory swapped for a symbolic link between the check and the read is refused
+* (D-I02). At most the size limit plus one byte is read, whatever the size was when checked.
+*/
+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)
+				}
+			});
+		}
+		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();
+	await hooks.afterCheck?.();
+	let handle;
+	try {
+		handle = await open(target, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+	} catch (error) {
+		throw new XlvError("XLV_E_FILE_READ", `Cannot read "${path}" (${errorCode(error)}).`, {
+			hint: "Check that the path points to a readable file.",
+			details: {
+				path,
+				code: errorCode(error)
+			}
+		});
+	}
+	try {
+		await hooks.afterOpen?.();
+		const opened = await handle.stat();
+		const now = await stat(await resolveInside());
+		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 }
+		});
+		if (!opened.isFile()) throw notAFile();
+		const tooLarge = (size) => new XlvError("XLV_E_LIMIT_EXCEEDED", `"${path}" is ${String(size)} bytes or more, more than the server's limit of ${String(roots.maxFileBytes)}.`, {
+			hint: "The limit is set when the server starts (--max-file-size).",
+			details: {
+				path,
+				limit: "maxFileBytes",
+				value: roots.maxFileBytes
+			}
+		});
+		if (opened.size > roots.maxFileBytes) throw tooLarge(opened.size);
+		await hooks.afterVerify?.();
+		const chunks = [];
+		let total = 0;
+		for (;;) {
+			const buffer = new Uint8Array(Math.min(1 << 20, roots.maxFileBytes + 1 - total));
+			if (buffer.length === 0) throw tooLarge(total);
+			const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+			if (bytesRead === 0) break;
+			chunks.push(buffer.subarray(0, bytesRead));
+			total += bytesRead;
+		}
+		const out = new Uint8Array(total);
+		let at = 0;
+		for (const c of chunks) {
+			out.set(c, at);
+			at += c.length;
+		}
+		return out;
+	} finally {
+		await handle.close();
+	}
+}
+/**
+* Writes a file inside the roots. The real path of the directory must be inside a root and the
+* file itself must not be a symbolic link. A new file is created exclusively ('wx'); an existing
+* one is replaced only with `overwrite`, through a temporary file and a rename.
+*/
+async function writeAllowed(roots, path, data, overwrite) {
+	const target = absolute(roots, path);
+	const name = basename(target);
+	if (name === "" || name === "." || name === "..") throw new XlvError("XLV_E_INVALID_INPUT", `"${path}" is not a file name.`, {
+		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 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)}.`, {
+		hint: "Write fewer rows per file.",
+		details: {
+			path,
+			limit: "maxFileBytes",
+			value: roots.maxFileBytes
+		}
+	});
+	let existing = null;
+	try {
+		const info = await lstat(file);
+		if (info.isSymbolicLink()) throw notAllowed(roots, path, " (it is a symbolic link)");
+		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: {
+				path,
+				code: "EISDIR"
+			}
+		});
+		existing = info;
+	} catch (error) {
+		if (error instanceof XlvError) throw error;
+	}
+	if (existing !== null && !overwrite) throw new XlvError("XLV_E_FILE_EXISTS", `"${path}" already exists.`, {
+		hint: "Choose another path, or pass \"overwrite\": true to replace the file.",
+		details: { path }
+	});
+	if (existing !== null && (existing.mode & 128) === 0) throw new XlvError("XLV_E_FILE_WRITE", `"${path}" is read-only.`, {
+		hint: "Write to another path, or make the file writable first.",
+		details: {
+			path,
+			code: "EACCES"
+		}
+	});
+	if (existing === null) {
+		try {
+			await writeFile(file, bytes, { flag: "wx" });
+		} catch (error) {
+			if (errorCode(error) === "EEXIST") throw new XlvError("XLV_E_FILE_EXISTS", `"${path}" already exists.`, {
+				hint: "Choose another path, or pass \"overwrite\": true to replace the file.",
+				details: { path }
+			});
+			throw new XlvError("XLV_E_FILE_WRITE", `Cannot write "${path}" (${errorCode(error)}).`, {
+				hint: "Check that the directory is writable.",
+				details: {
+					path,
+					code: errorCode(error)
+				}
+			});
+		}
+		return {
+			path,
+			bytes: bytes.length,
+			replaced: false
+		};
+	}
+	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`);
+	let created = false;
+	try {
+		await writeFile(temp, bytes, { flag: "wx" });
+		created = true;
+		await chmod(temp, existing.mode & 4095);
+		await rename(temp, file);
+	} catch (error) {
+		if (created) await rm(temp, { force: true });
+		throw new XlvError("XLV_E_FILE_WRITE", `Cannot write "${path}" (${errorCode(error)}).`, {
+			hint: "Check that the directory is writable.",
+			details: {
+				path,
+				code: errorCode(error)
+			}
+		});
+	}
+	return {
+		path,
+		bytes: bytes.length,
+		replaced: true
+	};
+}
+// src/tools.ts
+/** Problems `validate` lists; `problemsTotal` counts all of them (D-I02). */
+const MAX_PROBLEMS = 1e3;
+const READ = {
+	readOnlyHint: true,
+	openWorldHint: false
+};
+const WRITE = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	idempotentHint: false,
+	openWorldHint: false
+};
+const PATH = {
+	type: "string",
+	minLength: 1,
+	description: "File path, relative to the first allowed directory or absolute inside an allowed directory."
+};
+const SHEET = {
+	type: "string",
+	description: "Sheet name. Default: the first visible worksheet."
+};
+const OVERWRITE = {
+	type: "boolean",
+	description: "Replace the output file if it exists. Default false: an existing file is never replaced."
+};
+const HEADER = {
+	description: "Header row: \"auto\" (default) detects it, a 1-based row number, or false for no header (columns are named by letter).",
+	anyOf: [
+		{ const: "auto" },
+		{
+			type: "integer",
+			minimum: 1
+		},
+		{ const: false }
+	]
+};
+const CELL_VALUE = {
+	description: "A number, string, boolean or null (clears the cell); {\"formula\": \"SUM(A1:A3)\", \"result\": 6} for a formula (without \"=\"; xlvane does not calculate it); {\"error\": \"#N/A\"}; {\"date\": \"2024-01-31\"} for a date (ISO 8601, no time zone).",
+	anyOf: [
+		{ type: [
+			"number",
+			"string",
+			"boolean",
+			"null"
+		] },
+		{
+			type: "object",
+			properties: {
+				formula: {
+					type: "string",
+					minLength: 1
+				},
+				result: { type: [
+					"number",
+					"string",
+					"boolean",
+					"null"
+				] }
+			},
+			required: ["formula"],
+			additionalProperties: false
+		},
+		{
+			type: "object",
+			properties: { error: { enum: [...ERROR_VALUES] } },
+			required: ["error"],
+			additionalProperties: false
+		},
+		{
+			type: "object",
+			properties: { date: {
+				type: "string",
+				pattern: "^\\d{4}-\\d{2}-\\d{2}([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,3})?)?)?$"
+			} },
+			required: ["date"],
+			additionalProperties: false
+		}
+	]
+};
+function object(properties, required = []) {
+	return fromJsonSchema({
+		type: "object",
+		properties,
+		required: [...required],
+		additionalProperties: false
+	});
+}
+function ok(result, maxChars) {
+	const text = JSON.stringify(result);
+	if (text.length > maxChars) return fail(new XlvError("XLV_E_LIMIT_EXCEEDED", `The result is ${String(text.length)} characters of JSON, more than the server's limit of ${String(maxChars)}.`, {
+		hint: "Ask for less: one sheet, a smaller range, fewer changes (maxChanges) or fewer rows; the limit is set when the server starts (--max-response-chars).",
+		details: {
+			limit: "maxResponseChars",
+			value: maxChars
+		}
+	}));
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		structuredContent: result
+	};
+}
+function fail(error, maxChars = Number.POSITIVE_INFINITY) {
+	const e = isXlvError(error) ? error : new XlvError("XLV_E_INTERNAL", `Unexpected error: ${error instanceof Error ? error.message : String(error)}`, {
+		hint: "This is a bug in xlvane; the call may succeed with other input.",
+		details: { name: error instanceof Error ? error.name : typeof error }
+	});
+	let result = { error: e.toJSON() };
+	let text = JSON.stringify(result);
+	if (text.length > maxChars) {
+		const json = e.toJSON();
+		result = { error: {
+			...json,
+			message: `${json.message.slice(0, Math.max(0, Math.floor(maxChars / 4)))}…`,
+			hint: json.hint.slice(0, Math.max(0, Math.floor(maxChars / 4))),
+			details: { cut: true }
+		} };
+		text = JSON.stringify(result);
+		if (text.length > maxChars) {
+			result = { error: {
+				name: json.name,
+				code: json.code,
+				message: "The error message is longer than the result limit.",
+				location: {},
+				hint: "",
+				docsUrl: json.docsUrl,
+				details: { cut: true }
+			} };
+			text = JSON.stringify(result);
+		}
+	}
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		structuredContent: result,
+		isError: true
+	};
+}
+function handler(maxChars, run) {
+	return async (args) => {
+		try {
+			return ok(await run(args ?? {}), maxChars);
+		} catch (error) {
+			return fail(error, maxChars);
+		}
+	};
+}
+async function book(roots, path) {
+	const bytes = await readAllowed(roots, path);
+	try {
+		return readWorkbook(bytes);
+	} catch (error) {
+		throw withPath(error, path);
+	}
+}
+function withPath(error, path) {
+	if (error instanceof XlvError && error.details["path"] === void 0) return new XlvError(error.code, error.message, {
+		location: error.location,
+		hint: error.hint,
+		details: {
+			...error.details,
+			path
+		},
+		cause: error
+	});
+	return error;
+}
+function isoValues(row) {
+	return Object.fromEntries(Object.entries(row).map(([k, v]) => [k, v instanceof Date ? v.toISOString() : v]));
+}
+/** Converts a JSON cell value of the tools to a CellInput ({ date } becomes a Date, read as UTC). */
+function cellInput(value) {
+	if (value !== null && typeof value === "object" && "date" in value) {
+		const text = String(value.date).replace(" ", "T");
+		const invalid = () => new XlvError("XLV_E_INVALID_VALUE", `"${text.slice(0, 40)}" is not a valid date.`, { hint: "Use ISO 8601, for example {\"date\": \"2024-01-31\"} or {\"date\": \"2024-01-31T13:45:00\"}." });
+		const m = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?)?$/.exec(text);
+		if (m === null) throw invalid();
+		const d = /* @__PURE__ */ new Date(/T/.test(text) ? `${text}Z` : `${text}T00:00:00Z`);
+		const parts = [
+			d.getUTCFullYear(),
+			d.getUTCMonth() + 1,
+			d.getUTCDate(),
+			d.getUTCHours(),
+			d.getUTCMinutes(),
+			d.getUTCSeconds()
+		];
+		const wanted = [
+			m[1],
+			m[2],
+			m[3],
+			m[4] ?? "0",
+			m[5] ?? "0",
+			m[6] ?? "0"
+		].map(Number);
+		if (Number.isNaN(d.getTime()) || parts.some((v, i) => v !== wanted[i])) throw invalid();
+		return d;
+	}
+	return value;
+}
+function extension(path) {
+	const m = /\.([A-Za-z0-9]+)$/.exec(path);
+	return m ? m[1].toLowerCase() : "";
+}
+const TYPES = [
+	"number",
+	"string",
+	"date",
+	"boolean",
+	"any"
+];
+function typeOf(v) {
+	if (v === null || v === void 0 || v === "") return "empty";
+	if (typeof v === "number") return "number";
+	if (typeof v === "boolean") return "boolean";
+	if (v instanceof Date) return "date";
+	return "string";
+}
+/** Registers the read tools, and the write tools when writing is allowed, in a fixed order. */
+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.",
+		inputSchema: object({
+			path: PATH,
+			sheet: {
+				...SHEET,
+				description: "Describe only this sheet."
+			}
+		}, ["path"]),
+		annotations: READ
+	}, handler(limits.maxResponseChars, async (a) => {
+		const workbook = await book(roots, a["path"]);
+		const report = inspect(workbook);
+		if (typeof a["sheet"] !== "string") return report;
+		const sheet = workbook.getSheet(a["sheet"]);
+		return {
+			...report,
+			sheets: report.sheets.filter((s) => s.name === sheet.name),
+			warnings: report.warnings.filter((w) => w.location.sheet === void 0 || w.location.sheet === sheet.name)
+		};
+	}));
+	server.registerTool("read_table", {
+		title: "Read a sheet as rows",
+		description: `Reads a sheet as an array of row objects keyed by the header row (or by column letters with header: false). Dates are returned as ISO 8601 strings in UTC, error cells as their code (e.g. "#N/A"), formulas as their cached result. Returns at most ${String(limits.maxRows)} rows per call; use offset to page through larger sheets (totalRows and truncated say whether more rows exist).`,
+		inputSchema: object({
+			path: PATH,
+			sheet: SHEET,
+			range: {
+				type: "string",
+				description: "Only this A1 range, e.g. \"A1:D100\"."
+			},
+			header: HEADER,
+			offset: {
+				type: "integer",
+				minimum: 0,
+				description: "Rows to skip. Default 0."
+			},
+			limit: {
+				type: "integer",
+				minimum: 1,
+				maximum: limits.maxRows,
+				description: `Rows to return. Default ${String(Math.min(200, limits.maxRows))}.`
+			}
+		}, ["path"]),
+		annotations: READ
+	}, handler(limits.maxResponseChars, async (a) => {
+		const workbook = await book(roots, a["path"]);
+		const table = readTable(workbook, {
+			...typeof a["sheet"] === "string" ? { sheet: a["sheet"] } : {},
+			...typeof a["range"] === "string" ? { range: a["range"] } : {},
+			header: a["header"] ?? "auto"
+		});
+		const offset = a["offset"] ?? 0;
+		const limit = a["limit"] ?? Math.min(200, limits.maxRows);
+		const head = {
+			sheet: table.sheet,
+			headerRow: table.headerRow,
+			range: table.range,
+			columns: table.columns.map((c) => ({
+				key: c.key,
+				header: c.header,
+				letter: c.letter
+			}))
+		};
+		let used = JSON.stringify({
+			...head,
+			rows: [],
+			rowNumbers: [],
+			offset,
+			totalRows: table.rows.length,
+			truncated: true,
+			nextOffset: table.rows.length
+		}).length;
+		const rows = [];
+		for (let i = offset; i < Math.min(table.rows.length, offset + limit); i++) {
+			const row = isoValues(table.rows[i]);
+			const cost = JSON.stringify(row).length + String(table.rowNumbers[i]).length + 2;
+			if (used + cost > limits.maxResponseChars) break;
+			used += cost;
+			rows.push(row);
+		}
+		if (rows.length === 0 && offset < table.rows.length && limit > 0) throw new XlvError("XLV_E_LIMIT_EXCEEDED", `Row ${String(table.rowNumbers[offset])} alone is larger than the server's result limit of ${String(limits.maxResponseChars)} characters.`, {
+			hint: "Read fewer columns with range (for example \"A1:D100\"); the limit is set when the server starts (--max-response-chars).",
+			details: {
+				limit: "maxResponseChars",
+				value: limits.maxResponseChars
+			}
+		});
+		const end = offset + rows.length;
+		return {
+			...head,
+			rows,
+			rowNumbers: table.rowNumbers.slice(offset, end),
+			offset,
+			totalRows: table.rows.length,
+			truncated: end < table.rows.length,
+			...end < table.rows.length ? { nextOffset: end } : {}
+		};
+	}));
+	server.registerTool("diff", {
+		title: "Compare two workbooks",
+		description: "Compares two XLSX files cell by cell (values and formulas; formatting with styles: true). Sheets are matched by name. Use it to check the result of an edit.",
+		inputSchema: object({
+			before: PATH,
+			after: PATH,
+			styles: {
+				type: "boolean",
+				description: "Also compare cell formatting. Default false."
+			},
+			maxChanges: {
+				type: "integer",
+				minimum: 1,
+				maximum: 1e4,
+				description: "Changes listed per sheet. Default 200; the summary always counts all of them."
+			}
+		}, ["before", "after"]),
+		annotations: READ
+	}, handler(limits.maxResponseChars, async (a) => {
+		const before = await book(roots, a["before"]);
+		const after = await book(roots, a["after"]);
+		const r = diff(before, after, { styles: a["styles"] === true });
+		const max = a["maxChanges"] ?? 200;
+		return {
+			...r,
+			sheets: r.sheets.map((s) => ({
+				...s,
+				cells: s.cells.slice(0, max),
+				listed: Math.min(max, s.cells.length),
+				total: s.cells.length
+			}))
+		};
+	}));
+	server.registerTool("validate", {
+		title: "Check a workbook and its columns",
+		description: "Reports read warnings of an XLSX file and, with columns, checks a table: each listed column must exist in the header row, its cells must not be empty unless optional is true, and must have the given type. Each problem names the cell. ok is false when problems were found (warnings count only with strict: true).",
+		inputSchema: object({
+			path: PATH,
+			sheet: SHEET,
+			columns: {
+				type: "array",
+				maxItems: 256,
+				items: {
+					type: "object",
+					properties: {
+						name: {
+							type: "string",
+							minLength: 1
+						},
+						type: { enum: [...TYPES] },
+						optional: { type: "boolean" }
+					},
+					required: ["name"],
+					additionalProperties: false
+				},
+				description: "Column rules, matched to the header row by name. type defaults to \"any\"."
+			},
+			strict: {
+				type: "boolean",
+				description: "Treat warnings as problems. Default false."
+			}
+		}, ["path"]),
+		annotations: READ
+	}, handler(limits.maxResponseChars, async (a) => {
+		const workbook = await book(roots, a["path"]);
+		const warnings = inspect(workbook).warnings;
+		const rules = a["columns"] ?? [];
+		const names = /* @__PURE__ */ new Set();
+		for (const rule of rules) {
+			if (names.has(rule.name)) throw new XlvError("XLV_E_INVALID_INPUT", `Column "${rule.name.slice(0, 100)}" has more than one rule.`, {
+				hint: "Give each column one rule.",
+				details: { column: rule.name.slice(0, 100) }
+			});
+			names.add(rule.name);
+		}
+		const problems = [];
+		let problemsTotal = 0;
+		const problem = (p) => {
+			problemsTotal++;
+			if (problems.length < MAX_PROBLEMS) problems.push(p());
+		};
+		let sheetName = null;
+		let rowsChecked = 0;
+		if (rules.length > 0) {
+			const table = readTable(workbook, typeof a["sheet"] === "string" ? { sheet: a["sheet"] } : {});
+			sheetName = table.sheet;
+			rowsChecked = table.rows.length;
+			for (const rule of rules) {
+				const column = table.columns.find((c) => c.header === rule.name);
+				if (!column) {
+					problem(() => ({
+						kind: "missing-column",
+						column: rule.name,
+						cell: null,
+						row: table.headerRow,
+						message: `Column "${rule.name}" is missing from the header row.`
+					}));
+					continue;
+				}
+				table.rows.forEach((row, i) => {
+					const cell = `${column.letter}${String(table.rowNumbers[i])}`;
+					const t = typeOf(row[column.key]);
+					const want = rule.type ?? "any";
+					if (t === "empty") {
+						if (rule.optional !== true) problem(() => ({
+							kind: "empty",
+							column: rule.name,
+							cell,
+							row: table.rowNumbers[i],
+							message: `${cell} is empty; "${rule.name}" needs a value.`
+						}));
+					} else if (want !== "any" && t !== want) problem(() => ({
+						kind: "type",
+						column: rule.name,
+						cell,
+						row: table.rowNumbers[i],
+						message: `${cell} is a ${t}; "${rule.name}" needs a ${want}.`
+					}));
+				});
+			}
+		}
+		return {
+			ok: problemsTotal === 0 && (a["strict"] !== true || warnings.length === 0),
+			sheet: sheetName,
+			rowsChecked,
+			problems,
+			problemsTotal,
+			warnings
+		};
+	}));
+	if (!allowWrite) return;
+	server.registerTool("write_table", {
+		title: "Write rows to a new XLSX file",
+		description: "Writes an array of row objects (or arrays) to an XLSX file. The \"report\" preset (default) adds a bold header row, frozen first row, autofilter, fitted column widths and date and number formats; \"plain\" writes values only. Strings that look like ISO dates stay strings; pass {\"date\": \"...\"} for dates.",
+		inputSchema: object({
+			path: PATH,
+			rows: {
+				type: "array",
+				items: { type: ["object", "array"] },
+				description: "Row objects (keys become columns) or arrays."
+			},
+			columns: {
+				type: "array",
+				items: { type: "string" },
+				description: "Keys to include, in this order. Default: every key, in order of first appearance."
+			},
+			sheet: {
+				type: "string",
+				description: "Sheet name. Default \"Sheet1\"."
+			},
+			preset: { enum: ["report", "plain"] },
+			overwrite: OVERWRITE
+		}, ["path", "rows"]),
+		annotations: WRITE
+	}, handler(limits.maxResponseChars, async (a) => {
+		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"] } : {},
+			...typeof a["sheet"] === "string" ? { sheet: a["sheet"] } : {},
+			...typeof a["preset"] === "string" ? { preset: a["preset"] } : {}
+		});
+		return {
+			...await writeAllowed(roots, a["path"], bytes, a["overwrite"] === true),
+			rows: rows.length
+		};
+	}));
+	server.registerTool("edit_cells", {
+		title: "Change cells or append rows",
+		description: "Changes cells and appends rows in an existing XLSX file while keeping everything else in it (styles, formulas, other sheets) unchanged. The result is written to output; to change the file in place, omit output and pass \"overwrite\": true. xlvane does not calculate formulas; the edited file asks spreadsheet programs to recalculate them when it is opened.",
+		inputSchema: object({
+			path: PATH,
+			edits: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: {
+						sheet: {
+							type: "string",
+							minLength: 1
+						},
+						cell: {
+							type: "string",
+							pattern: "^[A-Za-z]{1,3}[1-9][0-9]{0,6}$"
+						},
+						value: CELL_VALUE
+					},
+					required: [
+						"sheet",
+						"cell",
+						"value"
+					],
+					additionalProperties: false
+				},
+				description: "Cells to set, e.g. [{\"sheet\": \"Sales\", \"cell\": \"B2\", \"value\": 1250}]."
+			},
+			append: {
+				type: "object",
+				properties: {
+					sheet: {
+						type: "string",
+						minLength: 1
+					},
+					rows: {
+						type: "array",
+						items: { type: ["object", "array"] }
+					},
+					header: {
+						type: "integer",
+						minimum: 1,
+						description: "Row that holds the column names, for object rows. Default: detected."
+					}
+				},
+				required: ["sheet", "rows"],
+				additionalProperties: false,
+				description: "Rows to add below the last row; object keys are matched to the header row."
+			},
+			output: {
+				...PATH,
+				description: "Where to write the result. Default: the input file, which requires \"overwrite\": true."
+			},
+			overwrite: OVERWRITE
+		}, ["path"]),
+		annotations: WRITE
+	}, handler(limits.maxResponseChars, async (a) => {
+		const path = a["path"];
+		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\"}." });
+		let bytes = await readAllowed(roots, path);
+		const warnings = [];
+		try {
+			if (edits.length > 0) {
+				const r = editCells(bytes, edits.map((e) => ({
+					sheet: e.sheet,
+					cell: e.cell.toUpperCase(),
+					value: cellInput(e.value)
+				})));
+				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);
+				bytes = r.bytes;
+				warnings.push(...r.warnings);
+			}
+		} catch (error) {
+			throw withPath(error, path);
+		}
+		return {
+			...await writeAllowed(roots, typeof a["output"] === "string" ? a["output"] : path, bytes, a["overwrite"] === true),
+			cellsSet: edits.length,
+			rowsAppended: append?.rows.length ?? 0,
+			warnings
+		};
+	}));
+	server.registerTool("convert", {
+		title: "Convert between XLSX, CSV and JSON",
+		description: "Converts a sheet of an XLSX file to CSV, TSV or JSON (an array of row objects), or CSV, TSV or JSON to a plain XLSX file. Formats come from the file extensions. CSV output escapes text that starts with =, +, -, @ and similar characters, so spreadsheet programs do not run it as a formula; dates are written as ISO 8601.",
+		inputSchema: object({
+			input: PATH,
+			output: PATH,
+			sheet: {
+				type: "string",
+				description: "Sheet to convert (XLSX input), or the sheet name (XLSX output)."
+			},
+			delimiter: {
+				type: "string",
+				minLength: 1,
+				maxLength: 1,
+				description: "CSV delimiter. Default \",\" (tab for .tsv)."
+			},
+			overwrite: OVERWRITE
+		}, ["input", "output"]),
+		annotations: WRITE
+	}, handler(limits.maxResponseChars, async (a) => {
+		const input = a["input"];
+		const output = a["output"];
+		const from = extension(input);
+		const to = extension(output);
+		const tables = [
+			"csv",
+			"tsv",
+			"json"
+		];
+		const books = ["xlsx", "xlsm"];
+		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, {
+				...sheet,
+				delimiter: a["delimiter"] ?? (to === "tsv" ? "	" : ",")
+			});
+		} else if (tables.includes(from) && to === "xlsx") {
+			let text;
+			try {
+				text = new TextDecoder("utf-8", { fatal: true }).decode(await readAllowed(roots, input));
+			} catch (error) {
+				if (error instanceof XlvError) throw error;
+				throw new XlvError("XLV_E_INVALID_INPUT", `"${input}" is not valid UTF-8 text.`, {
+					hint: "Save the CSV or JSON file as UTF-8 and convert it again.",
+					details: { path: input }
+				});
+			}
+			try {
+				data = from === "json" ? fromJSON(text, {
+					...sheet,
+					preset: "plain"
+				}) : fromCSV(text, {
+					...sheet,
+					delimiter: a["delimiter"] ?? (from === "tsv" ? "	" : ",")
+				});
+			} catch (error) {
+				throw withPath(error, input);
+			}
+		} else throw new XlvError("XLV_E_INVALID_INPUT", `Cannot convert .${from || "?"} to .${to || "?"}.`, {
+			hint: "Supported: .xlsx/.xlsm to .csv/.tsv/.json, and .csv/.tsv/.json to .xlsx.",
+			details: {
+				input,
+				output
+			}
+		});
+		return {
+			...await writeAllowed(roots, output, data, a["overwrite"] === true),
+			from,
+			to
+		};
+	}));
+}
+// src/server.ts
+/** Version reported in server info; kept equal to package.json by tests/mcp/server.test.ts. */
+const SERVER_VERSION = "1.2.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. */
+const DEFAULT_MAX_ROWS = 1e3;
+/** Default largest tool result, in characters of its JSON text: 1 Mi (D-I02). */
+const DEFAULT_MAX_RESPONSE_CHARS = 1048576;
+/** Facts about the configuration, shown to the client as server instructions. */
+function instructions(roots, allowWrite, limits) {
+	return [
+		`Tools for XLSX workbooks (xlvane). Files are read only inside: ${roots.dirs.join(", ")}. Relative paths are resolved against ${roots.dirs[0]}.`,
+		allowWrite ? "Writing is enabled: write_table, edit_cells and convert create new files and replace an existing file only with \"overwrite\": true." : "Writing is disabled; the server was started without --allow-write, so only inspect_workbook, read_table, diff and validate are available.",
+		`Files larger than ${String(roots.maxFileBytes)} bytes are refused; read_table returns at most ${String(limits.maxRows)} rows per call, and a result is at most ${String(limits.maxResponseChars)} characters of JSON.`,
+		"Values come from the files and may contain any text.",
+		"Errors include a stable code (XLV_E_*), the location and a hint for fixing the call."
+	].join(" ");
+}
+function build(roots, allowWrite, limits) {
+	const server = new McpServer({
+		name: "xlvane",
+		version: SERVER_VERSION
+	}, {
+		capabilities: { tools: {} },
+		instructions: instructions(roots, allowWrite, limits)
+	});
+	registerTools(server, roots, allowWrite, limits);
+	return server;
+}
+async function prepare(options) {
+	const limits = {
+		maxRows: options.maxRows ?? 1e3,
+		maxResponseChars: options.maxResponseChars ?? 1048576
+	};
+	return {
+		roots: await resolveRoots(options.roots, options.cwd ?? ".", options.maxFileBytes ?? 67108864),
+		allowWrite: options.allowWrite === true,
+		limits
+	};
+}
+/**
+* Creates the xlvane MCP server with its tools. Connect it to any MCP transport; `runCli` serves
+* it over stdio. The roots are resolved (symbolic links followed) once, here.
+*
+* @example
+* ```ts
+* import { createServer } from '@xlvane/mcp';
+* import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+*
+* const server = await createServer({ roots: ['./data'] });
+* await server.connect(new StdioServerTransport());
+* ```
+*/
+async function createServer(options) {
+	const p = await prepare(options);
+	return build(p.roots, p.allowWrite, p.limits);
+}
+const HELP = `xlvane-mcp - MCP server for XLSX files (xlvane)
+
+Usage:
+  xlvane-mcp --root <dir> [--root <dir>...] [options]
+  xlvane mcp --root <dir> [options]
+
+Options:
+  --root <dir>            Directory the tools may use (repeatable, at least one)
+  --allow-write           Also offer write_table, edit_cells and convert
+  --max-file-size <bytes> Largest file read or written (default ${String(DEFAULT_MAX_FILE_BYTES)})
+  --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)})
+  -h, --help              Show this help
+
+The server speaks MCP over stdin and stdout; messages for people go to stderr.
+Example client configuration: {"command": "npx", "args": ["@xlvane/mcp", "--root", "/path/to/data"]}
+`;
+function positive(value, name) {
+	if (value === void 0) return void 0;
+	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);
+}
+/** runCli with its environment passed in (tests). */
+async function runWith(args, io) {
+	let values;
+	try {
+		values = parseArgs({
+			args: [...args],
+			options: {
+				root: {
+					type: "string",
+					multiple: true
+				},
+				"allow-write": { type: "boolean" },
+				"max-file-size": { type: "string" },
+				"max-rows": { type: "string" },
+				"max-response-chars": { type: "string" },
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			},
+			strict: true,
+			allowPositionals: false,
+			tokens: true
+		}).values;
+	} catch (error) {
+		io.stderr(`xlvane-mcp: ${error instanceof Error ? error.message : String(error)}\nRun "xlvane-mcp --help" for the options.\n`);
+		return 2;
+	}
+	if (values["help"] === true) {
+		io.stdout(HELP);
+		return 0;
+	}
+	let prepared;
+	try {
+		const roots = values["root"] ?? [];
+		if (roots.length === 0) {
+			io.stderr("xlvane-mcp: no directory was given.\nStart the server with the directories it may use, for example: xlvane-mcp --root ./data\n");
+			return 2;
+		}
+		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");
+		prepared = await prepare({
+			roots,
+			cwd: io.cwd,
+			allowWrite: values["allow-write"] === true,
+			...maxFileBytes !== void 0 ? { maxFileBytes } : {},
+			...maxRows !== void 0 ? { maxRows } : {},
+			...maxResponseChars !== void 0 ? { maxResponseChars } : {}
+		});
+	} catch (error) {
+		io.stderr(`xlvane-mcp: ${error instanceof Error ? error.message : String(error)}\n${isXlvError(error) ? `${error.hint}\n` : ""}`);
+		return isXlvError(error) ? 3 : 2;
+	}
+	const { roots, allowWrite, limits } = prepared;
+	io.stderr(`xlvane-mcp ${SERVER_VERSION}: serving ${roots.dirs.join(", ")} over stdio${allowWrite ? " (writing enabled)" : " (read-only)"}.\n`);
+	await io.serve(() => build(roots, allowWrite, limits));
+	return 0;
+}
+/**
+* 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
+* code. `xlvane mcp` calls this function.
+*
+* @example
+* ```ts
+* import { runCli } from '@xlvane/mcp';
+*
+* const code = await runCli(['--root', './data', '--allow-write']);
+* ```
+*/
+async function runCli(args) {
+	const { default: process } = await import("node:process");
+	return runWith(args, {
+		stdout: (text) => {
+			process.stdout.write(text);
+		},
+		stderr: (text) => {
+			process.stderr.write(text);
+		},
+		cwd: process.cwd(),
+		serve: (factory) => new Promise((resolve) => {
+			serveStdio(factory);
+			process.stdin.once("end", () => resolve());
+			process.stdin.once("close", () => resolve());
+		})
+	});
+}
+export { runCli as n, createServer as t };

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@xlvane/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "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",
+    "excel",
+    "spreadsheet",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/DevXord/xlvane#readme",
+  "bugs": {
+    "url": "https://github.com/DevXord/xlvane/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DevXord/xlvane.git",
+    "directory": "packages/mcp"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "xlvane-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.4.0",
+    "xlvane": "^1.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}