@imenam/xls-reader 2.0.0 → 2.2.0

package/README.md

@@ -4,6 +4,19 @@ An MCP (Model Context Protocol) server that lets AI agents read Excel files. It
 
 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`
@@ -12,7 +25,9 @@ Lists all sheet names (tabs) in a workbook.
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `file_path` | `string` | ✅ | Absolute or relative path to the Excel file |
+| `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.
 
@@ -22,8 +37,12 @@ Reads a sheet and returns its content as a Markdown table.
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `file_path` | `string` | ✅ | Absolute or relative path to the Excel file |
-| `sheet_name` | `string` | ✅ | Name of the sheet to read |
+| `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 |
@@ -36,6 +55,42 @@ Reads a sheet and returns its content as a Markdown table.
 - **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).

package/dist/excel.js

@@ -1,32 +1,73 @@
 import XLSX from "xlsx";
 import fs from "fs";
-export function listSheets(filePath) {
-    if (!fs.existsSync(filePath)) {
-        throw new Error(`File not found: ${filePath}`);
+import path from "path";
+const BASE64_DATA_URL = /^data:[^;,]*(;[^;,]+)*;base64,/i;
+function decodeBase64(content) {
+    const cleaned = content.replace(BASE64_DATA_URL, "").replace(/\s+/g, "");
+    if (cleaned === "") {
+        throw new Error("file_content is empty.");
     }
-    const workbook = XLSX.readFile(filePath);
-    return workbook.SheetNames;
+    const buffer = Buffer.from(cleaned, "base64");
+    if (buffer.length === 0) {
+        throw new Error("file_content is not valid base64 data.");
+    }
+    return buffer;
+}
+function loadWorkbook(source, options = {}) {
+    if (source.fileContent != null && source.fileContent !== "") {
+        return XLSX.read(decodeBase64(source.fileContent), { ...options, type: "buffer" });
+    }
+    if (!source.filePath) {
+        throw new Error("Either file_path or file_content must be provided.");
+    }
+    if (!fs.existsSync(source.filePath)) {
+        throw new Error(`File not found: ${source.filePath}. If the file lives on another machine, send it with file_content (base64) instead.`);
+    }
+    return XLSX.readFile(source.filePath, options);
+}
+function sourceLabel(source) {
+    if (source.fileName)
+        return path.basename(source.fileName);
+    if (source.filePath)
+        return path.basename(source.filePath);
+    return "workbook";
 }
+export function listSheets(source) {
+    return loadWorkbook(source).SheetNames;
+}
+// ─── Cell value helpers ─────────────────────────────────────────────────────
+function isEmptyValue(value) {
+    return value === null || value === undefined || value === "";
+}
+/** Stringify a cell for Markdown (in-cell line breaks escaped to keep the table intact). */
 function cellToString(value) {
-    if (value === null || value === undefined || value === "")
+    if (isEmptyValue(value))
         return "";
     if (value instanceof Date)
         return value.toLocaleDateString();
     if (typeof value === "boolean")
         return value ? "TRUE" : "FALSE";
-    // Replace in-cell line breaks with a literal \n so they don't break the Markdown table row.
     return String(value).trim().replace(/\r\n|\r|\n/g, "\\n");
 }
-function toStringRow(raw, numCols) {
+/** Convert a cell to a native JSON value (types preserved, dates as ISO, real line breaks kept). */
+function cellToJson(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "string")
+        return value.trim();
+    return value;
+}
+function toStringCells(raw, numCols) {
     return Array.from({ length: numCols }, (_, i) => cellToString(raw[i]));
 }
-function isEmptyRow(cells) {
-    return cells.every((c) => c === "");
+// ─── Sections (an empty row delimits a new table) ───────────────────────────
+function isEmptyRawRow(row) {
+    return row.every(isEmptyValue);
 }
 function groupIntoSections(rows) {
     const sections = [[]];
     for (const row of rows) {
-        if (isEmptyRow(row)) {
+        if (isEmptyRawRow(row)) {
             if (sections[sections.length - 1].length > 0) {
                 sections.push([]);
             }
@@ -37,76 +78,130 @@ function groupIntoSections(rows) {
     }
     return sections.filter((s) => s.length > 0);
 }
+/** Read a worksheet into header + grouped sections, applying the size limit unless `unlimited`. */
+function extractSheetData(ws, options) {
+    const rawRows = XLSX.utils.sheet_to_json(ws, { header: 1, defval: "" });
+    if (rawRows.length === 0)
+        return null;
+    const { cellBudget = 2000, maxCols, maxRows, headerRow = true, unlimited = false } = options;
+    const totalCols = rawRows.reduce((max, row) => Math.max(max, row.length), 0);
+    let effectiveCols = totalCols;
+    let effectiveRows = rawRows.length;
+    let note = null;
+    if (!unlimited) {
+        effectiveCols = Math.min(totalCols, maxCols ?? totalCols);
+        effectiveRows = Math.min(rawRows.length, maxRows ?? Math.floor(cellBudget / Math.max(effectiveCols, 1)));
+        const truncatedCols = effectiveCols < totalCols;
+        const truncatedRows = effectiveRows < rawRows.length;
+        if (truncatedCols || truncatedRows) {
+            const w = [];
+            if (truncatedCols)
+                w.push(`${effectiveCols} columns out of ${totalCols}`);
+            if (truncatedRows)
+                w.push(`${effectiveRows} rows out of ${rawRows.length}`);
+            note = `Display limited to ${w.join(", ")}. Use max_cols / max_rows / cell_budget to adjust.`;
+        }
+    }
+    const matrix = rawRows
+        .slice(0, effectiveRows)
+        .map((row) => row.slice(0, effectiveCols));
+    let headerRaw = null;
+    let dataRows = matrix;
+    if (headerRow && matrix.length > 0) {
+        headerRaw = matrix[0];
+        dataRows = matrix.slice(1);
+    }
+    return { headerRaw, sections: groupIntoSections(dataRows), numCols: effectiveCols, note };
+}
+// ─── JSON groups builder (shared by single-sheet and whole-workbook output) ──
+function buildHeaderKeys(headerRaw, numCols) {
+    return Array.from({ length: numCols }, (_, i) => {
+        const key = cellToString(headerRaw[i]);
+        return key === "" ? `column_${i + 1}` : key;
+    });
+}
+function rowToObject(row, keys) {
+    const obj = {};
+    keys.forEach((key, i) => {
+        if (!isEmptyValue(row[i]))
+            obj[key] = cellToJson(row[i]);
+    });
+    return obj;
+}
+function rowToArray(row, numCols) {
+    return Array.from({ length: numCols }, (_, i) => isEmptyValue(row[i]) ? null : cellToJson(row[i]));
+}
+/** Turn a sheet's sections into JSON groups (objects keyed by header, or arrays of values). */
+function buildGroups(data) {
+    if (data.headerRaw) {
+        const keys = buildHeaderKeys(data.headerRaw, data.numCols);
+        return data.sections.map((section) => section.map((row) => rowToObject(row, keys)));
+    }
+    return data.sections.map((section) => section.map((row) => rowToArray(row, data.numCols)));
+}
+// ─── Markdown renderer ──────────────────────────────────────────────────────
 function formatRow(cells, numCols) {
     const padded = Array.from({ length: numCols }, (_, i) => cells[i] ?? "");
     return "| " + padded.join(" | ") + " |";
 }
-function sectionToMarkdown(section, header, numCols) {
-    const lines = [];
-    if (header) {
-        lines.push(formatRow(header, numCols));
-        const sep = Array.from({ length: numCols }, (_, i) => "-".repeat(Math.max((header[i] ?? "").length, 3)));
-        lines.push("| " + sep.join(" | ") + " |");
-    }
-    for (const row of section) {
-        lines.push(formatRow(row, numCols));
-    }
-    return lines.join("\n");
+function markdownHeader(header, numCols) {
+    const sep = Array.from({ length: numCols }, (_, i) => "-".repeat(Math.max((header[i] ?? "").length, 3)));
+    return [formatRow(header, numCols), "| " + sep.join(" | ") + " |"];
 }
-export function readSheet(filePath, sheetName, options = {}) {
-    if (!fs.existsSync(filePath)) {
-        throw new Error(`File not found: ${filePath}`);
+function renderMarkdown(data) {
+    const header = data.headerRaw ? toStringCells(data.headerRaw, data.numCols) : null;
+    if (data.sections.length === 0) {
+        if (!header)
+            return "_Empty sheet._";
+        return [...markdownHeader(header, data.numCols), "_No data rows._"].join("\n");
     }
-    const workbook = XLSX.readFile(filePath, { cellDates: true });
+    const parts = data.sections.map((section) => {
+        const lines = header ? markdownHeader(header, data.numCols) : [];
+        for (const row of section)
+            lines.push(formatRow(toStringCells(row, data.numCols), data.numCols));
+        return lines.join("\n");
+    });
+    let result = parts.join("\n\n");
+    if (data.note)
+        result += `\n\n> ⚠ ${data.note}`;
+    return result;
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+export function readSheet(source, sheetName, options = {}) {
+    const workbook = loadWorkbook(source, { cellDates: true });
     if (!workbook.SheetNames.includes(sheetName)) {
         throw new Error(`Sheet '${sheetName}' not found. Available: ${workbook.SheetNames.join(", ")}`);
     }
-    const ws = workbook.Sheets[sheetName];
-    const rawRows = XLSX.utils.sheet_to_json(ws, {
-        header: 1,
-        defval: "",
-    });
-    if (rawRows.length === 0) {
-        return "_Empty sheet._";
-    }
-    const { cellBudget = 2000, maxCols, maxRows, headerRow = true } = options;
-    const totalCols = rawRows.reduce((max, row) => Math.max(max, row.length), 0);
-    const effectiveCols = Math.min(totalCols, maxCols ?? totalCols);
-    const effectiveRows = Math.min(rawRows.length, maxRows ?? Math.floor(cellBudget / Math.max(effectiveCols, 1)));
-    const truncatedCols = effectiveCols < totalCols;
-    const truncatedRows = effectiveRows < rawRows.length;
-    const stringRows = rawRows
-        .slice(0, effectiveRows)
-        .map((row) => toStringRow(row, effectiveCols));
-    let header = null;
-    let dataRows = stringRows;
-    if (headerRow && stringRows.length > 0) {
-        header = stringRows[0];
-        dataRows = stringRows.slice(1);
+    const { format = "markdown", ...rest } = options;
+    const data = extractSheetData(workbook.Sheets[sheetName], rest);
+    if (format === "json") {
+        const out = { sheet: sheetName, truncated: data?.note != null };
+        if (data?.note)
+            out.note = data.note;
+        out.groups = data ? buildGroups(data) : [];
+        return JSON.stringify(out, null, 2);
     }
-    const sections = groupIntoSections(dataRows);
-    if (sections.length === 0) {
-        const lines = [];
-        if (header) {
-            lines.push(formatRow(header, effectiveCols));
-            const sep = Array.from({ length: effectiveCols }, (_, i) => "-".repeat(Math.max((header[i] ?? "").length, 3)));
-            lines.push("| " + sep.join(" | ") + " |");
-            lines.push("_No data rows._");
-        }
-        else {
-            return "_Empty sheet._";
+    return data ? renderMarkdown(data) : "_Empty sheet._";
+}
+/**
+ * Read a workbook into a single JSON object, with no size limit.
+ * Exports every sheet, or only `sheetName` when provided.
+ */
+export function readWorkbook(source, options = {}) {
+    const workbook = loadWorkbook(source, { cellDates: true });
+    let names = workbook.SheetNames;
+    if (options.sheetName) {
+        if (!names.includes(options.sheetName)) {
+            throw new Error(`Sheet '${options.sheetName}' not found. Available: ${names.join(", ")}`);
         }
-        return lines.join("\n");
-    }
-    const parts = sections.map((section) => sectionToMarkdown(section, header, effectiveCols));
-    let result = parts.join("\n\n");
-    if (truncatedCols || truncatedRows) {
-        const warnings = [];
-        if (truncatedCols)
-            warnings.push(`${effectiveCols} columns out of ${totalCols}`);
-        if (truncatedRows)
-            warnings.push(`${effectiveRows} rows out of ${rawRows.length}`);
-        result += `\n\n> ⚠ Display limited to ${warnings.join(", ")}. Use \`max_cols\` / \`max_rows\` / \`cell_budget\` to adjust.`;
+        names = [options.sheetName];
     }
-    return result;
+    const sheets = names.map((name) => {
+        const data = extractSheetData(workbook.Sheets[name], {
+            headerRow: options.headerRow,
+            unlimited: true,
+        });
+        return { sheet: name, groups: data ? buildGroups(data) : [] };
+    });
+    return JSON.stringify({ file: sourceLabel(source), sheets }, null, 2);
 }

package/dist/index.js

@@ -2,11 +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 } from "./excel.js";
+import { listSheets, readSheet, readWorkbook } from "./excel.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
 dotenv.config({ path: path.join(rootDir, ".env"), override: true });
@@ -15,12 +16,34 @@ const server = new McpServer({
     name: "xls-reader",
     version: "1.0.0",
 });
+// ─── Workbook source (path on this server, or inline content) ─────────────────
+const sourceShape = {
+    file_path: z
+        .string()
+        .optional()
+        .describe("Path to the Excel file on the machine running this server. Use it only when the file is local to the server; otherwise send file_content"),
+    file_content: z
+        .string()
+        .optional()
+        .describe("Base64-encoded content of the Excel file (a 'data:' URL prefix is accepted). Filled in by the client-side relay, which reads the file named by file_path on the caller's machine — a caller that provides file_path has nothing to put here. Takes precedence over file_path"),
+    file_name: z
+        .string()
+        .optional()
+        .describe("Original file name, used only to label the output. Also filled in by the relay alongside file_content"),
+};
+function toSource(args) {
+    if (!args.file_path && !args.file_content) {
+        throw new Error("Provide either file_path (file local to the server) or file_content (base64 content of the file).");
+    }
+    return { filePath: args.file_path, fileContent: args.file_content, fileName: args.file_name };
+}
 // ─── list_sheets ──────────────────────────────────────────────────────────────
-server.tool("list_sheets", "List all sheet names (tabs) in an Excel file (.xlsx, .xls, .ods, .csv).", {
-    file_path: z.string().describe("Absolute or relative path to the Excel file"),
-}, async ({ file_path }) => {
+server.tool("list_sheets", [
+    "List all sheet names (tabs) in an Excel file (.xlsx, .xls, .ods, .csv).",
+    "Pass file_path when the file sits on the machine running this server, or file_content (base64) when it does not.",
+].join(" "), sourceShape, async (args) => {
     try {
-        const sheets = listSheets(file_path);
+        const sheets = listSheets(toSource(args));
         return {
             content: [{ type: "text", text: sheets.join("\n") }],
         };
@@ -35,12 +58,27 @@ server.tool("list_sheets", "List all sheet names (tabs) in an Excel file (.xlsx,
 });
 // ─── get_sheet ────────────────────────────────────────────────────────────────
 server.tool("get_sheet", [
-    "Read an Excel sheet and return its content as a Markdown table.",
+    "Read an Excel sheet and return its content.",
+    "Pass file_path when the file sits on the machine running this server, or file_content (base64) when it does not.",
     "Empty rows are treated as section separators — they close the current table and start a new one.",
-    "Data is limited by a cell budget (cols × rows, default 2000). Use max_cols / max_rows / cell_budget to override.",
+    "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.",
 ].join(" "), {
-    file_path: z.string().describe("Absolute or relative path to the Excel file"),
-    sheet_name: z.string().describe("Name of the sheet to read"),
+    ...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"),
+    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()
+        .optional()
+        .describe("Destination path on the server's disk for the JSON export (required when format is 'json-file')"),
     cell_budget: z
         .number()
         .optional()
@@ -51,16 +89,39 @@ server.tool("get_sheet", [
         .boolean()
         .optional()
         .describe("Treat the first row as a column header (default: true)"),
-}, async ({ file_path, sheet_name, cell_budget, max_cols, max_rows, header_row }) => {
+}, async ({ sheet_name, format, output_path, cell_budget, max_cols, max_rows, header_row, ...rest }) => {
     try {
-        const markdown = readSheet(file_path, sheet_name, {
+        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,
             maxCols: max_cols,
             maxRows: max_rows,
             headerRow: header_row,
         });
         return {
-            content: [{ type: "text", text: markdown }],
+            content: [{ type: "text", text: output }],
         };
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/xls-reader",
-  "version": "2.0.0",
+  "version": "2.2.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",