@makeshkumar/mcp-xl-reader 1.0.2 → 1.0.5

package/README.md

@@ -1,65 +1,23 @@
-# 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. |
+| `find_excel_files` | Recursively finds all .xlsx files in directories. |
 | `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'). |
+| `add_worksheet_with_data` | Creates a new worksheet in an existing workbook and populates it with rows. |
+| `create_new_workbook` | Creates a brand new Excel workbook with initial sheet and data. **NEW: Supports optional filePath with reference file directory.** |
+
+### create_new_workbook - New Feature
 
-## Publishing to NPM
+You can now create a new workbook without specifying the full path. Instead, provide a reference file path and the new file will be created in the same directory:
 
-1. Login to your npm account using `npm login`.
-2. Run `npm publish`.
+**Option 1: Direct Path (original way)**
+```json
+{
+  "filePath": "/Users/user/new_file.xlsx",
+  "columns": [{"header": "Name", "key": "name"}],
+  "rows": [{"name": "John"}]
+}

package/dist/index.js

@@ -42,6 +42,18 @@ async function validateFilePath(filePath) {
     }
     return absolutePath;
 }
+// Helper for security check when creating new files (bypasses existence check)
+async function validateNewFilePath(filePath) {
+    const absolutePath = path.resolve(filePath);
+    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 for security and directory existence check
 async function validateDirectoryPath(directoryPath) {
     const absolutePath = path.resolve(directoryPath);
@@ -182,6 +194,64 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                     required: ["filePath", "cellAddress", "newValue"]
                 }
+            },
+            {
+                name: "add_worksheet_with_data",
+                description: "Creates a new worksheet in an existing workbook and populates it with an array of JSON rows. Great for generating summary reports.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filePath: { type: "string" },
+                        sheetName: { type: "string", description: "Name of the new sheet to create." },
+                        columns: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    header: { type: "string" },
+                                    key: { type: "string" }
+                                }
+                            },
+                            description: "Array of column definitions, e.g., [{header: 'Name', key: 'name'}]"
+                        },
+                        rows: {
+                            type: "array",
+                            items: { type: "object" },
+                            description: "Array of JSON objects representing the rows to insert."
+                        }
+                    },
+                    required: ["filePath", "sheetName", "columns", "rows"]
+                }
+            },
+            {
+                name: "create_new_workbook",
+                description: "Creates a brand new Excel workbook file. If filePath is omitted, it creates the file in the same directory as the reference file.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filePath: { type: "string", description: "Absolute path where the new .xlsx file should be created (optional if referenceFilePath provided)." },
+                        referenceFilePath: { type: "string", description: "Path to an existing file to use as directory reference (optional)." },
+                        fileName: { type: "string", description: "Name of the new file (e.g., 'report.xlsx'). Required if referenceFilePath is used." },
+                        sheetName: { type: "string", description: "Name of the first sheet.", default: "Sheet1" },
+                        columns: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    header: { type: "string" },
+                                    key: { type: "string" }
+                                }
+                            },
+                            description: "Array of column definitions, e.g., [{header: 'Name', key: 'name'}]"
+                        },
+                        rows: {
+                            type: "array",
+                            items: { type: "object" },
+                            description: "Array of JSON objects representing the rows to insert."
+                        }
+                    },
+                    required: ["columns", "rows"]
+                }
             }
         ]
     };
@@ -194,7 +264,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             content: [{ type: "text", text: "Invalid arguments provided." }]
         };
     }
-    if (name !== "find_excel_files") {
+    if (name !== "find_excel_files" && name !== "create_new_workbook") {
         if (!args.filePath) {
             return {
                 isError: true,
@@ -202,9 +272,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    else if (name === "create_new_workbook") {
+        // Path validation handled within the case statement
+    }
     let absolutePath = "";
     try {
-        if (name !== "find_excel_files") {
+        if (name === "create_new_workbook") {
+            // Path validation handled within the case statement
+            if (args.filePath) {
+                absolutePath = await validateNewFilePath(args.filePath);
+            }
+        }
+        else if (name !== "find_excel_files") {
             absolutePath = await validateFilePath(args.filePath);
         }
     }
@@ -398,6 +477,96 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [{ type: "text", text: `Successfully updated cell ${cellAddress} to ${newValue}` }]
                 };
             }
+            case "add_worksheet_with_data": {
+                const { sheetName, columns, rows } = args;
+                await workbook.xlsx.readFile(absolutePath);
+                // Check if sheet exists to avoid crashing
+                if (workbook.getWorksheet(sheetName)) {
+                    throw new Error(`A worksheet named '${sheetName}' already exists in this file.`);
+                }
+                const ws = workbook.addWorksheet(sheetName);
+                // Set columns
+                if (Array.isArray(columns)) {
+                    ws.columns = columns.map(col => ({
+                        header: col.header,
+                        key: col.key,
+                        width: 20 // Default reasonable width
+                    }));
+                }
+                // Add data rows
+                if (Array.isArray(rows)) {
+                    rows.forEach(rowData => {
+                        ws.addRow(rowData);
+                    });
+                }
+                // Make the header bold to look professional
+                const headerRow = ws.getRow(1);
+                headerRow.font = { bold: true };
+                headerRow.commit();
+                await workbook.xlsx.writeFile(absolutePath);
+                return {
+                    content: [{ type: "text", text: `Successfully generated new reporting sheet '${sheetName}' with ${rows.length} rows of data and saved it to the file.` }]
+                };
+            }
+            case "create_new_workbook": {
+                let finalFilePath = absolutePath;
+                const { sheetName = "Sheet1", columns, rows, referenceFilePath, fileName } = args;
+                // Handle path resolution
+                if (!args.filePath) {
+                    if (!referenceFilePath || !fileName) {
+                        return {
+                            isError: true,
+                            content: [{ type: "text", text: "Either provide 'filePath' OR both 'referenceFilePath' and 'fileName'." }]
+                        };
+                    }
+                    try {
+                        const refPath = await validateFilePath(args.referenceFilePath);
+                        const refDir = path.dirname(refPath);
+                        finalFilePath = path.join(refDir, fileName);
+                    }
+                    catch (error) {
+                        return {
+                            isError: true,
+                            content: [{ type: "text", text: error.message }]
+                        };
+                    }
+                }
+                try {
+                    const stats = await fs.stat(finalFilePath);
+                    if (stats) {
+                        throw new Error(`File already exists at '${finalFilePath}'. Use add_worksheet_with_data or update_cell to modify it, or use a different file path.`);
+                    }
+                }
+                catch (e) {
+                    if (e.code !== 'ENOENT') {
+                        throw e;
+                    }
+                }
+                const newWorkbook = new ExcelJS.Workbook();
+                const ws = newWorkbook.addWorksheet(sheetName);
+                // Set columns
+                if (Array.isArray(columns)) {
+                    ws.columns = columns.map(col => ({
+                        header: col.header,
+                        key: col.key,
+                        width: 20
+                    }));
+                }
+                // Add data rows
+                if (Array.isArray(rows)) {
+                    rows.forEach(rowData => {
+                        ws.addRow(rowData);
+                    });
+                }
+                // Make the header bold
+                const headerRow = ws.getRow(1);
+                headerRow.font = { bold: true };
+                headerRow.commit();
+                await newWorkbook.xlsx.writeFile(finalFilePath);
+                return {
+                    content: [{ type: "text", text: `Successfully created new workbook '${finalFilePath}' with sheet '${sheetName}' containing ${rows?.length || 0} rows of data.` }]
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makeshkumar/mcp-xl-reader",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "main": "dist/index.js",
   "type": "module",
   "scripts": {
@@ -21,11 +21,12 @@
     "xlsx",
     "ai",
     "claude",
-    "tools"
+    "tools",
+    "workbook"
   ],
   "author": "Makesh Kumar",
   "license": "MIT",
-  "description": "An MCP server to read, search, and update local Excel (.xlsx) files.",
+  "description": "An MCP server to read, search, and update local Excel (.xlsx) files. Create new workbooks with reference path support.",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "exceljs": "^4.4.0"