@makeshkumar/mcp-xl-reader 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# XL Reader MCP Server
+
+A Model Context Protocol (MCP) server that provides AI assistants with the ability to read, search, and update local `.xlsx` Excel files.
+
+## Features
+
+- **Read Spreadsheets**: Stream memory-efficient JSON rows from large Excel workbooks.
+- **Search within Sheets**: Perform case-insensitive fast searches on specific columns or headers.
+- **Update Cells**: Dynamically write string or numeric values back to the local Excel document.
+- **List Sheets**: Easily pull the names of all worksheets in a workbook.
+
+## Installation
+
+### Method 1: NPX (Recommended for quick use)
+You can directly run this server using `npx` in your MCP client configuration without globally installing it.
+
+```json
+{
+  "mcpServers": {
+    "xl-reader": {
+      "command": "npx",
+      "args": ["-y", "@makeshkumar/mcp-xl-reader"] 
+    }
+  }
+}
+```
+*(Replace `@makeshkumar/mcp-xl-reader` with your actual published npm package name once published)*
+
+### Method 2: Global Install
+```bash
+npm install -g @makeshkumar/mcp-xl-reader
+mcp-xl-reader
+```
+
+### Method 3: Local Build
+1. Clone the repository.
+2. Run `npm install` to install dependencies.
+3. Run `npm run build` to compile the TypeScript to JavaScript.
+4. Start the server using `npm start` or point your MCP client to the `dist/index.js` file.
+
+## Configuration Details
+
+### Security
+By default, the server can access any `.xlsx` file on your system using the absolute path provided by the language model. 
+
+To restrict access, set the `ALLOWED_DIRECTORIES` environment variable:
+```bash
+export ALLOWED_DIRECTORIES="/Users/yourname/Documents/Spreadsheets,/Users/yourname/Downloads"
+```
+
+If defined, the server will strictly reject paths outside these directory trees.
+
+## Tools Exposed
+
+| Tool Name | Description |
+|-----------|-------------|
+| `list_sheets` | Returns an array of worksheet names available in the workbook. |
+| `read_spreadsheet` | Returns JSON representation of rows. Streams using `worksheet.eachRow` for memory efficiency. |
+| `search_spreadsheet` | Performs a filtered search based on a `columnName` and `queryValue` and returns matching rows. |
+| `update_cell` | Updates the local file and saves changes by setting a new cell value at a specific alphanumeric address (e.g. 'B2'). |
+
+## Publishing to NPM
+
+1. Login to your npm account using `npm login`.
+2. Run `npm publish`.

package/dist/index.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import ExcelJS from "exceljs";
+import fs from "fs/promises";
+import path from "path";
+// Initialize the server
+const server = new Server({
+    name: "mcp-excel-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Helper for security and file existence check
+async function validateFilePath(filePath) {
+    const absolutePath = path.resolve(filePath);
+    try {
+        const stats = await fs.stat(absolutePath);
+        if (!stats.isFile()) {
+            throw new Error(`Path exists but is not a file: ${absolutePath}`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`File Not Found: ${absolutePath}`);
+        }
+        else if (error.code === 'EACCES') {
+            throw new Error(`Permission Denied: ${absolutePath}`);
+        }
+        throw error;
+    }
+    // Security warning log internally, could restrict paths here if ALLOWED_DIRECTORIES is set
+    const allowedDirectories = process.env.ALLOWED_DIRECTORIES ? process.env.ALLOWED_DIRECTORIES.split(',') : [];
+    if (allowedDirectories.length > 0) {
+        const isAllowed = allowedDirectories.some(dir => absolutePath.startsWith(path.resolve(dir)));
+        if (!isAllowed) {
+            throw new Error(`Security Violation: Access to ${absolutePath} is not within allowed directories.`);
+        }
+    }
+    return absolutePath;
+}
+// Helper to format cell values properly
+function formatCellValue(cell) {
+    if (cell.value === null || cell.value === undefined) {
+        return null;
+    }
+    switch (cell.type) {
+        case ExcelJS.ValueType.Null:
+        case ExcelJS.ValueType.Merge:
+            return null;
+        case ExcelJS.ValueType.Number:
+        case ExcelJS.ValueType.String:
+        case ExcelJS.ValueType.Boolean:
+            return cell.value;
+        case ExcelJS.ValueType.Date:
+            return cell.value.toISOString();
+        case ExcelJS.ValueType.Hyperlink:
+            return cell.value.text || cell.value.hyperlink;
+        case ExcelJS.ValueType.Formula:
+            const formulaVal = cell.value;
+            if (formulaVal.result instanceof Date) {
+                return formulaVal.result.toISOString();
+            }
+            if (formulaVal.result && typeof formulaVal.result.error !== "undefined") {
+                return String(formulaVal.result.error);
+            }
+            return formulaVal.result ?? null;
+        case ExcelJS.ValueType.RichText:
+            return cell.value.richText.map(rt => rt.text).join("");
+        case ExcelJS.ValueType.SharedString:
+            return String(cell.value);
+        case ExcelJS.ValueType.Error:
+            return cell.value.error?.toString() || "ERROR";
+        default:
+            return String(cell.value);
+    }
+}
+// Convert an entire row to a JSON primitive representation
+function rowToJson(row) {
+    const rowData = [];
+    row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+        // Fill gaps with null
+        while (rowData.length < colNumber - 1) {
+            rowData.push(null);
+        }
+        rowData.push(formatCellValue(cell));
+    });
+    return rowData;
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "list_sheets",
+                description: "Returns an array of worksheet names available in the workbook.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filePath: { type: "string", description: "Absolute or relative path to the .xlsx file." }
+                    },
+                    required: ["filePath"]
+                }
+            },
+            {
+                name: "read_spreadsheet",
+                description: "Returns JSON representation of rows. Streams using worksheet.eachRow for memory efficiency.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filePath: { type: "string" },
+                        sheetName: { type: "string" },
+                        limit: { type: "number", default: 100 }
+                    },
+                    required: ["filePath"]
+                }
+            },
+            {
+                name: "search_spreadsheet",
+                description: "Performs a filtered search based on a columnName and queryValue and returns matching rows.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filePath: { type: "string" },
+                        sheetName: { type: "string" },
+                        columnName: { type: "string", description: "The letter of the column (e.g., 'A', 'B') or header string if first row acts as header." },
+                        queryValue: { type: "string", description: "The value to search for." },
+                        limit: { type: "number", default: 100 }
+                    },
+                    required: ["filePath", "columnName", "queryValue"]
+                }
+            },
+            {
+                name: "update_cell",
+                description: "Updates the local file and saves changes by setting a new cell value.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filePath: { type: "string" },
+                        sheetName: { type: "string" },
+                        cellAddress: { type: "string", description: "The alphanumeric cell address, e.g., 'B2'." },
+                        newValue: { type: "string", description: "The new value to write into the cell." }
+                    },
+                    required: ["filePath", "cellAddress", "newValue"]
+                }
+            }
+        ]
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args || typeof args !== 'object' || !args.filePath) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: "Missing required filePath parameter." }]
+        };
+    }
+    const { filePath } = args;
+    let absolutePath;
+    try {
+        absolutePath = await validateFilePath(filePath);
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: error.message }]
+        };
+    }
+    try {
+        const workbook = new ExcelJS.Workbook();
+        switch (name) {
+            case "list_sheets": {
+                await workbook.xlsx.readFile(absolutePath);
+                const sheets = workbook.worksheets.map(ws => ws.name);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(sheets, null, 2) }]
+                };
+            }
+            case "read_spreadsheet": {
+                const { sheetName, limit = 100 } = args;
+                await workbook.xlsx.readFile(absolutePath);
+                let ws;
+                if (sheetName) {
+                    const fetchedWs = workbook.getWorksheet(sheetName);
+                    if (!fetchedWs)
+                        throw new Error(`Worksheet ${sheetName} not found.`);
+                    ws = fetchedWs;
+                }
+                else {
+                    ws = workbook.worksheets[0];
+                    if (!ws)
+                        throw new Error("No worksheets found in the workbook.");
+                }
+                const rows = [];
+                let count = 0;
+                ws.eachRow((row, rowNumber) => {
+                    if (count < limit) {
+                        rows.push({ rowNumber, data: rowToJson(row) });
+                        count++;
+                    }
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(rows, null, 2) }]
+                };
+            }
+            case "search_spreadsheet": {
+                const { sheetName, columnName, queryValue, limit = 100 } = args;
+                await workbook.xlsx.readFile(absolutePath);
+                let ws;
+                if (sheetName) {
+                    const fetchedWs = workbook.getWorksheet(sheetName);
+                    if (!fetchedWs)
+                        throw new Error(`Worksheet ${sheetName} not found.`);
+                    ws = fetchedWs;
+                }
+                else {
+                    ws = workbook.worksheets[0];
+                    if (!ws)
+                        throw new Error("No worksheets found in the workbook.");
+                }
+                const matches = [];
+                let count = 0;
+                let isAlphaCol = /^[A-Z]+$/i.test(columnName);
+                ws.eachRow((row, rowNumber) => {
+                    if (count >= limit)
+                        return;
+                    let matchesQuery = false;
+                    if (isAlphaCol) {
+                        const cell = row.getCell(columnName);
+                        const val = formatCellValue(cell);
+                        if (String(val).toLowerCase().includes(String(queryValue).toLowerCase())) {
+                            matchesQuery = true;
+                        }
+                    }
+                    else {
+                        // Assume it's a header string mismatch - check all cells
+                        // For simplicity and to be robust, if columnName is not a letter, 
+                        // maybe we map the first row. 
+                        // In large files first row headers might be easier to resolve once.
+                        // But let's just search the whole row if it's not alphabetic or we don't know the index.
+                        // If they provided a header name, we should find its index from row 1.
+                        let colIndex = -1;
+                        const headerRow = ws.getRow(1);
+                        headerRow.eachCell({ includeEmpty: true }, (c, idx) => {
+                            if (String(formatCellValue(c)).toLowerCase() === String(columnName).toLowerCase()) {
+                                colIndex = idx;
+                            }
+                        });
+                        if (colIndex !== -1) {
+                            const cell = row.getCell(colIndex);
+                            const val = formatCellValue(cell);
+                            if (String(val).toLowerCase().includes(String(queryValue).toLowerCase())) {
+                                matchesQuery = true;
+                            }
+                        }
+                        else {
+                            // Fallback: search anywhere
+                            row.eachCell({ includeEmpty: true }, (c) => {
+                                if (String(formatCellValue(c)).toLowerCase().includes(String(queryValue).toLowerCase())) {
+                                    matchesQuery = true;
+                                }
+                            });
+                        }
+                    }
+                    if (matchesQuery) {
+                        matches.push({ rowNumber, data: rowToJson(row) });
+                        count++;
+                    }
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(matches, null, 2) }]
+                };
+            }
+            case "update_cell": {
+                const { sheetName, cellAddress, newValue } = args;
+                await workbook.xlsx.readFile(absolutePath);
+                let ws;
+                if (sheetName) {
+                    const fetchedWs = workbook.getWorksheet(sheetName);
+                    if (!fetchedWs)
+                        throw new Error(`Worksheet ${sheetName} not found.`);
+                    ws = fetchedWs;
+                }
+                else {
+                    ws = workbook.worksheets[0];
+                    if (!ws)
+                        throw new Error("No worksheets found in the workbook.");
+                }
+                const cell = ws.getCell(cellAddress);
+                // Ensure new value is applied. If it looks like a number, cast it?
+                // Let's just set it as string or number appropriately
+                const numVal = Number(newValue);
+                if (!isNaN(numVal) && String(newValue).trim() !== "") {
+                    cell.value = numVal;
+                }
+                else {
+                    cell.value = newValue;
+                }
+                await workbook.xlsx.writeFile(absolutePath);
+                return {
+                    content: [{ type: "text", text: `Successfully updated cell ${cellAddress} to ${newValue}` }]
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Error processing Excel file: ${error.message}` }]
+        };
+    }
+});
+async function run() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Excel Server running on stdio");
+}
+run().catch((error) => {
+    console.error("Failed to start server", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@makeshkumar/mcp-xl-reader",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "bin": {
+    "mcp-xl-reader": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model context protocol",
+    "excel",
+    "xlsx",
+    "ai",
+    "claude",
+    "tools"
+  ],
+  "author": "Makesh Kumar",
+  "license": "MIT",
+  "description": "An MCP server to read, search, and update local Excel (.xlsx) files.",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "exceljs": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}