ExcelTamer 0.2.1__tar.gz → 0.3.0__tar.gz

{exceltamer-0.2.1 → 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.1 → 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.1 → 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")

{exceltamer-0.2.1 → 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.1 → exceltamer-0.3.0}/ExcelTamer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelTamer
-Version: 0.2.1
+Version: 0.3.0
 Summary: A Model Context Protocol server for safe Microsoft Excel automation
 Author: Shamit
 License-Expression: GPL-3.0-only
@@ -123,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:
@@ -179,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
@@ -187,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.1 → exceltamer-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelTamer
-Version: 0.2.1
+Version: 0.3.0
 Summary: A Model Context Protocol server for safe Microsoft Excel automation
 Author: Shamit
 License-Expression: GPL-3.0-only
@@ -123,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:
@@ -179,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
@@ -187,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.1 → exceltamer-0.3.0}/README.md

@@ -99,6 +99,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:
@@ -155,7 +181,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
@@ -163,6 +191,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.1 → exceltamer-0.3.0}/docs/developer_guide.md

@@ -119,10 +119,13 @@ Run the automated suite from the repository root:
 python -m unittest discover -s test -p "test_*.py" -v
 ```
 
-The current suite runs eight tests covering the MCP surface, packaged prompts,
-range normalization, engine read/search/write behavior, and a real stdio
-and SSE handshake. These tests use fakes where workbook behavior is needed and
-do not launch Microsoft Excel.
+The current suite runs twelve tests covering the 17-tool MCP surface, packaged
+prompts, range normalization, engine read/search/write behavior, four
+Excel-free attachment scenarios, and real stdio and SSE handshakes. The
+attachment tests cover multi-application discovery, saved and unsaved
+workbooks, out-of-root paths, idempotent attachment, clear missing-Excel
+errors, non-owning detach, and rollback rejection. These tests use fakes where
+workbook behavior is needed and do not launch Microsoft Excel.
 
 For optional live validation, use the included example workbook:
 
@@ -141,6 +144,13 @@ python test/mcp_client.py --transport sse --port 8123 --file .\test\example.xlsx
 The workbook must be under one of `EXCELTAMER_MCP_ALLOWED_ROOTS`. The default
 allowed root is the current working directory.
 
+To validate attachment manually, leave a workbook open and focused in Excel,
+then use an MCP client to call `excel.list_open_workbooks`,
+`excel.attach_workbook`, `excel.get_structure`, and `excel.close`. Confirm the
+last call returns `status: "detached"` and that both Excel and the workbook
+remain open. Discovery and attachment deliberately bypass allowed-root
+filtering, so perform this check only with non-sensitive workbooks.
+
 ## Build and verify packages
 
 Run the following workflow from a clean repository checkout with the virtual
@@ -155,7 +165,7 @@ Select-String -Path .\pyproject.toml -Pattern '^version = '
 git status --short
 ```
 
-The current version is `0.2.1`. Review unexpected working-tree changes before
+The current version is `0.3.0`. Review unexpected working-tree changes before
 building.
 
 ### 2. Run the automated tests
@@ -170,10 +180,10 @@ python -m unittest discover -s test -p "test_*.py" -v
 python -m build
 ```
 
-For version `0.2.1`, this creates:
+For version `0.3.0`, this creates:
 
-- `dist\exceltamer-0.2.1.tar.gz` — source distribution
-- `dist\exceltamer-0.2.1-py3-none-any.whl` — binary wheel
+- `dist\exceltamer-0.3.0.tar.gz` — source distribution
+- `dist\exceltamer-0.3.0-py3-none-any.whl` — binary wheel
 
 The `dist/` directory is ignored by Git. If it contains artifacts from other
 versions, verify only the files for the version being prepared.
@@ -182,8 +192,8 @@ versions, verify only the files for the version being prepared.
 
 ```powershell
 python -m twine check `
-  .\dist\exceltamer-0.2.1.tar.gz `
-  .\dist\exceltamer-0.2.1-py3-none-any.whl
+  .\dist\exceltamer-0.3.0.tar.gz `
+  .\dist\exceltamer-0.3.0-py3-none-any.whl
 ```
 
 Both artifacts must report `PASSED`.
@@ -192,8 +202,8 @@ Both artifacts must report `PASSED`.
 
 ```powershell
 Get-FileHash -Algorithm SHA256 `
-  .\dist\exceltamer-0.2.1.tar.gz, `
-  .\dist\exceltamer-0.2.1-py3-none-any.whl
+  .\dist\exceltamer-0.3.0.tar.gz, `
+  .\dist\exceltamer-0.3.0-py3-none-any.whl
 ```
 
 Record these hashes when artifacts are transferred or retained for a release.

{exceltamer-0.2.1 → exceltamer-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ExcelTamer"
-version = "0.2.1"
+version = "0.3.0"
 description = "A Model Context Protocol server for safe Microsoft Excel automation"
 readme = "README.md"
 authors = [

{exceltamer-0.2.1 → exceltamer-0.3.0}/test/test_mcp_smoke.py

@@ -1,36 +1,38 @@
 """MCP-only smoke tests that do not require Microsoft Excel."""
 
 import asyncio
+import json
 import os
 import socket
 import sys
 import unittest
 from types import SimpleNamespace
-from unittest.mock import patch
+from unittest.mock import Mock, patch
 
 import pandas as pd
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.sse import sse_client
 from mcp.client.stdio import stdio_client
 
-from ExcelTamer.mcp.engine import read, search, write
+from ExcelTamer.mcp.engine import diff, read, search, workbook, write
 from ExcelTamer.mcp.excel import ExcelAutomation
 from ExcelTamer.mcp.server import (
     handle_get_prompt,
     handle_list_prompts,
     handle_list_resources,
     handle_list_tools,
+    handle_read_resource,
 )
 from ExcelTamer.mcp.sessions import session
 
 
 class ProtocolSurfaceTests(unittest.TestCase):
-    def test_protocol_surface_is_unchanged(self):
+    def test_protocol_surface(self):
         tools = asyncio.run(handle_list_tools())
         resources = asyncio.run(handle_list_resources())
         prompts = asyncio.run(handle_list_prompts())
 
-        self.assertEqual(len(tools), 15)
+        self.assertEqual(len(tools), 17)
         self.assertEqual(len(resources), 1)
         self.assertEqual(
             {prompt.name for prompt in prompts},
@@ -167,6 +169,169 @@ class EngineTests(unittest.TestCase):
         self.assertEqual(self.backend.sheet.target.value, [[1, 2], [3, 4]])
 
 
+class AttachmentTests(unittest.TestCase):
+    class Book:
+        def __init__(
+            self,
+            name,
+            path=None,
+            *,
+            saved=True,
+            read_only=False,
+        ):
+            self.name = name
+            self.fullname = path or name
+            directory = path.rsplit("\\", 1)[0] if path else ""
+            self.api = SimpleNamespace(
+                Path=directory,
+                Saved=saved,
+                ReadOnly=read_only,
+            )
+            self.sheets = [SimpleNamespace(name="Sheet1")]
+            self.close = Mock()
+
+    class Books(list):
+        def __init__(self, books, active=None):
+            super().__init__(books)
+            self.active = active
+
+    class App:
+        def __init__(self, pid, books):
+            self.pid = pid
+            self.books = books
+
+    class Apps(list):
+        def __init__(self, apps, active=None):
+            super().__init__(apps)
+            self.active = active
+
+    def setUp(self):
+        session.clear()
+        diff.checkpoints.clear()
+
+    def tearDown(self):
+        session.clear()
+        diff.checkpoints.clear()
+
+    def test_lists_apps_saved_unsaved_and_out_of_root_workbooks(self):
+        saved = self.Book(
+            "Budget.xlsx",
+            r"C:\Users\you\Documents\Excel\Budget.xlsx",
+            read_only=True,
+        )
+        unsaved = self.Book("Book1", saved=False)
+        outside_root = self.Book(
+            "Private.xlsx",
+            r"D:\OutsideAllowedRoots\Private.xlsx",
+        )
+        first_app = self.App(101, self.Books([saved, unsaved], active=saved))
+        second_app = self.App(
+            202,
+            self.Books([outside_root], active=outside_root),
+        )
+
+        class InaccessibleApp:
+            pid = 303
+
+            @property
+            def books(self):
+                raise RuntimeError("Excel instance is inaccessible")
+
+        apps = self.Apps(
+            [first_app, second_app, InaccessibleApp()],
+            active=first_app,
+        )
+        registered_id = session.add_workbook(
+            ExcelAutomation.attach(first_app, saved)
+        )
+
+        with patch.object(workbook.xw, "apps", apps):
+            result = workbook.list_open_workbooks()
+
+        self.assertEqual(result["count"], 3)
+        by_name = {item["name"]: item for item in result["workbooks"]}
+        self.assertEqual(by_name["Budget.xlsx"]["workbook_id"], registered_id)
+        self.assertTrue(by_name["Budget.xlsx"]["active"])
+        self.assertTrue(by_name["Budget.xlsx"]["read_only"])
+        self.assertIsNone(by_name["Book1"]["path"])
+        self.assertTrue(by_name["Book1"]["has_unsaved_changes"])
+        self.assertEqual(
+            by_name["Private.xlsx"]["path"],
+            r"D:\OutsideAllowedRoots\Private.xlsx",
+        )
+        self.assertFalse(by_name["Private.xlsx"]["active"])
+        self.assertEqual(result["warnings"][0]["app_pid"], 303)
+        self.assertIn("inaccessible", result["warnings"][0]["error"])
+
+    def test_attaches_active_workbook_idempotently(self):
+        active_book = self.Book(
+            "Active.xlsx",
+            r"C:\Work\Active.xlsx",
+        )
+        app = self.App(404, self.Books([active_book], active=active_book))
+        apps = self.Apps([app], active=app)
+
+        with patch.object(workbook.xw, "apps", apps):
+            first = workbook.attach_workbook()
+            second = workbook.attach_workbook()
+
+        self.assertEqual(first["workbook_id"], second["workbook_id"])
+        self.assertEqual(first["app_pid"], 404)
+        self.assertEqual(first["sheets"], ["Sheet1"])
+        self.assertTrue(first["attached"])
+        self.assertFalse(first["already_attached"])
+        self.assertTrue(second["already_attached"])
+        self.assertEqual(len(session.open_workbooks), 1)
+
+    def test_attach_reports_no_excel_and_no_active_workbook(self):
+        with patch.object(workbook.xw, "apps", self.Apps([])):
+            with self.assertRaisesRegex(
+                ValueError,
+                "No running Excel application",
+            ):
+                workbook.attach_workbook()
+
+        app = self.App(505, self.Books([]))
+        with patch.object(workbook.xw, "apps", self.Apps([app], active=app)):
+            with self.assertRaisesRegex(ValueError, "no open workbook"):
+                workbook.attach_workbook()
+
+    def test_detaches_without_closing_and_rejects_rollback(self):
+        active_book = self.Book(
+            "Attached.xlsx",
+            r"C:\Work\Attached.xlsx",
+        )
+        app = self.App(606, self.Books([active_book], active=active_book))
+        apps = self.Apps([app], active=app)
+
+        with patch.object(workbook.xw, "apps", apps):
+            attached = workbook.attach_workbook()
+        workbook_id = attached["workbook_id"]
+
+        resource = json.loads(asyncio.run(handle_read_resource(
+            "excel://workbooks"
+        )))
+        self.assertEqual(resource[0]["app_pid"], 606)
+        self.assertEqual(resource[0]["path"], r"C:\Work\Attached.xlsx")
+        self.assertTrue(resource[0]["attached"])
+        self.assertEqual(resource[0]["access_mode"], "rw")
+
+        with patch.object(diff.shutil, "copy2") as copy2:
+            with self.assertRaisesRegex(
+                ValueError,
+                "not supported for attached workbooks",
+            ):
+                diff.checkpoint_rollback(workbook_id, "before")
+            copy2.assert_not_called()
+        active_book.close.assert_not_called()
+        self.assertIsNotNone(session.get_workbook(workbook_id))
+
+        result = workbook.close_workbook(workbook_id)
+        self.assertEqual(result["status"], "detached")
+        active_book.close.assert_not_called()
+        self.assertIsNone(session.get_workbook(workbook_id))
+
+
 class StdioHandshakeTests(unittest.IsolatedAsyncioTestCase):
     async def test_stdio_discovery_and_prompt_retrieval(self):
         env = os.environ.copy()
@@ -187,7 +352,7 @@ class StdioHandshakeTests(unittest.IsolatedAsyncioTestCase):
                 prompts = await session.list_prompts()
                 safe_edit = await session.get_prompt("safe-edit")
 
-                self.assertEqual(len(tools.tools), 15)
+                self.assertEqual(len(tools.tools), 17)
                 self.assertEqual(len(resources.resources), 1)
                 self.assertEqual(len(prompts.prompts), 2)
                 self.assertTrue(safe_edit.messages[0].content.text.strip())
@@ -229,7 +394,7 @@ class SseHandshakeTests(unittest.IsolatedAsyncioTestCase):
                         prompts = await session.list_prompts()
                         safe_edit = await session.get_prompt("safe-edit")
 
-                        self.assertEqual(len(tools.tools), 15)
+                        self.assertEqual(len(tools.tools), 17)
                         self.assertEqual(len(resources.resources), 1)
                         self.assertEqual(len(prompts.prompts), 2)
                         self.assertTrue(safe_edit.messages[0].content.text.strip())

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

@@ -1,63 +0,0 @@
-
-from ..config import DEFAULT_MODE
-from ..excel import ExcelAutomation
-from ..safety import validate_path
-from ..sessions import session
-
-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))
-    
-    # 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")
-        
-    # 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}