@imenam/xls-reader 2.0.0 → 2.1.0

package/README.md

@@ -23,7 +23,9 @@ 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 |
+| `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 +38,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` 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,5 +1,6 @@
 import XLSX from "xlsx";
 import fs from "fs";
+import path from "path";
 export function listSheets(filePath) {
     if (!fs.existsSync(filePath)) {
         throw new Error(`File not found: ${filePath}`);
@@ -7,26 +8,39 @@ export function listSheets(filePath) {
     const workbook = XLSX.readFile(filePath);
     return workbook.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,22 +51,95 @@ 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));
+function markdownHeader(header, numCols) {
+    const sep = Array.from({ length: numCols }, (_, i) => "-".repeat(Math.max((header[i] ?? "").length, 3)));
+    return [formatRow(header, numCols), "| " + sep.join(" | ") + " |"];
+}
+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");
     }
-    return lines.join("\n");
+    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(filePath, sheetName, options = {}) {
     if (!fs.existsSync(filePath)) {
         throw new Error(`File not found: ${filePath}`);
@@ -61,52 +148,39 @@ export function readSheet(filePath, sheetName, options = {}) {
     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 { 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 { 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);
+    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(filePath, options = {}) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
     }
-    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._";
+    const workbook = XLSX.readFile(filePath, { 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");
+        names = [options.sheetName];
     }
-    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.`;
-    }
-    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: path.basename(filePath), 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 });
@@ -35,12 +36,26 @@ 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.",
     "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"),
+    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 file path for the JSON export (required when format is 'json-file')"),
     cell_budget: z
         .number()
         .optional()
@@ -51,16 +66,38 @@ 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 ({ file_path, sheet_name, format, output_path, cell_budget, max_cols, max_rows, header_row }) => {
     try {
-        const markdown = readSheet(file_path, sheet_name, {
+        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(file_path, { 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(file_path, 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.1.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",