@imenam/xls-reader 2.1.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,7 +37,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 |
+| `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`) |
@@ -62,7 +79,7 @@ With `format: "json"` you get a structured object — better when the agent need
 - 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:
+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
 {

package/dist/excel.js

@@ -1,12 +1,39 @@
 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}`);
+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) {
@@ -140,11 +167,8 @@ function renderMarkdown(data) {
     return result;
 }
 // ─── Public API ─────────────────────────────────────────────────────────────
-export function readSheet(filePath, sheetName, options = {}) {
-    if (!fs.existsSync(filePath)) {
-        throw new Error(`File not found: ${filePath}`);
-    }
-    const workbook = XLSX.readFile(filePath, { cellDates: true });
+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(", ")}`);
     }
@@ -163,11 +187,8 @@ export function readSheet(filePath, sheetName, options = {}) {
  * 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 workbook = XLSX.readFile(filePath, { cellDates: true });
+export function readWorkbook(source, options = {}) {
+    const workbook = loadWorkbook(source, { cellDates: true });
     let names = workbook.SheetNames;
     if (options.sheetName) {
         if (!names.includes(options.sheetName)) {
@@ -182,5 +203,5 @@ export function readWorkbook(filePath, options = {}) {
         });
         return { sheet: name, groups: data ? buildGroups(data) : [] };
     });
-    return JSON.stringify({ file: path.basename(filePath), sheets }, null, 2);
+    return JSON.stringify({ file: sourceLabel(source), sheets }, null, 2);
 }

package/dist/index.js

@@ -16,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") }],
         };
@@ -37,13 +59,14 @@ 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.",
+    "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.",
     "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"),
+    ...sourceShape,
     sheet_name: z
         .string()
         .optional()
@@ -55,7 +78,7 @@ server.tool("get_sheet", [
     output_path: z
         .string()
         .optional()
-        .describe("Destination file path for the JSON export (required when format is 'json-file')"),
+        .describe("Destination path on the server's disk for the JSON export (required when format is 'json-file')"),
     cell_budget: z
         .number()
         .optional()
@@ -66,8 +89,9 @@ server.tool("get_sheet", [
         .boolean()
         .optional()
         .describe("Treat the first row as a column header (default: true)"),
-}, async ({ file_path, sheet_name, format, output_path, 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 source = toSource(rest);
         if (format === "json-file") {
             if (!output_path) {
                 return {
@@ -75,7 +99,7 @@ server.tool("get_sheet", [
                     isError: true,
                 };
             }
-            const json = readWorkbook(file_path, { headerRow: header_row, sheetName: sheet_name });
+            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");
@@ -89,7 +113,7 @@ server.tool("get_sheet", [
                 isError: true,
             };
         }
-        const output = readSheet(file_path, sheet_name, {
+        const output = readSheet(source, sheet_name, {
             format,
             cellBudget: cell_budget,
             maxCols: max_cols,

package/package.json

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