@imenam/xls-reader 2.2.0 → 2.4.0

package/README.md

@@ -1,145 +1,164 @@
-# @imenam/xls-reader
-
-An MCP (Model Context Protocol) server that lets AI agents read Excel files. It can list the sheets of a workbook and render any sheet as a Markdown table, with smart handling of empty rows, empty cells, and in-cell line breaks, plus a configurable size limit to keep responses LLM-friendly.
-
-Supports `.xlsx`, `.xls`, `.ods` and `.csv` (anything [SheetJS](https://sheetjs.com/) can read).
-
-## Where the file comes from
-
-Both tools take the workbook either **by path** or **by content**:
-
-- `file_path` — a path on the machine *running the server*. This is what a caller provides.
-- `file_content` — the file itself, base64-encoded (a `data:…;base64,` prefix is accepted), with `file_name` to label the output.
-
-At least one of the two is required. When both are given, `file_content` wins.
-
-**When the server runs on another machine, the content is what must travel** — a path would point at a file the server cannot see. That translation is not the agent's job: the client-side relay does it. With [`@imenam/mcp-http-gateway`](https://www.npmjs.com/package/@imenam/mcp-http-gateway) in `--mcp` mode, the relay runs next to the agent, reads the file named by `file_path`, sends `file_content`, and hides `file_content` / `file_name` from the schema it publishes — so the agent only ever names a path. Enable it with `GATEWAY_INLINE_ROOTS`, which also confines *which* folders can be read; see that package's README.
-
-Over stdio on a single machine, `file_path` is read directly and nothing else is needed.
-
-## Tools
-
-### `list_sheets`
-
-Lists all sheet names (tabs) in a workbook.
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `file_path` | `string` | ⚠️ | Path to the Excel file. Resolved on the server, or read by the relay (see above) |
-| `file_content` | `string` | ⚠️ | Base64 content of the file. Normally filled in by the relay, not by the agent |
-| `file_name` | `string` | ❌ | Original file name, used only for labelling. Filled in with `file_content` |
-
-Returns the sheet names, one per line.
-
-### `get_sheet`
-
-Reads a sheet and returns its content as a Markdown table.
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `file_path` | `string` | ⚠️ | Path to the Excel file. Resolved on the server, or read by the relay (see above) |
-| `file_content` | `string` | ⚠️ | Base64 content of the file. Normally filled in by the relay, not by the agent |
-| `file_name` | `string` | ❌ | Original file name, used only for labelling. Filled in with `file_content` |
-| `sheet_name` | `string` | ⚠️ | Name of the sheet to read. Required for `markdown`/`json`. For `json-file`: omit to export the whole workbook, or set it to export only that sheet |
-| `format` | `"markdown" \| "json" \| "json-file"` | ❌ | Output format (default: `markdown`) |
-| `output_path` | `string` | ⚠️ | Destination file for the JSON export (required when `format` is `json-file`) |
-| `cell_budget` | `number` | ❌ | Maximum number of cells to return (cols × rows). Default: `2000` |
-| `max_cols` | `number` | ❌ | Override the maximum number of columns |
-| `max_rows` | `number` | ❌ | Override the maximum number of rows |
-| `header_row` | `boolean` | ❌ | Treat the first row as a column header (default: `true`) |
-
-#### Smart content handling
-
-- **Empty rows are section separators.** A fully empty row closes the current table and starts a new one; when `header_row` is enabled, the header is repeated on each section.
-- **Empty cells are kept as blanks** so columns stay aligned.
-- **In-cell line breaks** are converted to a literal `\n` so they don't break the Markdown table row.
-- **Dates and booleans** are rendered as readable text rather than Excel serial numbers.
-
-#### Output formats
-
-With `format: "markdown"` (default) you get one Markdown table per section.
-
-With `format: "json"` you get a structured object — better when the agent needs to *process* the data rather than read it. Native types are preserved (numbers, booleans, dates as ISO strings) and real line breaks are kept:
-
-```json
-{
-  "sheet": "Feuille1",
-  "truncated": false,
-  "groups": [
-    [
-      { "Nom": "Dupont", "Prénom": "Jean", "Age": 42 },
-      { "Nom": "Martin", "Age": 35 }
-    ]
-  ]
-}
-```
-
-- `groups` is an array of sections (one per block separated by an empty row).
-- With `header_row: true`, each row is an **object** keyed by column name; **empty cells are omitted**.
-- With `header_row: false`, each row is an **array** of values (empty cells become `null`).
-- When data is truncated, `truncated` is `true` and a `note` field explains what was omitted.
-
-With `format: "json-file"` the data (no size limit) is written to `output_path` **on the server's disk** and the tool returns the saved path. Use this when the data is too large to return inline. By default the **entire workbook** is exported; provide `sheet_name` to export only that one sheet. Size limits are ignored. The file content is:
-
-```json
-{
-  "file": "data.xlsx",
-  "sheets": [
-    { "sheet": "Feuille1", "groups": [ /* …same shape as json… */ ] },
-    { "sheet": "Feuille2", "groups": [ /* … */ ] }
-  ]
-}
-```
-
-#### Size limit
-
-By default the response is capped at `cell_budget = 2000` cells (`cols × rows`). With 10 columns you get ~200 rows; with 20 columns, ~100 rows. When data is truncated, a warning is appended telling you how much was omitted. Override with `cell_budget`, `max_cols`, or `max_rows` to read more (or less).
-
-## Installation
-
-```bash
-npm install -g @imenam/xls-reader
-```
-
-Or use it directly with `npx`:
-
-```json
-{
-  "xls-reader": {
-    "command": "npx",
-    "args": ["-y", "@imenam/xls-reader"]
-  }
-}
-```
-
-Or point to a local build:
-
-```json
-{
-  "xls-reader": {
-    "command": "node",
-    "args": ["/absolute/path/to/xls-reader/dist/index.js"]
-  }
-}
-```
-
-## Configuration
-
-No environment variables are required. Optionally, set `MCP_LOG_DIR` to change where logs are written (default: `C:\var\log\xls-reader` on Windows, `/var/log/xls-reader` otherwise).
-
-```env
-# .env
-MCP_LOG_DIR=/absolute/path/to/logs
-```
-
-## Development
-
-```bash
-npm install
-npm run build      # compile TypeScript to dist/
-npm run dev        # run from source with tsx
-```
-
-## License
-
-MIT
+# @imenam/xls-reader
+
+An MCP (Model Context Protocol) server that lets AI agents read Excel files. It can list the sheets of a workbook and render any sheet as a Markdown table, with smart handling of empty rows, empty cells, and in-cell line breaks, plus a configurable size limit to keep responses LLM-friendly.
+
+Supports `.xlsx`, `.xls`, `.ods` and `.csv` (anything [SheetJS](https://sheetjs.com/) can read).
+
+## Where the file comes from
+
+Both tools take the workbook either **by path** or **by content**:
+
+- `file_path` — a path on the machine *running the server*. This is what a caller provides.
+- `file_content` — the file itself, base64-encoded (a `data:…;base64,` prefix is accepted), with `file_name` to label the output.
+
+At least one of the two is required. When both are given, `file_content` wins.
+
+**When the server runs on another machine, the content is what must travel** — a path would point at a file the server cannot see. That translation is not the agent's job: the client-side relay does it. With [`@imenam/mcp-http-gateway`](https://www.npmjs.com/package/@imenam/mcp-http-gateway) in `--mcp` mode, the relay runs next to the agent, reads the file named by `file_path`, sends `file_content`, and hides `file_content` / `file_name` from the schema it publishes — so the agent only ever names a path. Enable it with `GATEWAY_INLINE_ROOTS`, which also confines *which* folders can be read; see that package's README.
+
+Over stdio on a single machine, `file_path` is read directly and nothing else is needed.
+
+## Tools
+
+### `list_sheets`
+
+Lists all sheet names (tabs) in a workbook.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `file_path` | `string` | ⚠️ | Path to the Excel file. Resolved on the server, or read by the relay (see above) |
+| `file_content` | `string` | ⚠️ | Base64 content of the file. Normally filled in by the relay, not by the agent |
+| `file_name` | `string` | ❌ | Original file name, used only for labelling. Filled in with `file_content` |
+
+Returns the sheet names, one per line.
+
+### `get_sheet`
+
+Reads a sheet and returns its content as a Markdown table.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `file_path` | `string` | ⚠️ | Path to the Excel file. Resolved on the server, or read by the relay (see above) |
+| `file_content` | `string` | ⚠️ | Base64 content of the file. Normally filled in by the relay, not by the agent |
+| `file_name` | `string` | ❌ | Original file name, used only for labelling. Filled in with `file_content` |
+| `sheet_name` | `string` | ✅ | Name of the sheet to read |
+| `format` | `"markdown" \| "json"` | ❌ | Output format (default: `markdown`) |
+| `cell_budget` | `number` | ❌ | Maximum number of cells to return (cols × rows). Default: `2000` |
+| `max_cols` | `number` | ❌ | Override the maximum number of columns |
+| `max_rows` | `number` | ❌ | Override the maximum number of rows |
+| `header_row` | `boolean` | ❌ | Treat the first row as a column header (default: `true`) |
+
+#### Smart content handling
+
+- **Empty rows are section separators.** A fully empty row closes the current table and starts a new one; when `header_row` is enabled, the header is repeated on each section.
+- **Empty cells are kept as blanks** so columns stay aligned.
+- **In-cell line breaks** are converted to a literal `\n` so they don't break the Markdown table row.
+- **Dates and booleans** are rendered as readable text rather than Excel serial numbers.
+
+#### Output formats
+
+With `format: "markdown"` (default) you get one Markdown table per section.
+
+With `format: "json"` you get a structured object — better when the agent needs to *process* the data rather than read it. Native types are preserved (numbers, booleans, dates as ISO strings) and real line breaks are kept:
+
+```json
+{
+  "sheet": "Feuille1",
+  "truncated": false,
+  "groups": [
+    [
+      { "Nom": "Dupont", "Prénom": "Jean", "Age": 42 },
+      { "Nom": "Martin", "Age": 35 }
+    ]
+  ]
+}
+```
+
+- `groups` is an array of sections (one per block separated by an empty row).
+- With `header_row: true`, each row is an **object** keyed by column name; **empty cells are omitted**.
+- With `header_row: false`, each row is an **array** of values (empty cells become `null`).
+- When data is truncated, `truncated` is `true` and a `note` field explains what was omitted.
+
+To export without any size limit, use [`export_workbook`](#export_workbook), which writes a JSON file instead of returning it.
+
+#### Size limit
+
+By default the response is capped at `cell_budget = 2000` cells (`cols × rows`). With 10 columns you get ~200 rows; with 20 columns, ~100 rows. When data is truncated, a warning is appended telling you how much was omitted. Override with `cell_budget`, `max_cols`, or `max_rows` to read more (or less).
+
+### `export_workbook`
+
+Exports a workbook as a JSON file, with **no size limit**, and writes it **on the agent machine**. Use it when the data is too large to return inline. By default the entire workbook is exported; provide `sheet_name` to export only one sheet.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `file_path` | `string` | ⚠️ | Path to the Excel file. Resolved on the server, or read by the relay (see above) |
+| `file_content` | `string` | ⚠️ | Base64 content of the file. Normally filled in by the relay, not by the agent |
+| `file_name` | `string` | ❌ | Original file name, used only for labelling. Filled in with `file_content` |
+| `sheet_name` | `string` | ❌ | Omit to export the whole workbook, or set it to export only that sheet |
+| `header_row` | `boolean` | ❌ | Treat the first row as a column header (default: `true`) |
+| `destination_path` | `string` | ✅ | **Absolute directory** on the agent machine. Created if missing |
+| `filename` | `string` | ✅ | Name the exported file gets there, e.g. `data.json`. No path separators |
+| `destination_overwrite` | `boolean` | ❌ | Replace the destination file if it exists (default: `false`) |
+| `destination_relay` | `boolean` | ❌ | Filled in by the relay, never by the agent |
+
+The exported file never passes through the conversation. When this MCP runs next to the agent (stdio), it writes the file itself. Behind [`@imenam/mcp-http-gateway`](https://www.npmjs.com/package/@imenam/mcp-http-gateway) it runs on the gateway's machine and cannot reach the agent's disk: it then returns the bytes, and the relay — which *does* run on the agent machine — writes them at `destination_path`. That path requires `GATEWAY_INLINE_WRITE_ROOTS` in the relay's `env` block; without it the call fails explicitly rather than dropping the file on the wrong machine.
+
+The file content is:
+
+```json
+{
+  "file": "data.xlsx",
+  "sheets": [
+    { "sheet": "Feuille1", "groups": [ /* …same shape as json… */ ] },
+    { "sheet": "Feuille2", "groups": [ /* … */ ] }
+  ]
+}
+```
+
+## Installation
+
+```bash
+npm install -g @imenam/xls-reader
+```
+
+Or use it directly with `npx`:
+
+```json
+{
+  "xls-reader": {
+    "command": "npx",
+    "args": ["-y", "@imenam/xls-reader"]
+  }
+}
+```
+
+Or point to a local build:
+
+```json
+{
+  "xls-reader": {
+    "command": "node",
+    "args": ["/absolute/path/to/xls-reader/dist/index.js"]
+  }
+}
+```
+
+## Configuration
+
+No environment variables are required. Optionally, set `MCP_LOG_DIR` to change where logs are written (default: `C:\var\log\xls-reader` on Windows, `/var/log/xls-reader` otherwise).
+
+```env
+# .env
+MCP_LOG_DIR=/absolute/path/to/logs
+```
+
+## Development
+
+```bash
+npm install
+npm run build      # compile TypeScript to dist/
+npm run dev        # run from source with tsx
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -2,12 +2,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import dotenv from "dotenv";
-import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod";
 import { setupLogging } from "./logger.js";
 import { listSheets, readSheet, readWorkbook } from "./excel.js";
+import { deliverFile, RELAY_SHAPE_DESCRIPTIONS } from "./relay.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
 dotenv.config({ path: path.join(rootDir, ".env"), override: true });
@@ -63,22 +63,17 @@ server.tool("get_sheet", [
     "Empty rows are treated as section separators — they close the current table and start a new one.",
     "format='markdown' (default) returns Markdown table(s); format='json' returns { sheet, truncated, groups }",
     "where groups is an array of sections. With header_row, each row is an object keyed by column name (empty cells omitted, types preserved); otherwise each row is an array of values.",
-    "format='json-file' writes JSON (no size limit) to output_path (required) and returns the path; it exports the whole workbook, or only sheet_name when provided. Size limits are ignored.",
-    "Data is limited by a cell budget (cols × rows, default 2000) for 'markdown' and 'json'. Use max_cols / max_rows / cell_budget to override.",
+    "To export without any size limit, use export_workbook, which writes a JSON file instead of returning it.",
+    "Data is limited by a cell budget (cols × rows, default 2000). Use max_cols / max_rows / cell_budget to override.",
 ].join(" "), {
     ...sourceShape,
     sheet_name: z
         .string()
-        .optional()
-        .describe("Name of the sheet to read. Required for 'markdown'/'json'. For 'json-file': omit to export the whole workbook, or provide it to export only that sheet"),
+        .describe("Name of the sheet to read"),
     format: z
-        .enum(["markdown", "json", "json-file"])
-        .optional()
-        .describe("Output format: 'markdown' (default), 'json', or 'json-file' (whole workbook to disk)"),
-    output_path: z
-        .string()
+        .enum(["markdown", "json"])
         .optional()
-        .describe("Destination path on the server's disk for the JSON export (required when format is 'json-file')"),
+        .describe("Output format: 'markdown' (default) or 'json'"),
     cell_budget: z
         .number()
         .optional()
@@ -89,30 +84,9 @@ server.tool("get_sheet", [
         .boolean()
         .optional()
         .describe("Treat the first row as a column header (default: true)"),
-}, async ({ sheet_name, format, output_path, cell_budget, max_cols, max_rows, header_row, ...rest }) => {
+}, async ({ sheet_name, format, cell_budget, max_cols, max_rows, header_row, ...rest }) => {
     try {
         const source = toSource(rest);
-        if (format === "json-file") {
-            if (!output_path) {
-                return {
-                    content: [{ type: "text", text: "Error: output_path is required when format is 'json-file'." }],
-                    isError: true,
-                };
-            }
-            const json = readWorkbook(source, { headerRow: header_row, sheetName: sheet_name });
-            const resolved = path.resolve(output_path);
-            fs.mkdirSync(path.dirname(resolved), { recursive: true });
-            fs.writeFileSync(resolved, json, "utf-8");
-            return {
-                content: [{ type: "text", text: `Workbook exported to ${resolved}` }],
-            };
-        }
-        if (!sheet_name) {
-            return {
-                content: [{ type: "text", text: "Error: sheet_name is required." }],
-                isError: true,
-            };
-        }
         const output = readSheet(source, sheet_name, {
             format,
             cellBudget: cell_budget,
@@ -132,6 +106,54 @@ server.tool("get_sheet", [
         };
     }
 });
+// ─── export_workbook ──────────────────────────────────────────────────────────
+// L'export est un outil à part, et non un `format` de get_sheet : le relais rend
+// obligatoire tout `<x>_path` dont il voit la paire, donc porter `destination_path` dans
+// get_sheet forcerait une destination sur chaque simple lecture de feuille.
+server.tool("export_workbook", [
+    "Export an Excel workbook as a JSON file written on the agent machine, with no size limit.",
+    "Exports the whole workbook, or only sheet_name when provided.",
+    "Pass file_path when the file sits on the machine running this server, or file_content (base64) when it does not.",
+    "The exported file never passes through the conversation.",
+].join(" "), {
+    ...sourceShape,
+    sheet_name: z
+        .string()
+        .optional()
+        .describe("Omit to export the whole workbook, or provide it to export only that sheet"),
+    header_row: z
+        .boolean()
+        .optional()
+        .describe("Treat the first row as a column header (default: true)"),
+    destination_path: z.string().describe(RELAY_SHAPE_DESCRIPTIONS.destination_path),
+    filename: z.string().describe(RELAY_SHAPE_DESCRIPTIONS.filename),
+    destination_overwrite: z
+        .boolean()
+        .optional()
+        .describe(RELAY_SHAPE_DESCRIPTIONS.destination_overwrite),
+    destination_relay: z
+        .boolean()
+        .optional()
+        .describe(RELAY_SHAPE_DESCRIPTIONS.destination_relay),
+}, async ({ sheet_name, header_row, destination_path, filename, destination_overwrite, destination_relay, ...rest }) => {
+    try {
+        const json = readWorkbook(toSource(rest), { headerRow: header_row, sheetName: sheet_name });
+        const blocks = deliverFile(Buffer.from(json, "utf-8"), "application/json", {
+            destination_path,
+            filename,
+            destination_overwrite,
+            destination_relay,
+        });
+        return { content: blocks };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
 // ─── main ─────────────────────────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/dist/relay.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+// Un fichier produit par ce MCP n'a aucun moyen d'atteindre la machine de l'agent quand
+// le MCP tourne derrière mcp-http-gateway : le protocole n'offre au serveur aucune
+// primitive pour y écrire. La convention du relais règle ça — dès qu'un outil déclare la
+// paire `destination_path` / `destination_relay`, le relais retient la destination, pose
+// `destination_relay`, et écrit lui-même les octets qu'on lui renvoie.
+//
+// Ici, on ne sait pas si un relais est dans la chaîne : `destination_relay` le dit. Posé,
+// on renvoie le contenu ; absent, les deux machines n'en font qu'une et on écrit nous-même.
+/** Plafond de ce qui peut être encodé dans une réponse d'outil. Le relais applique sa
+ *  propre limite, configurable ; celle-ci n'existe que pour qu'un fichier démesuré
+ *  échoue proprement ici plutôt qu'en épuisant la mémoire pendant l'encodage base64. */
+const RELAY_MAX_BYTES = 32 * 1024 * 1024;
+export const RELAY_SHAPE_DESCRIPTIONS = {
+    destination_path: "ABSOLUTE path of the destination DIRECTORY on the agent machine. It is created if missing, and the file keeps the name given in filename",
+    filename: "Name of the file to create, extension included (e.g. 'workbook.json'). Must not contain path separators",
+    destination_overwrite: "Replace the destination file if it already exists. Defaults to false",
+    destination_relay: "Filled in by the mcp-http-gateway relay, never by the agent. Signals that the destination lives on another machine and that the file content must travel in the response",
+};
+/**
+ * Livre un fichier produit par le MCP, du bon côté de la chaîne.
+ *
+ * Renvoie les blocs de contenu à faire figurer dans le résultat de l'outil : un bloc
+ * `resource` que le relais interceptera et retirera, ou une simple confirmation quand
+ * l'écriture a eu lieu ici. Toute impossibilité est une erreur franche : mieux vaut un
+ * fichier perdu qu'un fichier écrit sur la mauvaise machine.
+ */
+export function deliverFile(data, mimeType, target) {
+    const name = path.basename(target.filename);
+    if (name !== target.filename || name === "." || name === "..") {
+        throw new Error(`filename must be a bare file name, without path separators: ${target.filename}`);
+    }
+    if (data.length > RELAY_MAX_BYTES) {
+        throw new Error(`File too large to transfer: ${data.length} bytes, the limit is ${RELAY_MAX_BYTES}.`);
+    }
+    // Le relais tourne sur la machine de l'agent et a retenu la destination : il attend les
+    // octets, qu'il écrira lui-même. Écrire ici viserait le mauvais disque.
+    if (target.destination_relay) {
+        return [
+            {
+                type: "resource",
+                resource: {
+                    uri: `file:///${name}`,
+                    name,
+                    mimeType,
+                    blob: data.toString("base64"),
+                },
+            },
+        ];
+    }
+    // Pas de relais : le MCP tourne à côté de l'agent, son disque est le bon.
+    if (!path.isAbsolute(target.destination_path)) {
+        throw new Error(`destination_path must be an absolute directory path: ${target.destination_path}`);
+    }
+    if (fs.existsSync(target.destination_path) &&
+        !fs.statSync(target.destination_path).isDirectory()) {
+        throw new Error(`destination_path must be a directory, but a file already exists there: ${target.destination_path}`);
+    }
+    const written = path.join(target.destination_path, name);
+    if (!target.destination_overwrite && fs.existsSync(written)) {
+        throw new Error(`Destination already exists: ${written}. Pass destination_overwrite to replace it.`);
+    }
+    fs.mkdirSync(target.destination_path, { recursive: true });
+    fs.writeFileSync(written, data);
+    return [{ type: "text", text: `File written to ${written} (${data.length} bytes).` }];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/xls-reader",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "MCP server that lets AI agents read Excel files: list sheets and render any sheet as a Markdown table.",
   "type": "module",
   "main": "dist/index.js",