ExcelTamer 0.2.0__py3-none-any.whl

ExcelTamer/mcp/main.py

@@ -0,0 +1,18 @@
+
+import asyncio
+import sys
+import argparse
+from .server import run
+
+def main():
+    parser = argparse.ArgumentParser(description="ExcelTamer MCP Server")
+    parser.add_argument("--port", type=int, help="Port to run the SSE server on (default: stdio mode)")
+    args = parser.parse_args()
+    
+    try:
+        asyncio.run(run(port=args.port))
+    except KeyboardInterrupt:
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()

ExcelTamer/mcp/prompts/financial_metric_extract.md

@@ -0,0 +1,23 @@
+
+You are an expert financial analyst. Your goal is to extract a specific financial metric (e.g., "Net Income", "Revenue") from an Excel workbook reliably.
+
+Follow these steps:
+
+1. **Locate Data**:
+   - Open the workbook.
+   - Use `excel.search` to find the metric name (e.g., "Net Income") in the workbook.
+   - Note the sheet name and row number.
+
+2. **Identify Time Axis**:
+   - Look for date headers (years like "2023", "2024" or quarters "Q1", "Q2") in the rows above the metric or columns to the left.
+   - Use `excel.read_sheet_preview` or `excel.read_range` around the found metric cell to understand the table layout.
+
+3. **Extract Series**:
+   - Once you identified the metric row and the time columns, read the specific intersection cells using `excel.query_cell` or `excel.read_range`.
+
+4. **Validate**:
+   - Ensure the extracted values are numbers. If they are formulas, note that.
+
+5. **Report**:
+   - Present the extracted time-series data clearly.
+   - Close the workbook.

ExcelTamer/mcp/prompts/safe_edit.md

@@ -0,0 +1,26 @@
+
+You are tasked with safely editing an Excel workbook using the `ExcelTamer` tools.
+Follow this workflow strictly to ensure data integrity:
+
+1. **Open & Inspect**: 
+   - Open the workbook (`excel.open_workbook`).
+   - Read the structure (`excel.get_structure`) and preview relevant sheets (`excel.read_sheet_preview`).
+
+2. **Plan**: 
+   - Identify the specific cells or ranges that need modification.
+   - If searching for data, use `excel.search`.
+
+3. **Checkpoint (Critical)**:
+   - Before making ANY changes, create a checkpoint (`excel.checkpoint_create` with name "pre_edit").
+
+4. **Edit**:
+   - Apply changes using `excel.change_cell_value` or `excel.batch_update_cells` or `excel.write_range`.
+
+5. **Verify**:
+   - Read back the changed cells (`excel.read_range` or `excel.query_cell`) to confirm they match expectations.
+   - Check the operation history (`excel.preview_diff`).
+
+6. **Finalize**:
+   - If successful, save the workbook (`excel.save` or `excel.save_as`).
+   - If something went wrong, rollback immediately (`excel.checkpoint_rollback` name="pre_edit").
+   - Close the workbook (`excel.close`).

ExcelTamer/mcp/safety.py

@@ -0,0 +1,39 @@
+
+import os
+from pathlib import Path
+from .config import ALLOWED_ROOTS
+
+class SecurityError(Exception):
+    pass
+
+def validate_path(request_path: str, allow_write: bool = False) -> Path:
+    """
+    Validates that the given path is within ALLOWED_ROOTS.
+    Resolves symlinks and checks for traversal.
+    """
+    try:
+        # Resolve user path to absolute
+        abs_path = Path(request_path).resolve()
+        
+        # Check if it matches any allowed root
+        is_allowed = False
+        for root in ALLOWED_ROOTS:
+            allowed_root = Path(root).resolve()
+            # method 1: check if allowed_root is a parent of abs_path
+            # calculate relative path; if it starts with '..', it's outside
+            try:
+                abs_path.relative_to(allowed_root)
+                is_allowed = True
+                break
+            except ValueError:
+                continue
+        
+        if not is_allowed:
+            raise SecurityError(f"Path '{request_path}' is not within allowed roots: {ALLOWED_ROOTS}")
+            
+        return abs_path
+
+    except Exception as e:
+        if isinstance(e, SecurityError):
+            raise
+        raise SecurityError(f"Invalid path: {e}")

ExcelTamer/mcp/server.py

@@ -0,0 +1,541 @@
+
+import asyncio
+import logging
+from pathlib import Path
+
+from mcp.server import Server
+from mcp.types import (
+    Tool,
+    TextContent,
+    ImageContent,
+    EmbeddedResource
+)
+import mcp.types as types
+
+from .engine import workbook as workbook_engine
+from .engine import read as read_engine
+from .engine import write as write_engine
+from .engine import search as search_engine
+from .engine import diff as diff_engine
+from .sessions import session
+from mcp.types import Resource, Prompt, PromptMessage, PromptArgument
+
+# Configure logging (stderr so it doesn't break json-rpc on stdout)
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+logger = logging.getLogger("ExcelTamerMCP")
+
+server = Server("exceltamer-mcp")
+PROMPT_DIR = Path(__file__).with_name("prompts")
+
+@server.list_tools()
+async def handle_list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="excel.open_workbook",
+            description="Open an Excel workbook and get a workbook_id. required for other operations.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Absolute path to the Excel file"},
+                    "mode": {"type": "string", "enum": ["ro", "rw"], "default": "ro", "description": "Open mode: ro=read-only, rw=read-write"}
+                },
+                "required": ["path"]
+            }
+        ),
+        Tool(
+            name="excel.close",
+            description="Close an open workbook by ID.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"}
+                },
+                "required": ["workbook_id"]
+            }
+        ),
+        Tool(
+            name="excel.save",
+            description="Save the workbook (overwriting file).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"}
+                },
+                "required": ["workbook_id"]
+            }
+        ),
+        Tool(
+            name="excel.save_as",
+            description="Save the workbook to a new path.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "output_path": {"type": "string"}
+                },
+                "required": ["workbook_id", "output_path"]
+            }
+        ),
+        Tool(
+            name="excel.get_structure",
+            description="Get structure of the workbook (sheets, named ranges).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"}
+                },
+                "required": ["workbook_id"]
+            }
+        ),
+        Tool(
+            name="excel.query_cell",
+            description="Get value, formula, and text of a specific cell.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "sheet": {"type": "string"},
+                    "cell": {"type": "string"}
+                },
+                "required": ["workbook_id", "sheet", "cell"]
+            }
+        ),
+        Tool(
+            name="excel.read_range",
+            description="Read a range of cells as a 2D array.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "sheet": {"type": "string"},
+                    "range_a1": {"type": "string", "description": "Range address (e.g. A1:C10). If omitted, uses used range."},
+                    "max_rows": {"type": "integer", "default": 1000},
+                    "max_cols": {"type": "integer", "default": 100}
+                },
+                "required": ["workbook_id", "sheet"]
+            }
+        ),
+        Tool(
+            name="excel.read_sheet_preview",
+            description="Quick preview of a sheet's content (top-left).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "sheet": {"type": "string"},
+                    "rows": {"type": "integer", "default": 50},
+                    "cols": {"type": "integer", "default": 20}
+                },
+                "required": ["workbook_id", "sheet"]
+            }
+        ),
+        Tool(
+            name="excel.change_cell_value",
+            description="Write a value/formula to a single cell.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "sheet": {"type": "string"},
+                    "cell": {"type": "string"},
+                    "value": {"type": ["string", "number", "boolean", "null"]}
+                },
+                "required": ["workbook_id", "sheet", "cell", "value"]
+            }
+        ),
+        Tool(
+            name="excel.batch_update_cells",
+            description="Write multiple non-contiguous cells in one go.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "updates": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "sheet": {"type": "string"},
+                                "cell": {"type": "string"},
+                                "value": {"type": ["string", "number", "boolean", "null"]}
+                            },
+                            "required": ["sheet", "cell", "value"]
+                        }
+                    }
+                },
+                "required": ["workbook_id", "updates"]
+            }
+        ),
+        Tool(
+            name="excel.write_range",
+            description="Write a 2D array of values starting at a specific cell.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "sheet": {"type": "string"},
+                    "start_cell": {"type": "string"},
+                    "values": {
+                        "type": "array", 
+                        "items": {"type": "array", "items": {"type": ["string", "number", "boolean", "null"]}}
+                    }
+                },
+                "required": ["workbook_id", "sheet", "start_cell", "values"]
+            }
+        ),
+        Tool(
+            name="excel.search",
+            description="Search for a value across a sheet or the entire workbook.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "query": {"type": "string"},
+                    "sheet": {"type": "string", "description": "Optional. If omitted, searches all sheets."},
+                    "scope": {"type": "string", "enum": ["values", "formulas", "both"], "default": "both"},
+                    "match_mode": {"type": "string", "enum": ["contains", "exact", "regex"], "default": "contains"},
+                    "max_hits": {"type": "integer", "default": 200}
+                },
+                "required": ["workbook_id", "query"]
+            }
+        ),
+        Tool(
+            name="excel.checkpoint_create",
+            description="Create a named checkpoint of the current workbook state.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "name": {"type": "string"}
+                },
+                "required": ["workbook_id", "name"]
+            }
+        ),
+        Tool(
+            name="excel.checkpoint_rollback",
+            description="Rollback workbook to a named checkpoint (reloads file).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "name": {"type": "string"}
+                },
+                "required": ["workbook_id", "name"]
+            }
+        ),
+        Tool(
+            name="excel.preview_diff",
+            description="Show recent changes/audit history for this workbook.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "workbook_id": {"type": "string"},
+                    "max_changes": {"type": "integer", "default": 20}
+                },
+                "required": ["workbook_id"]
+            }
+        )
+    ]
+
+@server.list_resources()
+async def handle_list_resources() -> list[Resource]:
+    # Resource: List of open workbooks
+    # URI: excel://workbooks
+    wb_list_resource = Resource(
+        uri="excel://workbooks",
+        name="Open Workbooks",
+        description="List of currently open workbook IDs and filenames",
+        mimeType="application/json"
+    )
+    return [wb_list_resource]
+
+@server.read_resource()
+async def handle_read_resource(uri: str) -> str | bytes:
+    if uri == "excel://workbooks":
+        workbooks = []
+        for wb_id, automation in session.open_workbooks.items():
+            workbooks.append({
+                "id": wb_id,
+                "name": automation.wb.name
+            })
+        return str(workbooks)
+    
+    # Pattern: excel://workbooks/{id}/summary
+    # Simple manual parsing since we don't have pattern matching in this basic skeleton
+    import re
+    match = re.match(r"excel://workbooks/([^/]+)/summary", uri)
+    if match:
+        wb_id = match.group(1)
+        automation = session.get_workbook(wb_id)
+        if automation:
+            return str(read_engine.get_structure(wb_id))
+        else:
+            raise ValueError(f"Workbook {wb_id} not found")
+
+    raise ValueError(f"Resource not found: {uri}")
+
+@server.list_prompts()
+async def handle_list_prompts() -> list[Prompt]:
+    return [
+        Prompt(
+            name="safe-edit",
+            description="Workflow for safely editing an Excel file with checkpoints.",
+            arguments=[]
+        ),
+        Prompt(
+            name="financial-extract",
+            description="Workflow for extracting financial metrics.",
+            arguments=[]
+        )
+    ]
+
+@server.get_prompt()
+async def handle_get_prompt(name: str, arguments: dict | None) -> types.GetPromptResult:
+    if name == "safe-edit":
+        content = (PROMPT_DIR / "safe_edit.md").read_text(encoding="utf-8")
+        return types.GetPromptResult(
+            messages=[
+                PromptMessage(
+                    role="user",
+                    content=TextContent(type="text", text=content)
+                )
+            ]
+        )
+        
+    elif name == "financial-extract":
+        content = (PROMPT_DIR / "financial_metric_extract.md").read_text(
+            encoding="utf-8"
+        )
+        return types.GetPromptResult(
+            messages=[
+                PromptMessage(
+                    role="user",
+                    content=TextContent(type="text", text=content)
+                )
+            ]
+        )
+        
+    raise ValueError(f"Prompt not found: {name}")
+
+@server.call_tool()
+async def handle_call_tool(
+    name: str, arguments: dict | None
+) -> list[TextContent | ImageContent | EmbeddedResource]:
+    if not arguments:
+        arguments = {}
+        
+    try:
+        if name == "excel.open_workbook":
+            path = arguments.get("path")
+            mode = arguments.get("mode", "ro")
+            if not path:
+                raise ValueError("path is required")
+            result = workbook_engine.open_workbook(path, mode)
+            return [TextContent(type="text", text=str(result))]
+            
+        elif name == "excel.close":
+            workbook_id = arguments.get("workbook_id")
+            if not workbook_id:
+                raise ValueError("workbook_id is required")
+            result = workbook_engine.close_workbook(workbook_id)
+            return [TextContent(type="text", text=str(result))]
+            
+        elif name == "excel.save":
+            workbook_id = arguments.get("workbook_id")
+            if not workbook_id:
+                raise ValueError("workbook_id is required")
+            result = workbook_engine.save_workbook(workbook_id)
+            return [TextContent(type="text", text=str(result))]
+            
+        elif name == "excel.save_as":
+            workbook_id = arguments.get("workbook_id")
+            output_path = arguments.get("output_path")
+            if not workbook_id or not output_path:
+                raise ValueError("workbook_id and output_path are required")
+            result = workbook_engine.save_as_workbook(workbook_id, output_path)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.get_structure":
+            workbook_id = arguments.get("workbook_id")
+            if not workbook_id:
+                raise ValueError("workbook_id is required")
+            result = read_engine.get_structure(workbook_id)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.query_cell":
+            workbook_id = arguments.get("workbook_id")
+            sheet = arguments.get("sheet")
+            cell = arguments.get("cell")
+            if not workbook_id or not sheet or not cell:
+                raise ValueError("workbook_id, sheet, and cell are required")
+            result = read_engine.query_cell(workbook_id, sheet, cell)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.read_range":
+            workbook_id = arguments.get("workbook_id")
+            sheet = arguments.get("sheet")
+            range_a1 = arguments.get("range_a1")
+            max_rows = arguments.get("max_rows", 1000)
+            max_cols = arguments.get("max_cols", 100)
+            
+            if not workbook_id or not sheet:
+                raise ValueError("workbook_id and sheet are required")
+            
+            result = read_engine.read_range(
+                workbook_id, 
+                sheet, 
+                range_a1=range_a1, 
+                max_rows=max_rows, 
+                max_cols=max_cols
+            )
+            return [TextContent(type="text", text=str(result))]
+            
+        elif name == "excel.read_sheet_preview":
+            workbook_id = arguments.get("workbook_id")
+            sheet = arguments.get("sheet")
+            rows = arguments.get("rows", 50)
+            cols = arguments.get("cols", 20)
+            
+            if not workbook_id or not sheet:
+                raise ValueError("workbook_id and sheet are required")
+            
+            result = read_engine.read_sheet_preview(workbook_id, sheet, rows=rows, cols=cols)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.change_cell_value":
+            workbook_id = arguments.get("workbook_id")
+            sheet = arguments.get("sheet")
+            cell = arguments.get("cell")
+            value = arguments.get("value")
+            
+            if not workbook_id or not sheet or not cell:
+                raise ValueError("workbook_id, sheet, and cell are required")
+                
+            result = write_engine.change_cell_value(workbook_id, sheet, cell, value)
+            return [TextContent(type="text", text=str(result))]
+            
+        elif name == "excel.batch_update_cells":
+            workbook_id = arguments.get("workbook_id")
+            updates = arguments.get("updates")
+            
+            if not workbook_id or not updates:
+                raise ValueError("workbook_id and updates are required")
+                
+            result = write_engine.batch_update_cells(workbook_id, updates)
+            return [TextContent(type="text", text=str(result))]
+            
+        elif name == "excel.write_range":
+            workbook_id = arguments.get("workbook_id")
+            sheet = arguments.get("sheet")
+            start_cell = arguments.get("start_cell")
+            values = arguments.get("values")
+            
+            if not workbook_id or not sheet or not start_cell or values is None:
+                raise ValueError("workbook_id, sheet, start_cell, and values are required")
+                
+            result = write_engine.write_range(workbook_id, sheet, start_cell, values)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.search":
+            workbook_id = arguments.get("workbook_id")
+            query = arguments.get("query")
+            sheet = arguments.get("sheet")
+            scope = arguments.get("scope", "both")
+            match_mode = arguments.get("match_mode", "contains")
+            max_hits = arguments.get("max_hits", 200)
+            
+            if not workbook_id or not query:
+                raise ValueError("workbook_id and query are required")
+                
+            result = search_engine.search(
+                workbook_id, query, 
+                sheet=sheet, 
+                scope=scope, 
+                match_mode=match_mode, 
+                max_hits=max_hits
+            )
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.checkpoint_create":
+            workbook_id = arguments.get("workbook_id")
+            name = arguments.get("name")
+            if not workbook_id or not name:
+                raise ValueError("workbook_id and name required")
+            result = diff_engine.checkpoint_create(workbook_id, name)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.checkpoint_rollback":
+            workbook_id = arguments.get("workbook_id")
+            name = arguments.get("name")
+            if not workbook_id or not name:
+                raise ValueError("workbook_id and name required")
+            result = diff_engine.checkpoint_rollback(workbook_id, name)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.preview_diff":
+            workbook_id = arguments.get("workbook_id")
+            max_changes = arguments.get("max_changes", 20)
+            if not workbook_id:
+                raise ValueError("workbook_id required")
+            result = diff_engine.preview_diff(workbook_id, max_changes)
+            return [TextContent(type="text", text=str(result))]
+            
+        else:
+            raise ValueError(f"Unknown tool: {name}")
+
+    except Exception as e:
+        logger.error(f"Error executing {name}: {e}")
+        return [TextContent(type="text", text=f"Error: {str(e)}")]
+
+
+async def run_stdio():
+    from mcp.server.stdio import stdio_server
+    
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options()
+        )
+
+async def run_sse(port: int):
+    from mcp.server.sse import SseServerTransport
+    from starlette.applications import Starlette
+    from starlette.routing import Route
+    import uvicorn
+    
+    sse = SseServerTransport("/messages")
+    
+    async def handle_sse(request):
+        async with sse.connect_sse(
+            request.scope, 
+            request.receive, 
+            request._send
+        ) as streams:
+            await server.run(
+                streams[0], 
+                streams[1], 
+                server.create_initialization_options()
+            )
+            
+    async def handle_messages(request):
+        await sse.handle_post_message(request.scope, request.receive, request._send)
+        
+    app = Starlette(
+        debug=True,
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Route("/messages", endpoint=handle_messages, methods=["POST"])
+        ]
+    )
+    
+    config = uvicorn.Config(app, host="0.0.0.0", port=port, log_level="info")
+    server_instance = uvicorn.Server(config)
+    await server_instance.serve()
+
+async def run(port: int | None = None):
+    if port is not None:
+        await run_sse(port)
+    else:
+        await run_stdio()
+

ExcelTamer/mcp/sessions.py

@@ -0,0 +1,35 @@
+
+import uuid
+from typing import Dict, Optional
+from .excel import ExcelAutomation
+
+class SessionState:
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(SessionState, cls).__new__(cls)
+            cls._instance.open_workbooks = {}
+        return cls._instance
+
+    def __init__(self):
+        # type hints
+        self.open_workbooks: Dict[str, ExcelAutomation]
+
+    def add_workbook(self, automation: ExcelAutomation) -> str:
+        wb_id = str(uuid.uuid4())
+        self.open_workbooks[wb_id] = automation
+        return wb_id
+
+    def get_workbook(self, wb_id: str) -> Optional[ExcelAutomation]:
+        return self.open_workbooks.get(wb_id)
+
+    def remove_workbook(self, wb_id: str):
+        if wb_id in self.open_workbooks:
+            del self.open_workbooks[wb_id]
+
+    def clear(self):
+        self.open_workbooks.clear()
+
+# Global session singleton
+session = SessionState()