sheetforge-mcp 0.2.1__tar.gz

sheetforge_mcp-0.2.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+excel_files/
+__pycache__/
+.notes/
+*.log

sheetforge_mcp-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Haris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sheetforge_mcp-0.2.1/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: sheetforge-mcp
+Version: 0.2.1
+Summary: SheetForge MCP for reading, writing, and reshaping Excel workbooks
+Author: SheetForge
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<3.0.0,>=2.0.0
+Requires-Dist: mcp[cli]>=1.10.1
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: typer>=0.16.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SheetForge MCP
+
+SheetForge MCP exposes `.xlsx` workbook operations over the Model Context Protocol. It uses `openpyxl` under the hood, so MCP clients can inspect and modify Excel files without launching Microsoft Excel or LibreOffice.
+
+Package name: `sheetforge-mcp`
+CLI command: `sheetforge-mcp`
+
+## What This Project Covers
+
+- workbook creation and metadata
+- worksheet creation, renaming, copying, and deletion
+- structured reads, compact table reads, and cell search
+- row, column, and range mutations
+- formulas and validation checks
+- formatting, merges, and conditional formatting
+- native Excel tables, charts, and pivot summaries
+- `stdio`, `streamable-http`, and deprecated `sse` transports
+
+## Requirements
+
+- Python `3.10+`
+- `.xlsx` workbooks
+- either `uvx` or a local package install
+
+## Quick Start
+
+### Stdio
+
+Use `stdio` when the MCP client starts the server locally.
+
+```bash
+uvx sheetforge-mcp stdio
+```
+
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "command": "uvx",
+      "args": ["sheetforge-mcp", "stdio"]
+    }
+  }
+}
+```
+
+### Streamable HTTP
+
+Use `streamable-http` when you want a long-running local or remote server process.
+
+```bash
+EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp streamable-http
+```
+
+Default endpoint:
+
+```text
+http://127.0.0.1:8017/mcp
+```
+
+Example client config:
+
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "url": "http://127.0.0.1:8017/mcp"
+    }
+  }
+}
+```
+
+### SSE
+
+SSE is kept for compatibility, but new integrations should prefer `streamable-http`.
+
+```bash
+EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp sse
+```
+
+Default endpoint:
+
+```text
+http://127.0.0.1:8017/sse
+```
+
+## File Path Rules
+
+- In `stdio` mode, `filepath` values must be absolute paths.
+- In `streamable-http` and `sse` mode, relative paths are resolved under `EXCEL_FILES_PATH`.
+- Absolute paths are accepted in every transport.
+- In `streamable-http` and `sse` mode, the server creates `EXCEL_FILES_PATH` automatically if it does not exist.
+
+## Environment Variables
+
+| Variable | Default | Used by | Purpose |
+| --- | --- | --- | --- |
+| `FASTMCP_HOST` | `127.0.0.1` | HTTP and SSE | Bind address for the server process |
+| `FASTMCP_PORT` | `8017` | HTTP and SSE | Port for the server process |
+| `EXCEL_FILES_PATH` | `./excel_files` | HTTP and SSE | Base directory for relative workbook paths |
+
+## Tooling Overview
+
+The server currently registers 28 MCP tools across these groups:
+
+- workbook overview: `create_workbook`, `create_worksheet`, `get_workbook_metadata`, `list_all_sheets`
+- data access: `read_data_from_excel`, `read_excel_as_table`, `search_in_sheet`, `write_data_to_excel`
+- worksheet and range changes: `copy_worksheet`, `delete_worksheet`, `rename_worksheet`, `copy_range`, `delete_range`, `insert_rows`, `insert_columns`, `delete_sheet_rows`, `delete_sheet_columns`
+- formatting and layout: `format_range`, `merge_cells`, `unmerge_cells`, `get_merged_cells`
+- formulas and validation: `apply_formula`, `validate_formula_syntax`, `validate_excel_range`, `get_data_validation_info`
+- analysis and structure: `create_table`, `create_chart`, `create_pivot_table`
+
+The three most agent-friendly read tools are:
+
+- `list_all_sheets`: quick workbook inventory with sheet sizes and emptiness flags
+- `read_excel_as_table`: compact `headers + rows` output for structured datasets
+- `search_in_sheet`: exact or partial value search across a worksheet
+
+See [TOOLS.md](TOOLS.md) for the full reference.
+
+## Development
+
+Install dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+Run tests:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+Run the package locally:
+
+```bash
+uv run sheetforge-mcp stdio
+```
+
+## Release Flow
+
+- GitHub releases run a build verification workflow only.
+- PyPI publishing is a separate manual workflow, so releases do not create a failing deployment before Trusted Publisher is configured for the package.
+
+## Repository Layout
+
+- `src/excel_mcp/server.py`: MCP server, transport setup, and tool registration
+- `src/excel_mcp/workbook.py`: workbook lifecycle helpers and workbook metadata
+- `src/excel_mcp/data.py`: read, write, table, and search helpers
+- `src/excel_mcp/sheet.py`: worksheet and range mutations
+- `tests/`: regression tests for workbook handling and public behavior
+- `manifest.json`: packaged MCP bundle metadata
+- `docs/index.html`: static project landing page
+
+## Notes For Integrators
+
+- `stdio` mode is careful not to write non-protocol text to `stdout`.
+- Most read-oriented tools return JSON strings, but a few older tools still return plain string representations for compatibility.
+- `read_data_from_excel(..., preview_only=True)` limits the response to the first 10 rows in the selected range and marks the payload as truncated when applicable.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sheetforge_mcp-0.2.1/README.md

@@ -0,0 +1,163 @@
+# SheetForge MCP
+
+SheetForge MCP exposes `.xlsx` workbook operations over the Model Context Protocol. It uses `openpyxl` under the hood, so MCP clients can inspect and modify Excel files without launching Microsoft Excel or LibreOffice.
+
+Package name: `sheetforge-mcp`
+CLI command: `sheetforge-mcp`
+
+## What This Project Covers
+
+- workbook creation and metadata
+- worksheet creation, renaming, copying, and deletion
+- structured reads, compact table reads, and cell search
+- row, column, and range mutations
+- formulas and validation checks
+- formatting, merges, and conditional formatting
+- native Excel tables, charts, and pivot summaries
+- `stdio`, `streamable-http`, and deprecated `sse` transports
+
+## Requirements
+
+- Python `3.10+`
+- `.xlsx` workbooks
+- either `uvx` or a local package install
+
+## Quick Start
+
+### Stdio
+
+Use `stdio` when the MCP client starts the server locally.
+
+```bash
+uvx sheetforge-mcp stdio
+```
+
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "command": "uvx",
+      "args": ["sheetforge-mcp", "stdio"]
+    }
+  }
+}
+```
+
+### Streamable HTTP
+
+Use `streamable-http` when you want a long-running local or remote server process.
+
+```bash
+EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp streamable-http
+```
+
+Default endpoint:
+
+```text
+http://127.0.0.1:8017/mcp
+```
+
+Example client config:
+
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "url": "http://127.0.0.1:8017/mcp"
+    }
+  }
+}
+```
+
+### SSE
+
+SSE is kept for compatibility, but new integrations should prefer `streamable-http`.
+
+```bash
+EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp sse
+```
+
+Default endpoint:
+
+```text
+http://127.0.0.1:8017/sse
+```
+
+## File Path Rules
+
+- In `stdio` mode, `filepath` values must be absolute paths.
+- In `streamable-http` and `sse` mode, relative paths are resolved under `EXCEL_FILES_PATH`.
+- Absolute paths are accepted in every transport.
+- In `streamable-http` and `sse` mode, the server creates `EXCEL_FILES_PATH` automatically if it does not exist.
+
+## Environment Variables
+
+| Variable | Default | Used by | Purpose |
+| --- | --- | --- | --- |
+| `FASTMCP_HOST` | `127.0.0.1` | HTTP and SSE | Bind address for the server process |
+| `FASTMCP_PORT` | `8017` | HTTP and SSE | Port for the server process |
+| `EXCEL_FILES_PATH` | `./excel_files` | HTTP and SSE | Base directory for relative workbook paths |
+
+## Tooling Overview
+
+The server currently registers 28 MCP tools across these groups:
+
+- workbook overview: `create_workbook`, `create_worksheet`, `get_workbook_metadata`, `list_all_sheets`
+- data access: `read_data_from_excel`, `read_excel_as_table`, `search_in_sheet`, `write_data_to_excel`
+- worksheet and range changes: `copy_worksheet`, `delete_worksheet`, `rename_worksheet`, `copy_range`, `delete_range`, `insert_rows`, `insert_columns`, `delete_sheet_rows`, `delete_sheet_columns`
+- formatting and layout: `format_range`, `merge_cells`, `unmerge_cells`, `get_merged_cells`
+- formulas and validation: `apply_formula`, `validate_formula_syntax`, `validate_excel_range`, `get_data_validation_info`
+- analysis and structure: `create_table`, `create_chart`, `create_pivot_table`
+
+The three most agent-friendly read tools are:
+
+- `list_all_sheets`: quick workbook inventory with sheet sizes and emptiness flags
+- `read_excel_as_table`: compact `headers + rows` output for structured datasets
+- `search_in_sheet`: exact or partial value search across a worksheet
+
+See [TOOLS.md](TOOLS.md) for the full reference.
+
+## Development
+
+Install dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+Run tests:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+Run the package locally:
+
+```bash
+uv run sheetforge-mcp stdio
+```
+
+## Release Flow
+
+- GitHub releases run a build verification workflow only.
+- PyPI publishing is a separate manual workflow, so releases do not create a failing deployment before Trusted Publisher is configured for the package.
+
+## Repository Layout
+
+- `src/excel_mcp/server.py`: MCP server, transport setup, and tool registration
+- `src/excel_mcp/workbook.py`: workbook lifecycle helpers and workbook metadata
+- `src/excel_mcp/data.py`: read, write, table, and search helpers
+- `src/excel_mcp/sheet.py`: worksheet and range mutations
+- `tests/`: regression tests for workbook handling and public behavior
+- `manifest.json`: packaged MCP bundle metadata
+- `docs/index.html`: static project landing page
+
+## Notes For Integrators
+
+- `stdio` mode is careful not to write non-protocol text to `stdout`.
+- Most read-oriented tools return JSON strings, but a few older tools still return plain string representations for compatibility.
+- `read_data_from_excel(..., preview_only=True)` limits the response to the first 10 rows in the selected range and marks the payload as truncated when applicable.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sheetforge_mcp-0.2.1/excel_mcp/__main__.py

@@ -0,0 +1,47 @@
+import sys
+import traceback
+from collections.abc import Callable
+
+import typer
+
+from .server import run_sse, run_stdio, run_streamable_http
+
+app = typer.Typer(help="SheetForge MCP")
+
+
+def _run_server(start_fn: Callable[[], None]) -> None:
+    """Run a server command without writing protocol-breaking output to stdout."""
+    exit_code = 0
+    try:
+        start_fn()
+    except KeyboardInterrupt:
+        typer.echo("Shutting down server...", err=True)
+        exit_code = 130
+    except Exception as e:
+        typer.echo(f"Error: {e}", err=True)
+        traceback.print_exc(file=sys.stderr)
+        exit_code = 1
+    finally:
+        typer.echo("Service stopped.", err=True)
+
+    if exit_code:
+        raise typer.Exit(code=exit_code)
+
+
+@app.command()
+def sse():
+    """Start SheetForge MCP in SSE mode."""
+    _run_server(run_sse)
+
+@app.command()
+def streamable_http():
+    """Start SheetForge MCP in streamable HTTP mode."""
+    _run_server(run_streamable_http)
+
+@app.command()
+def stdio():
+    """Start SheetForge MCP in stdio mode."""
+    _run_server(run_stdio)
+
+if __name__ == "__main__":
+    app()

sheetforge_mcp-0.2.1/excel_mcp/calculations.py

@@ -0,0 +1,55 @@
+from typing import Any
+import logging
+
+from .workbook import safe_workbook
+from .cell_utils import validate_cell_reference
+from .exceptions import ValidationError, CalculationError
+from .validation import validate_formula
+
+logger = logging.getLogger(__name__)
+
+def apply_formula(
+    filepath: str,
+    sheet_name: str,
+    cell: str,
+    formula: str
+) -> dict[str, Any]:
+    """Apply any Excel formula to a cell."""
+    try:
+        if not validate_cell_reference(cell):
+            raise ValidationError(f"Invalid cell reference: {cell}")
+
+        # Ensure formula starts with =
+        if not formula.startswith('='):
+            formula = f'={formula}'
+
+        # Validate formula syntax
+        is_valid, message = validate_formula(formula)
+        if not is_valid:
+            raise CalculationError(f"Invalid formula syntax: {message}")
+
+        with safe_workbook(filepath, save=True) as wb:
+            if sheet_name not in wb.sheetnames:
+                raise ValidationError(f"Sheet '{sheet_name}' not found")
+
+            sheet = wb[sheet_name]
+
+            try:
+                # Apply formula to the cell
+                cell_obj = sheet[cell]
+                cell_obj.value = formula
+            except Exception as e:
+                raise CalculationError(f"Failed to apply formula to cell: {str(e)}")
+
+        return {
+            "message": f"Applied formula '{formula}' to cell {cell}",
+            "cell": cell,
+            "formula": formula
+        }
+
+    except (ValidationError, CalculationError) as e:
+        logger.error(str(e))
+        raise
+    except Exception as e:
+        logger.error(f"Failed to apply formula: {e}")
+        raise CalculationError(str(e))

sheetforge_mcp-0.2.1/excel_mcp/cell_utils.py

@@ -0,0 +1,54 @@
+import re
+
+from openpyxl.utils import column_index_from_string
+
+def parse_cell_range(
+    cell_ref: str,
+    end_ref: str | None = None
+) -> tuple[int, int, int | None, int | None]:
+    """Parse Excel cell reference into row and column indices."""
+    if end_ref:
+        start_cell = cell_ref
+        end_cell = end_ref
+    else:
+        start_cell = cell_ref
+        end_cell = None
+
+    match = re.match(r"([A-Z]+)([0-9]+)", start_cell.upper())
+    if not match:
+        raise ValueError(f"Invalid cell reference: {start_cell}")
+    col_str, row_str = match.groups()
+    start_row = int(row_str)
+    start_col = column_index_from_string(col_str)
+
+    if end_cell:
+        match = re.match(r"([A-Z]+)([0-9]+)", end_cell.upper())
+        if not match:
+            raise ValueError(f"Invalid cell reference: {end_cell}")
+        col_str, row_str = match.groups()
+        end_row = int(row_str)
+        end_col = column_index_from_string(col_str)
+    else:
+        end_row = None
+        end_col = None
+
+    return start_row, start_col, end_row, end_col
+
+def validate_cell_reference(cell_ref: str) -> bool:
+    """Validate Excel cell reference format (e.g., 'A1', 'BC123')"""
+    if not cell_ref:
+        return False
+
+    # Split into column and row parts
+    col = row = ""
+    for c in cell_ref:
+        if c.isalpha():
+            if row:  # Letters after numbers not allowed
+                return False
+            col += c
+        elif c.isdigit():
+            row += c
+        else:
+            return False
+
+    return bool(col and row)