ExcelTamer 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -498,36 +498,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.2.1}/ExcelTamer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelTamer
-Version: 0.2.0
+Version: 0.2.1
 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:

{exceltamer-0.2.0 → exceltamer-0.2.1}/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

{exceltamer-0.2.0 → exceltamer-0.2.1}/MANIFEST.in

@@ -1,3 +1,4 @@
 include LICENSE
 include README.md
+include docs/developer_guide.md
 recursive-include ExcelTamer/mcp/prompts *.md

{exceltamer-0.2.0 → exceltamer-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ExcelTamer
-Version: 0.2.0
+Version: 0.2.1
 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:

{exceltamer-0.2.0 → exceltamer-0.2.1}/README.md

@@ -9,6 +9,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
@@ -17,13 +20,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
 {
@@ -42,6 +51,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:

exceltamer-0.2.1/docs/developer_guide.md

@@ -0,0 +1,202 @@
+# ExcelTamer Developer Guide
+
+This guide covers the Windows development workflow for ExcelTamer: setting up
+an editable checkout, navigating the MCP implementation, running automated and
+live validation, and building release artifacts. For MCP client configuration
+and the public protocol reference, see the [MCP server guide](mcp_server.md).
+
+## Prerequisites
+
+- Windows
+- Python 3.11, 3.12, 3.13, or 3.14
+- Git
+- Microsoft Excel for live workbook validation
+
+Microsoft Excel is not required to run the automated smoke tests or build the
+package.
+
+## Set up a development environment
+
+Clone the repository and enter its directory:
+
+```powershell
+git clone https://github.com/shamitv/ExcelTamer.git
+Set-Location ExcelTamer
+```
+
+Create and activate a virtual environment:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python --version
+```
+
+The reported Python version must be between 3.11 and 3.14. Install ExcelTamer
+in editable mode, then install the build-validation tools:
+
+```powershell
+python -m pip install --upgrade pip
+python -m pip install -e .
+python -m pip install build twine
+```
+
+`build` and `twine` are development tools and are intentionally not installed
+as ExcelTamer runtime dependencies.
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `pyproject.toml` | Package metadata, supported Python versions, runtime dependencies, and the `exceltamer-mcp` entry point |
+| `ExcelTamer/mcp/main.py` | CLI parsing and stdio/SSE transport selection |
+| `ExcelTamer/mcp/server.py` | MCP tools, resources, prompts, request dispatch, and transport hosts |
+| `ExcelTamer/mcp/engine/` | Workbook lifecycle, read, write, search, checkpoint, and audit-history operations |
+| `ExcelTamer/mcp/excel.py` | Internal xlwings backend |
+| `ExcelTamer/mcp/config.py` | Environment-driven server settings |
+| `ExcelTamer/mcp/safety.py` | Workbook path validation |
+| `ExcelTamer/mcp/audit.py` and `sessions.py` | Write-audit persistence and active workbook sessions |
+| `ExcelTamer/mcp/prompts/` | Markdown bodies for the packaged MCP prompts |
+| `test/test_mcp_smoke.py` | Automated protocol and engine smoke tests |
+| `test/mcp_client.py` | Standalone stdio/SSE validation client |
+| `docs/excel/` | Internal Excel behavior, constraints, and threading documentation |
+
+The MCP protocol is the public integration boundary. Treat the xlwings backend
+and engine modules as internal implementation details.
+
+## Run the development server
+
+After the editable install, the `exceltamer-mcp` command runs the current
+checkout.
+
+### Stdio
+
+Run the default stdio transport:
+
+```powershell
+exceltamer-mcp
+```
+
+The equivalent module command is:
+
+```powershell
+python -m ExcelTamer.mcp.main
+```
+
+The standalone client starts its own stdio server subprocess, performs MCP
+discovery, retrieves the packaged prompts, and exits:
+
+```powershell
+python test/mcp_client.py
+```
+
+### SSE
+
+Start the SSE server in one PowerShell window. Environment variables must be
+set in the server process:
+
+```powershell
+$env:EXCELTAMER_MCP_ALLOWED_ROOTS = (Get-Location).Path
+exceltamer-mcp --port 8123
+```
+
+In a second activated PowerShell window, connect the validation client:
+
+```powershell
+python test/mcp_client.py --transport sse --port 8123
+```
+
+The SSE stream is available at `http://127.0.0.1:8123/sse`; client messages are
+posted to `http://127.0.0.1:8123/messages/`. See the
+[configuration reference](mcp_server.md#configuration) for every environment
+variable that influences the server.
+
+## Test changes
+
+Run the automated suite from the repository root:
+
+```powershell
+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.
+
+For optional live validation, use the included example workbook:
+
+```powershell
+python test/mcp_client.py --file .\test\example.xlsx
+```
+
+This opens the workbook through Excel in read-only mode, retrieves its
+structure, and closes it. To run the same check against an already running SSE
+server:
+
+```powershell
+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.
+
+## Build and verify packages
+
+Run the following workflow from a clean repository checkout with the virtual
+environment activated.
+
+### 1. Confirm the package version
+
+The version used in both artifact names comes from `pyproject.toml`:
+
+```powershell
+Select-String -Path .\pyproject.toml -Pattern '^version = '
+git status --short
+```
+
+The current version is `0.2.1`. Review unexpected working-tree changes before
+building.
+
+### 2. Run the automated tests
+
+```powershell
+python -m unittest discover -s test -p "test_*.py" -v
+```
+
+### 3. Build the source and binary distributions
+
+```powershell
+python -m build
+```
+
+For version `0.2.1`, this creates:
+
+- `dist\exceltamer-0.2.1.tar.gz` — source distribution
+- `dist\exceltamer-0.2.1-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.
+
+### 4. Check PyPI metadata and README rendering
+
+```powershell
+python -m twine check `
+  .\dist\exceltamer-0.2.1.tar.gz `
+  .\dist\exceltamer-0.2.1-py3-none-any.whl
+```
+
+Both artifacts must report `PASSED`.
+
+### 5. Generate optional SHA-256 hashes
+
+```powershell
+Get-FileHash -Algorithm SHA256 `
+  .\dist\exceltamer-0.2.1.tar.gz, `
+  .\dist\exceltamer-0.2.1-py3-none-any.whl
+```
+
+Record these hashes when artifacts are transferred or retained for a release.
+
+Uploading to TestPyPI or PyPI, managing credentials, and publishing a release
+are intentionally outside the scope of this guide.

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

@@ -1,19 +1,19 @@
-[build-system]
-requires = ["setuptools>=83.0.0"]
-build-backend = "setuptools.build_meta"
-
+[build-system]
+requires = ["setuptools>=83.0.0"]
+build-backend = "setuptools.build_meta"
+
 [project]
 name = "ExcelTamer"
-version = "0.2.0"
+version = "0.2.1"
 description = "A Model Context Protocol server for safe Microsoft Excel automation"
 readme = "README.md"
 authors = [
   { name = "Shamit" },
 ]
-license = "GPL-3.0-only"
-license-files = ["LICENSE"]
-classifiers = [
-    "Programming Language :: Python :: 3",
+license = "GPL-3.0-only"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",

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

@@ -2,6 +2,7 @@
 
 import asyncio
 import os
+import socket
 import sys
 import unittest
 from types import SimpleNamespace
@@ -9,6 +10,7 @@ from unittest.mock import 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
@@ -191,5 +193,94 @@ class StdioHandshakeTests(unittest.IsolatedAsyncioTestCase):
                 self.assertTrue(safe_edit.messages[0].content.text.strip())
 
 
+class SseHandshakeTests(unittest.IsolatedAsyncioTestCase):
+    async def test_sse_discovery_and_prompt_retrieval(self):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as port_socket:
+            port_socket.bind(("127.0.0.1", 0))
+            port = port_socket.getsockname()[1]
+
+        env = os.environ.copy()
+        env["PYTHONPATH"] = os.pathsep.join(
+            path for path in (os.getcwd(), env.get("PYTHONPATH")) if path
+        )
+        process = await asyncio.create_subprocess_exec(
+            sys.executable,
+            "-m",
+            "ExcelTamer.mcp.main",
+            "--port",
+            str(port),
+            env=env,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stderr_text = ""
+        try:
+            await self._wait_for_listener(process, port)
+            async with asyncio.timeout(10):
+                async with sse_client(
+                    f"http://127.0.0.1:{port}/sse",
+                    timeout=5,
+                    sse_read_timeout=5,
+                ) as streams:
+                    async with ClientSession(*streams) as session:
+                        await session.initialize()
+                        tools = await session.list_tools()
+                        resources = await session.list_resources()
+                        prompts = await session.list_prompts()
+                        safe_edit = await session.get_prompt("safe-edit")
+
+                        self.assertEqual(len(tools.tools), 15)
+                        self.assertEqual(len(resources.resources), 1)
+                        self.assertEqual(len(prompts.prompts), 2)
+                        self.assertTrue(safe_edit.messages[0].content.text.strip())
+
+            # Give the request handler time to finish after the SSE client closes.
+            await asyncio.sleep(0.1)
+        finally:
+            if process.returncode is None:
+                process.terminate()
+                try:
+                    await asyncio.wait_for(process.wait(), timeout=5)
+                except TimeoutError:
+                    process.kill()
+                    await process.wait()
+            if process.stderr is not None:
+                stderr_text = (await process.stderr.read()).decode(
+                    errors="replace"
+                )
+
+        self.assertNotIn("Exception in ASGI application", stderr_text)
+        self.assertNotIn(
+            "TypeError: 'NoneType' object is not callable",
+            stderr_text,
+        )
+
+    async def _wait_for_listener(self, process, port):
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + 10
+        while loop.time() < deadline:
+            if process.returncode is not None:
+                stderr = ""
+                if process.stderr is not None:
+                    stderr = (await process.stderr.read()).decode(
+                        errors="replace"
+                    )
+                self.fail(
+                    f"SSE server exited before accepting connections:\n{stderr}"
+                )
+            try:
+                _reader, writer = await asyncio.open_connection(
+                    "127.0.0.1",
+                    port,
+                )
+            except OSError:
+                await asyncio.sleep(0.05)
+                continue
+            writer.close()
+            await writer.wait_closed()
+            return
+        self.fail(f"SSE server did not listen on port {port} within 10 seconds")
+
+
 if __name__ == "__main__":
     unittest.main()