ExcelTamer 0.2.0__py3-none-any.whl

exceltamer-0.2.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: ExcelTamer
+Version: 0.2.0
+Summary: A Model Context Protocol server for safe Microsoft Excel automation
+Author: Shamit
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/shamitv/ExcelTamer
+Project-URL: Bug Tracker, https://github.com/shamitv/ExcelTamer/issues
+Project-URL: Documentation, https://github.com/shamitv/ExcelTamer/blob/main/docs/mcp_server.md
+Project-URL: Repository, https://github.com/shamitv/ExcelTamer
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xlwings~=0.36.10
+Requires-Dist: pandas~=3.0.5
+Requires-Dist: mcp~=1.28.1
+Dynamic: license-file
+
+# ExcelTamer
+
+ExcelTamer is a Model Context Protocol (MCP) server for safe, structured
+automation of Microsoft Excel. It exposes workbook lifecycle, reading, writing,
+search, checkpoint, resource, and prompt capabilities to any MCP-compatible
+client.
+
+**New to ExcelTamer?** Follow the [quick start](#quick-start-use-exceltamer-with-an-mcp-client)
+below or read the
+[complete MCP usage guide](https://github.com/shamitv/ExcelTamer/blob/main/docs/mcp_server.md).
+
+## Quick start: use ExcelTamer with an MCP client
+
+### 1. Install ExcelTamer
+
+ExcelTamer requires Windows with Microsoft Excel installed and Python 3.11 or
+newer.
+
+```powershell
+pip install .
+```
+
+### 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:
+
+```json
+{
+  "mcpServers": {
+    "exceltamer": {
+      "command": "exceltamer-mcp",
+      "env": {
+        "EXCELTAMER_MCP_ALLOWED_ROOTS": "C:\\Users\\you\\Documents\\Excel"
+      }
+    }
+  }
+}
+```
+
+`EXCELTAMER_MCP_ALLOWED_ROOTS` limits which workbook paths the server may
+access. The server defaults to read-only workbook mode and records write
+operations in an audit log.
+
+### 3. Restart the client and ask it to use Excel
+
+For inspection, try:
+
+```text
+Open C:\Users\you\Documents\Excel\budget.xlsx in read-only mode. List the
+worksheets, preview the first 10 rows of the first sheet, summarize what the
+workbook contains, and close it when finished.
+```
+
+For a safe edit, try:
+
+```text
+Open C:\Users\you\Documents\Excel\budget.xlsx in read-write mode. Create a
+checkpoint, update cell B4 on Sheet1 to 120, read the cell back to verify the
+change, save the workbook, and close it. If verification fails, roll back to
+the checkpoint.
+```
+
+Your MCP client handles the `excel.*` tool calls and carries the returned
+`workbook_id` through the workflow.
+
+## Run the server manually
+
+Start the default stdio transport:
+
+```powershell
+exceltamer-mcp
+```
+
+The module form remains available:
+
+```powershell
+python -m ExcelTamer.mcp.main
+```
+
+For SSE transport:
+
+```powershell
+exceltamer-mcp --port 8123
+```
+
+### Command-line options
+
+```text
+exceltamer-mcp [-h] [--port PORT]
+```
+
+| Option | Description |
+| --- | --- |
+| `-h`, `--help` | Show the command help and exit |
+| `--port PORT` | Run the SSE transport on the specified integer port |
+
+When `--port` is omitted, the server uses stdio transport. The module form
+accepts the same options:
+
+```powershell
+python -m ExcelTamer.mcp.main --port 8123
+```
+
+### Environment variables
+
+ExcelTamer reads these variables when the server process starts. Restart the
+server or MCP client after changing them.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `EXCELTAMER_MCP_ALLOWED_ROOTS` | Current working directory | Comma-separated directory roots from which workbook paths may be opened |
+| `EXCELTAMER_MCP_DEFAULT_MODE` | `ro` | Default workbook mode: `ro` for read-only or `rw` for read-write |
+| `EXCELTAMER_MCP_MAX_CELLS_READ` | `20000` | Maximum number of cells considered by one read operation |
+| `EXCELTAMER_MCP_MAX_CELLS_WRITE` | `5000` | Maximum number of cells accepted by one write operation |
+| `EXCELTAMER_MCP_AUDIT_LOG_DIR` | `./.exceltamer_mcp_logs` | Directory in which write audit records are stored as `audit.jsonl` |
+
+Set these values in the MCP client configuration's `env` object, as shown in
+the quick start, or in the shell before starting `exceltamer-mcp`.
+
+## Capabilities
+
+- Open, inspect, save, save-as, and close workbooks
+- Read cells, ranges, sheet previews, and workbook structure
+- Write cells, batches, and rectangular ranges
+- Search workbook values with exact, contains, or regex matching
+- Create and roll back checkpoints
+- Inspect recent write history
+- Discover workbook resources and MCP-native workflow prompts
+
+## Validation
+
+Run the automated MCP smoke tests:
+
+```powershell
+python -m unittest discover -s test -p "test_*.py" -v
+```
+
+Run the standalone protocol client:
+
+```powershell
+python test/mcp_client.py
+```
+
+Pass `--file path\to\workbook.xlsx` to additionally validate opening,
+inspecting, and closing a real workbook.

exceltamer-0.2.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+ExcelTamer/__init__.py,sha256=8qU_pcwHowLrWWjYas-X1nQCgKH17WCzjzRJgXlehPQ,37
+ExcelTamer/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ExcelTamer/mcp/audit.py,sha256=jYf7bSxcONODhmoBFB5AEI67YX3Etey0nn3SkoWjCUU,1183
+ExcelTamer/mcp/config.py,sha256=OFaPhy8gZU4wLC6vcen8qV8L3R8fQ8KCFZnC-KyDpf0,838
+ExcelTamer/mcp/excel.py,sha256=Vay6lMcqSriRLzs3Ze3OlPet6W--y3CB_YBuw3TBiYA,3842
+ExcelTamer/mcp/main.py,sha256=SKlDjeWr0HT7C4OvxAZSwf0j5sNoT2RzCwyZy54byKg,451
+ExcelTamer/mcp/safety.py,sha256=49bPfqZ2ZZ6G5kYXVw2uMjdNpNi0haxqoBMDG7-oYT8,1250
+ExcelTamer/mcp/server.py,sha256=t4BPV50ot32SLhR5UManYgN6XdH9CU8WoeFLtglkSoM,21020
+ExcelTamer/mcp/sessions.py,sha256=pu_I5dyANF4VQE2V_AsLfFh4nv6JWJd8uwH9vARdbew,983
+ExcelTamer/mcp/engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ExcelTamer/mcp/engine/diff.py,sha256=VlrslvIMyQyHe24BMCQ2SzArg2jv2_ZSIvlE4hWMjtA,4810
+ExcelTamer/mcp/engine/read.py,sha256=UJz6FF8womugGePJ0rPyNcftg51ZL_0FoHjUeHLjJqI,4224
+ExcelTamer/mcp/engine/search.py,sha256=IWH-s8UygImJiHavZFHmx2XktOmpLiNkegye8MVB7_8,4135
+ExcelTamer/mcp/engine/workbook.py,sha256=5JvfJ5N7kqNalgwyc_IlLM7x9lXd2A90ACnQeCChWxE,2101
+ExcelTamer/mcp/engine/write.py,sha256=ueRHDjn-VXsm_uVghav4vNutEV957f5K_oD0J5tnjGo,3275
+ExcelTamer/mcp/prompts/README.md,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ExcelTamer/mcp/prompts/financial_metric_extract.md,sha256=QuvwgTU42Z9gdLsfyraxRcbzH4hq5mwZA7bcO5zhJ1Y,1011
+ExcelTamer/mcp/prompts/safe_edit.md,sha256=VMZ8ugoJuKWGTu0CcI_c2o_qOs3xppHcAidDfhZDhPc,1142
+ExcelTamer/mcp/schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exceltamer-0.2.0.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+exceltamer-0.2.0.dist-info/METADATA,sha256=xHvlcJrYIkC6ei-IsgXOeuc2DtVInZvPDWURpV8ZaqU,5313
+exceltamer-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+exceltamer-0.2.0.dist-info/entry_points.txt,sha256=ddNwWBE1QS-ijYbhKNP9cZFWMLTHJE_LsSEkaQd8Ztk,60
+exceltamer-0.2.0.dist-info/top_level.txt,sha256=vy92OVLvfH2ddH0I9HV-NJZU0YJY6o_yyr0uHrNohyY,11
+exceltamer-0.2.0.dist-info/RECORD,,

exceltamer-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

exceltamer-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+exceltamer-mcp = ExcelTamer.mcp.main:main