@imenam/xls-reader 2.0.0

package/README.md

@@ -0,0 +1,90 @@
+# @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).
+
+## Tools
+
+### `list_sheets`
+
+Lists all sheet names (tabs) in a workbook.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `file_path` | `string` | ✅ | Absolute or relative path to the Excel file |
+
+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` | ✅ | Absolute or relative path to the Excel file |
+| `sheet_name` | `string` | ✅ | Name of the sheet to read |
+| `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.
+
+#### 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

package/dist/excel.js

@@ -0,0 +1,112 @@
+import XLSX from "xlsx";
+import fs from "fs";
+export function listSheets(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    const workbook = XLSX.readFile(filePath);
+    return workbook.SheetNames;
+}
+function cellToString(value) {
+    if (value === null || value === undefined || 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) {
+    return Array.from({ length: numCols }, (_, i) => cellToString(raw[i]));
+}
+function isEmptyRow(cells) {
+    return cells.every((c) => c === "");
+}
+function groupIntoSections(rows) {
+    const sections = [[]];
+    for (const row of rows) {
+        if (isEmptyRow(row)) {
+            if (sections[sections.length - 1].length > 0) {
+                sections.push([]);
+            }
+        }
+        else {
+            sections[sections.length - 1].push(row);
+        }
+    }
+    return sections.filter((s) => s.length > 0);
+}
+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");
+}
+export function readSheet(filePath, sheetName, options = {}) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    const workbook = XLSX.readFile(filePath, { 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 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 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.`;
+    }
+    return result;
+}

package/dist/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import dotenv from "dotenv";
+import path from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+import { setupLogging } from "./logger.js";
+import { listSheets, readSheet } 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 });
+setupLogging("MASTER");
+const server = new McpServer({
+    name: "xls-reader",
+    version: "1.0.0",
+});
+// ─── 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 }) => {
+    try {
+        const sheets = listSheets(file_path);
+        return {
+            content: [{ type: "text", text: sheets.join("\n") }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ─── get_sheet ────────────────────────────────────────────────────────────────
+server.tool("get_sheet", [
+    "Read an Excel sheet and return its content as a Markdown table.",
+    "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.",
+].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"),
+    cell_budget: z
+        .number()
+        .optional()
+        .describe("Maximum number of cells to return (cols × rows). Default: 2000"),
+    max_cols: z.number().optional().describe("Override maximum number of columns"),
+    max_rows: z.number().optional().describe("Override maximum number of rows"),
+    header_row: z
+        .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 }) => {
+    try {
+        const markdown = readSheet(file_path, sheet_name, {
+            cellBudget: cell_budget,
+            maxCols: max_cols,
+            maxRows: max_rows,
+            headerRow: header_row,
+        });
+        return {
+            content: [{ type: "text", text: markdown }],
+        };
+    }
+    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();
+    await server.connect(transport);
+    console.error("[xls-reader] MCP server started");
+}
+main().catch((err) => {
+    console.error("[xls-reader] Fatal error:", err);
+    process.exit(1);
+});

package/dist/logger.js

@@ -0,0 +1,47 @@
+import fs from "fs";
+import path from "path";
+let currentPrefix = "";
+export function logToFile(message, prefix = "") {
+    const defaultLogDir = process.platform === "win32"
+        ? "C:\\var\\log\\xls-reader"
+        : "/var/log/xls-reader";
+    const logDir = process.env.MCP_LOG_DIR ?? defaultLogDir;
+    const logFile = path.join(logDir, "server.log");
+    const now = new Date().toLocaleString("fr-FR", {
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    const effectivePrefix = prefix || currentPrefix;
+    const label = effectivePrefix ? ` [${effectivePrefix}]` : "";
+    const logEntry = `[${now}] [PID ${process.pid}]${label} ${message}\n`;
+    try {
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        fs.appendFileSync(logFile, logEntry);
+    }
+    catch {
+        process.stderr.write("Critical: Failed to write to log file\n");
+    }
+}
+export function setupLogging(prefix) {
+    currentPrefix = prefix;
+    if (prefix === "MASTER") {
+        console.log = (...args) => {
+            console.error(...args);
+        };
+    }
+    const originalError = console.error;
+    console.error = (...args) => {
+        const message = args
+            .map((arg) => (typeof arg === "object" ? JSON.stringify(arg, null, 2) : arg))
+            .join(" ");
+        logToFile(message, prefix);
+        originalError.apply(console, args);
+    };
+    logToFile("--- Logging system initialized ---", prefix);
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@imenam/xls-reader",
+  "version": "2.0.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",
+  "bin": {
+    "xls-reader": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "release:patch": "npm version patch && npm publish --access public && git push origin master --follow-tags",
+    "release:minor": "npm version minor && npm publish --access public && git push origin master --follow-tags",
+    "release:major": "npm version major && npm publish --access public && git push origin master --follow-tags"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "excel",
+    "xlsx",
+    "xls",
+    "ods",
+    "csv",
+    "spreadsheet"
+  ],
+  "author": "imenam",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Matthieu-Pesnot-Pin/xls-reader.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "dotenv": "^17.3.1",
+    "xlsx": "^0.18.5",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  }
+}