PSU3D0/spreadsheet-mcp

**agent-spreadsheet is the tool interaction service for agent-based spreadsheet usage.**
It gives agents a safe, inspectable, token-efficient way to **read, analyze, mutate, verify, and operationalize Excel workbooks** without falling back to brittle UI automation.
If you want an agent to work with spreadsheets like a real system instead of a screenshot puppet, this is the stack.
---
What this project is
agent-spreadsheet ships a unified spreadsheet interaction layer across three surfaces:
| Surface | Binary / Package | Mode | Best for |
| --- | --- | --- | --- |
| **CLI** | agent-spreadsheet / asp | Stateless files + resident sessions | One-shot pipelines or retained multi-turn workbook editing |
| **MCP server** | agent-spreadsheet-mcp | Stateful | Multi-turn agent sessions, workbook caching, fork/recalc workflows |
| **TypeScript SDK** | agent-spreadsheet-sdk | Library | App integrations — drives the server's canonical /v1 route, or runs fully in-process via the embedded WASM engine (no server required) |
The WASM build (agent-spreadsheet-wasm) is the SDK's local runtime, not a separate product surface: JS and TypeScript code targets one object model and the execution substrate (server vs embedded engine) is a configuration choice.
In 0.16 these surfaces share the resident Rust document/evaluator runtime and 32-operation registry. Explicit native sessions automatically start a private journal-backed host. SDK/WASM and genuine just-bash sessions retain their history in memory; XLSX export saves a document snapshot, not a restartable session journal. Warm edit/recalculate/read loops avoid XLSX serialization and repeated evaluator ingestion. See runtime guarantees and limits and the SDK/just-bash examples.
Supported workbook modes:
- .xlsx / .xlsm — read + write
- .xls / .xlsb — discovery/read-oriented workflows only
Powered by Formualizer
Default in-process calculation uses **Formualizer** — a permissively licensed (MIT/Apache-2.0) spreadsheet engine written in Rust: formula parsing, dependency-graph recalculation, 400+ Excel functions, dynamic arrays, and deterministic evaluation built for agents. No Excel COM or headless LibreOffice is required. Optional LibreOffice integration remains available, but Formualizer is the release-critical backend.
That native engine is why this project can offer what most spreadsheet tooling for agents cannot: **recalculate the actual workbook, trace which cells changed and why, and prove it** — not just read cached values or push blind edits.
Embedding spreadsheet logic in your own product rather than driving workbooks as an agent? Use Formualizer directly (Rust, Python, JS/WASM).
---
Why agents use agent-spreadsheet
Built for tool use, not just humans
- deterministic JSON contracts
- schema and example discovery from the CLI itself
- explicit pagination and compact output modes
- machine-readable warnings and error envelopes
Safe mutation, not blind mutation
- dry-run first workflows
- stateless output modes and overwrite safety
- event-sourced session editing
- verification surfaces for proving downstream outcomes
- structural impact analysis before risky workbook changes
Spreadsheet-aware, not generic file editing
- region detection
- table and footer-aware append helpers
- template row / row band cloning
- formula-specific replace and diagnostics
- named range CRUD
- recalculation + diff + proof flows
Good agent ergonomics
- nested command groups with legacy alias compatibility
- token-efficient reads
- exact-cell inspection and layout inspection
- workflow helpers for the repetitive parts agents usually get wrong
---
What is new / what makes this stack different
The current surface is much stronger than a plain “read some cells” tool. Major capabilities now include:
- **asp as the primary CLI** with agent-spreadsheet preserved as a compatibility alias
- **grouped verification** via asp verify proof and asp verify diff
- **preview-first workflow helpers** for:
- write append
- write clone-template-row
- write clone-row-band
- **formula-safe batch workflows** with parse-policy diagnostics
- **cell/layout/export/import inspection surfaces**
- **named range management** (write name define|update|delete)
- **formula-only replacement** (write formulas replace)
- **event-sourced session editing** with log, branch, undo/redo, fork, apply, and materialize
- **SheetPort manifest lifecycle + execution** for contract-driven spreadsheet automation
---
Install
Shell installer