ExcelTamer 0.2.0__tar.gz → 0.3.0__tar.gz

{exceltamer-0.2.0 → exceltamer-0.3.0}/ExcelTamer/mcp/engine/diff.py

@@ -53,12 +53,18 @@ def checkpoint_create(workbook_id: str, name: str) -> dict:
     
     return {"status": "created", "name": name, "path": str(cp_path)}
 
-def checkpoint_rollback(workbook_id: str, name: str) -> dict:
-    automation = session.get_workbook(workbook_id)
-    if not automation:
-        raise ValueError(f"Workbook {workbook_id} not found")
-        
-    if workbook_id not in checkpoints or name not in checkpoints[workbook_id]:
+def checkpoint_rollback(workbook_id: str, name: str) -> dict:
+    automation = session.get_workbook(workbook_id)
+    if not automation:
+        raise ValueError(f"Workbook {workbook_id} not found")
+
+    if getattr(automation, "attached", False):
+        raise ValueError(
+            "Checkpoint rollback is not supported for attached workbooks "
+            "because rollback must close and reopen the workbook"
+        )
+        
+    if workbook_id not in checkpoints or name not in checkpoints[workbook_id]:
         raise ValueError(f"Checkpoint '{name}' not found for this workbook")
         
     cp_path = checkpoints[workbook_id][name]

exceltamer-0.3.0/ExcelTamer/mcp/engine/workbook.py

@@ -0,0 +1,240 @@
+
+from typing import Any
+
+import xlwings as xw
+
+from ..config import DEFAULT_MODE
+from ..excel import ExcelAutomation
+from ..safety import validate_path
+from ..sessions import session
+
+
+def _workbook_path(workbook: Any) -> str | None:
+    """Return a saved workbook path, or None for an unsaved workbook."""
+    try:
+        if not workbook.api.Path:
+            return None
+        return str(workbook.fullname)
+    except Exception:
+        return None
+
+
+def _api_boolean(workbook: Any, property_name: str) -> bool | None:
+    try:
+        return bool(getattr(workbook.api, property_name))
+    except Exception:
+        return None
+
+
+def workbook_metadata(automation: ExcelAutomation) -> dict:
+    """Return live metadata for a registered workbook."""
+    saved = _api_boolean(automation.wb, "Saved")
+    return {
+        "name": automation.wb.name,
+        "path": _workbook_path(automation.wb),
+        "app_pid": int(automation.app.pid),
+        "attached": bool(getattr(automation, "attached", False)),
+        "access_mode": getattr(automation, "access_mode", DEFAULT_MODE),
+        "read_only": _api_boolean(automation.wb, "ReadOnly"),
+        "has_unsaved_changes": None if saved is None else not saved,
+    }
+
+
+def list_open_workbooks() -> dict:
+    """Enumerate workbooks visible to xlwings in the current desktop session."""
+    workbooks = []
+    warnings = []
+
+    try:
+        apps = list(xw.apps)
+    except Exception as exc:
+        return {
+            "count": 0,
+            "workbooks": [],
+            "warnings": [{"app_pid": None, "error": str(exc)}],
+        }
+
+    try:
+        active_app = xw.apps.active
+        active_pid = int(active_app.pid) if active_app is not None else None
+    except Exception:
+        active_pid = None
+
+    for app in apps:
+        try:
+            app_pid = int(app.pid)
+        except Exception as exc:
+            warnings.append({"app_pid": None, "error": str(exc)})
+            continue
+
+        try:
+            books = list(app.books)
+            active_book = app.books.active if app.books else None
+            active_name = active_book.name if active_book is not None else None
+        except Exception as exc:
+            warnings.append({"app_pid": app_pid, "error": str(exc)})
+            continue
+
+        for book in books:
+            try:
+                name = book.name
+                saved = _api_boolean(book, "Saved")
+                workbooks.append(
+                    {
+                        "app_pid": app_pid,
+                        "name": name,
+                        "path": _workbook_path(book),
+                        "active": (
+                            app_pid == active_pid and name == active_name
+                        ),
+                        "read_only": _api_boolean(book, "ReadOnly"),
+                        "has_unsaved_changes": (
+                            None if saved is None else not saved
+                        ),
+                        "workbook_id": session.find_workbook_id(
+                            app_pid,
+                            name,
+                        ),
+                    }
+                )
+            except Exception as exc:
+                try:
+                    workbook_name = book.name
+                except Exception:
+                    workbook_name = None
+                warnings.append(
+                    {
+                        "app_pid": app_pid,
+                        "workbook": workbook_name,
+                        "error": str(exc),
+                    }
+                )
+
+    return {
+        "count": len(workbooks),
+        "workbooks": workbooks,
+        "warnings": warnings,
+    }
+
+
+def attach_workbook() -> dict:
+    """Attach the active workbook without opening or taking ownership of it."""
+    try:
+        apps = list(xw.apps)
+    except Exception as exc:
+        raise ValueError("No running Excel application found") from exc
+    if not apps:
+        raise ValueError("No running Excel application found")
+
+    try:
+        app = xw.apps.active
+    except Exception as exc:
+        raise ValueError("No active Excel application found") from exc
+    if app is None:
+        raise ValueError("No active Excel application found")
+
+    try:
+        if not app.books:
+            raise ValueError("The active Excel application has no open workbook")
+        workbook = app.books.active
+    except ValueError:
+        raise
+    except Exception as exc:
+        raise ValueError(
+            "The active Excel application has no active workbook"
+        ) from exc
+    if workbook is None:
+        raise ValueError("The active Excel application has no active workbook")
+
+    app_pid = int(app.pid)
+    name = workbook.name
+    existing_id = session.find_workbook_id(app_pid, name)
+    if existing_id:
+        automation = session.get_workbook(existing_id)
+        return {
+            "workbook_id": existing_id,
+            "app_pid": app_pid,
+            "name": name,
+            "path": _workbook_path(workbook),
+            "sheets": automation.list_sheets(),
+            "attached": bool(getattr(automation, "attached", False)),
+            "already_attached": True,
+        }
+
+    automation = ExcelAutomation.attach(app, workbook)
+    workbook_id = session.add_workbook(automation)
+    return {
+        "workbook_id": workbook_id,
+        "app_pid": app_pid,
+        "name": name,
+        "path": _workbook_path(workbook),
+        "sheets": automation.list_sheets(),
+        "attached": True,
+        "already_attached": False,
+    }
+
+
+def open_workbook(path: str, mode: str = DEFAULT_MODE) -> dict:
+    """
+    Opens a workbook and returns its ID and metadata.
+    mode: 'ro' (read-only) or 'rw' (read-write)
+    """
+    # 1. Validate path
+    abs_path = validate_path(path)
+    
+    # 2. Open workbook
+    # Note: Xlwings doesn't strictly support 'ro' at open() level easily without API flags,
+    # but we will enforce it at the Write tool level.
+    # We pass the validated absolute path string.
+    automation = ExcelAutomation(
+        file_path=str(abs_path),
+        access_mode=mode,
+    )
+    
+    # 3. Store in session
+    wb_id = session.add_workbook(automation)
+    
+    # 4. Gather metadata
+    sheets = automation.list_sheets()
+    
+    return {
+        "workbook_id": wb_id,
+        "filename": abs_path.name,
+        "sheets": sheets,
+        "mode": mode
+    }
+
+def close_workbook(workbook_id: str) -> dict:
+    automation = session.get_workbook(workbook_id)
+    if not automation:
+        raise ValueError(f"Workbook {workbook_id} not found")
+        
+    if getattr(automation, "attached", False):
+        session.remove_workbook(workbook_id)
+        return {"status": "detached", "workbook_id": workbook_id}
+
+    # Close without quitting app to support multiple workbooks
+    automation.close(quit_app=False)
+    session.remove_workbook(workbook_id)
+    
+    return {"status": "closed", "workbook_id": workbook_id}
+
+def save_workbook(workbook_id: str) -> dict:
+    automation = session.get_workbook(workbook_id)
+    if not automation:
+        raise ValueError(f"Workbook {workbook_id} not found")
+        
+    automation.save()
+    return {"status": "saved", "workbook_id": workbook_id}
+
+def save_as_workbook(workbook_id: str, output_path: str) -> dict:
+    # 1. Validate output path
+    abs_path = validate_path(output_path, allow_write=True)
+    
+    automation = session.get_workbook(workbook_id)
+    if not automation:
+        raise ValueError(f"Workbook {workbook_id} not found")
+        
+    automation.save(str(abs_path))
+    
+    return {"status": "saved_as", "path": str(abs_path), "workbook_id": workbook_id}

{exceltamer-0.2.0 → exceltamer-0.3.0}/ExcelTamer/mcp/excel.py

@@ -10,14 +10,40 @@ logger = logging.getLogger(__name__)
 
 
 class ExcelAutomation:
-    """Own an Excel application/workbook pair for one MCP session entry."""
-
-    def __init__(self, file_path: str | None = None):
-        self.app = xw.apps.active if xw.apps else xw.App(visible=True)
-        self.wb = (
-            self.app.books.open(file_path)
-            if file_path
-            else self.app.books.active if self.app.books else self.app.books.add()
+    """Manage an Excel application/workbook pair for one MCP session entry."""
+
+    def __init__(
+        self,
+        file_path: str | None = None,
+        *,
+        app: Any | None = None,
+        workbook: Any | None = None,
+        attached: bool = False,
+        access_mode: str = "rw",
+    ):
+        if workbook is not None:
+            self.app = app if app is not None else workbook.app
+            self.wb = workbook
+        else:
+            self.app = xw.apps.active if xw.apps else xw.App(visible=True)
+            self.wb = (
+                self.app.books.open(file_path)
+                if file_path
+                else self.app.books.active
+                if self.app.books
+                else self.app.books.add()
+            )
+        self.attached = attached
+        self.access_mode = access_mode
+
+    @classmethod
+    def attach(cls, app: Any, workbook: Any) -> "ExcelAutomation":
+        """Create a non-owning handle for a workbook already open in Excel."""
+        return cls(
+            app=app,
+            workbook=workbook,
+            attached=True,
+            access_mode="rw",
         )
 
     def save(self, file_path: str | None = None) -> None:

{exceltamer-0.2.0 → exceltamer-0.3.0}/ExcelTamer/mcp/server.py

@@ -1,5 +1,6 @@
 
 import asyncio
+import json
 import logging
 from pathlib import Path
 
@@ -30,21 +31,46 @@ 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.",
+        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.",
+                "required": ["path"]
+            }
+        ),
+        Tool(
+            name="excel.list_open_workbooks",
+            description=(
+                "List all Excel workbooks already open in the current Windows "
+                "desktop session. This deliberately bypasses allowed-root filtering."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {}
+            }
+        ),
+        Tool(
+            name="excel.attach_workbook",
+            description=(
+                "Attach the active Excel workbook without reopening or taking "
+                "ownership of it."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {}
+            }
+        ),
+        Tool(
+            name="excel.close",
+            description=(
+                "Close an MCP-opened workbook, or detach a workbook that was "
+                "already open in Excel."
+            ),
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -211,9 +237,12 @@ async def handle_list_tools() -> list[Tool]:
                 "required": ["workbook_id", "name"]
             }
         ),
-        Tool(
-            name="excel.checkpoint_rollback",
-            description="Rollback workbook to a named checkpoint (reloads file).",
+        Tool(
+            name="excel.checkpoint_rollback",
+            description=(
+                "Restore a named checkpoint for an MCP-opened workbook. "
+                "Rollback is not available for attached workbooks."
+            ),
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -241,24 +270,27 @@ async def handle_list_tools() -> list[Tool]:
 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"
+    wb_list_resource = Resource(
+        uri="excel://workbooks",
+        name="Open Workbooks",
+        description="Metadata for workbooks registered in the MCP session",
+        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)
+        workbooks = []
+        for wb_id, automation in session.open_workbooks.items():
+            workbooks.append(
+                {
+                    "id": wb_id,
+                    "workbook_id": wb_id,
+                    **workbook_engine.workbook_metadata(automation),
+                }
+            )
+        return json.dumps(workbooks)
     
     # Pattern: excel://workbooks/{id}/summary
     # Simple manual parsing since we don't have pattern matching in this basic skeleton
@@ -325,15 +357,23 @@ async def handle_call_tool(
         arguments = {}
         
     try:
-        if name == "excel.open_workbook":
+        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":
+            result = workbook_engine.open_workbook(path, mode)
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.list_open_workbooks":
+            result = workbook_engine.list_open_workbooks()
+            return [TextContent(type="text", text=str(result))]
+
+        elif name == "excel.attach_workbook":
+            result = workbook_engine.attach_workbook()
+            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")
@@ -498,36 +538,35 @@ async def run_stdio():
             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(
+async def run_sse(port: int):
+    from mcp.server.sse import SseServerTransport
+    from starlette.applications import Starlette
+    from starlette.responses import Response
+    from starlette.routing import Mount, 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"])
-        ]
-    )
+                streams[1], 
+                server.create_initialization_options()
+            )
+        return Response()
+        
+    app = Starlette(
+        debug=True,
+        routes=[
+            Route("/sse", endpoint=handle_sse, methods=["GET"]),
+            Mount("/messages/", app=sse.handle_post_message),
+        ]
+    )
     
     config = uvicorn.Config(app, host="0.0.0.0", port=port, log_level="info")
     server_instance = uvicorn.Server(config)

{exceltamer-0.2.0 → exceltamer-0.3.0}/ExcelTamer/mcp/sessions.py

@@ -21,12 +21,27 @@ class SessionState:
         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 get_workbook(self, wb_id: str) -> Optional[ExcelAutomation]:
+        return self.open_workbooks.get(wb_id)
+
+    def find_workbook_id(self, app_pid: int, workbook_name: str) -> Optional[str]:
+        """Find an existing session entry by its live Excel identity."""
+        for wb_id, automation in self.open_workbooks.items():
+            try:
+                if (
+                    int(automation.app.pid) == int(app_pid)
+                    and automation.wb.name == workbook_name
+                ):
+                    return wb_id
+            except Exception:
+                # A stale or inaccessible Excel handle must not prevent discovery
+                # of other workbooks.
+                continue
+        return None
+
+    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()

{exceltamer-0.2.0 → exceltamer-0.3.0}/ExcelTamer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelTamer
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Model Context Protocol server for safe Microsoft Excel automation
 Author: Shamit
 License-Expression: GPL-3.0-only
@@ -33,6 +33,9 @@ client.
 below or read the
 [complete MCP usage guide](https://github.com/shamitv/ExcelTamer/blob/main/docs/mcp_server.md).
 
+**Building or contributing?** Read the
+[developer guide](https://github.com/shamitv/ExcelTamer/blob/main/docs/developer_guide.md).
+
 ## Quick start: use ExcelTamer with an MCP client
 
 ### 1. Install ExcelTamer
@@ -41,13 +44,19 @@ ExcelTamer requires Windows with Microsoft Excel installed and Python 3.11 or
 newer.
 
 ```powershell
-pip install .
+pip install ExcelTamer
 ```
 
 ### 2. Add ExcelTamer to your MCP client
 
-Add this client-neutral server definition to your MCP client's configuration,
-replacing the allowed root with the directory containing your workbooks:
+Choose either stdio or SSE, depending on the transports supported by your MCP
+client.
+
+#### Stdio
+
+For the default stdio transport, add this server definition to your MCP
+client's configuration, replacing the allowed root with the directory
+containing your workbooks:
 
 ```json
 {
@@ -66,6 +75,32 @@ replacing the allowed root with the directory containing your workbooks:
 access. The server defaults to read-only workbook mode and records write
 operations in an audit log.
 
+#### SSE
+
+To use SSE, start ExcelTamer separately in PowerShell. Set server environment
+variables in the same shell:
+
+```powershell
+$env:EXCELTAMER_MCP_ALLOWED_ROOTS = "C:\Users\you\Documents\Excel"
+exceltamer-mcp --port 8123
+```
+
+Then configure an SSE-capable MCP client to connect to the stream endpoint:
+
+```json
+{
+  "mcpServers": {
+    "exceltamer": {
+      "url": "http://127.0.0.1:8123/sse"
+    }
+  }
+}
+```
+
+Client configuration field names can vary; use
+`http://127.0.0.1:8123/sse` as the server URL. ExcelTamer receives client
+messages at `http://127.0.0.1:8123/messages/`.
+
 ### 3. Restart the client and ask it to use Excel
 
 For inspection, try:
@@ -88,6 +123,32 @@ the checkpoint.
 Your MCP client handles the `excel.*` tool calls and carries the returned
 `workbook_id` through the workflow.
 
+If the workbook is already open in Excel, focus its Excel window and try:
+
+```text
+List the workbooks currently open in Excel, attach the active workbook,
+describe its worksheets and used ranges, and then detach from it without
+closing the workbook or Excel.
+```
+
+That follows the `list → attach → operate → detach` workflow:
+
+1. `excel.list_open_workbooks` discovers workbooks in all visible Excel
+   applications.
+2. `excel.attach_workbook` registers the active workbook and returns its
+   `workbook_id`.
+3. Read, write, checkpoint, and save tools operate on that identifier.
+4. `excel.close` removes an attached workbook from the MCP session but leaves
+   both the workbook and Excel open.
+
+> **Security warning:** Discovery and attachment deliberately bypass
+> `EXCELTAMER_MCP_ALLOWED_ROOTS`. They can expose every workbook open in the
+> same Windows user session, including unsaved workbooks and files outside the
+> configured roots. Use these tools only with a trusted local MCP client.
+> Checkpoint creation is supported for attached workbooks, but checkpoint
+> rollback is rejected because rollback would have to close and reopen the
+> user's workbook.
+
 ## Run the server manually
 
 Start the default stdio transport:
@@ -144,7 +205,9 @@ the quick start, or in the shell before starting `exceltamer-mcp`.
 
 ## Capabilities
 
-- Open, inspect, save, save-as, and close workbooks
+- Discover all open Excel workbooks and attach the active one without
+  reopening or taking ownership of it
+- Open, inspect, save, save-as, close, and detach workbooks
 - Read cells, ranges, sheet previews, and workbook structure
 - Write cells, batches, and rectangular ranges
 - Search workbook values with exact, contains, or regex matching
@@ -152,6 +215,8 @@ the quick start, or in the shell before starting `exceltamer-mcp`.
 - Inspect recent write history
 - Discover workbook resources and MCP-native workflow prompts
 
+ExcelTamer 0.3.0 exposes 17 MCP tools, one resource, and two prompts.
+
 ## Validation
 
 Run the automated MCP smoke tests:

{exceltamer-0.2.0 → exceltamer-0.3.0}/ExcelTamer.egg-info/SOURCES.txt

@@ -27,4 +27,5 @@ ExcelTamer/mcp/prompts/README.md
 ExcelTamer/mcp/prompts/financial_metric_extract.md
 ExcelTamer/mcp/prompts/safe_edit.md
 ExcelTamer/mcp/schemas/__init__.py
+docs/developer_guide.md
 test/test_mcp_smoke.py