logisheets-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,46 +1,65 @@
 # logisheets-mcp
 
-**A real spreadsheet engine your AI agent can think in.**
+**A real spreadsheet engine your agent can think in.** Excel-compatible formulas
+it doesn't have to do in its head, structured memory it addresses by name, and a
+genuine `.xlsx` at the end that a person can open, audit and keep using.
 
-An [MCP](https://modelcontextprotocol.io) server that gives any LLM agent a
-real, Excel-compatible calculation engine — with structured memory it can
-address semantically, and a genuine `.xlsx` at the end that a human can open,
-audit, and keep using.
+An [MCP](https://modelcontextprotocol.io) server over
+[LogiSheets](https://github.com/logisky/LogiSheets), a spreadsheet engine written
+in Rust. MIT, runs on your machine, opens no sockets.
 
-Built on [LogiSheets](https://github.com/logisky/LogiSheets), a spreadsheet
-engine written in Rust. MIT licensed, self-hostable, no cloud dependency.
+---
 
-## Why
+Three things an agent is bad at on a grid, and does not have to do here.
 
-Agents are doing real work that is spreadsheet-shaped — financial models, data
-reconciliation, analysis — and they are bad at exactly the parts a spreadsheet
-engine is good at.
+### It doesn't do the arithmetic
 
-**Arithmetic.** Agents mis-sum and mis-multiply. Here they don't have to: they
-write a formula and a deterministic engine evaluates it.
+```
+set_field_rule   proj.pv = #FIELD("fcf") * #FIELD("df")
+describe_block   proj
+  →  Y1 147.2727   Y2 144.5950   Y3 141.9660   Y4 139.3848   Y5 136.8506
+```
+
+The rule is stated once, **for the field** — not per cell. Five years of it
+materialise, and a sixth computes the moment a row is added, with no formula
+written for it. Writing the same formula N times with the row number adjusted is
+precisely where a model makes a silent mistake.
+
+### It doesn't keep track of where anything is
+
+```
+… the sheet is reshaped: a projected year deleted,
+  two rows inserted at the top, a column at the left …
 
-**Memory.** Across a thirty-step task, intermediate state has to live
-*somewhere* structured. A context window is lossy and expensive; a code
-sandbox's variables vanish. This server gives the agent an external structured
-disk it reads and writes across the whole task.
+describe_block   val
+  →  per_share 19.383943        ← still right, nothing re-derived
+```
+
+Same question, same address, after the shape changed underneath it.
+`SUM(BLOCKREFS("proj","*","pv"))` never referred to a position, so the edit had
+nothing to break. A model that spent its attention on bookkeeping — *did my rows
+shift? is my range still right?* — spends none of it here.
 
-**Addressing.** Agents are bad at spatial reasoning, so a raw grid is a fragile
-surface — they lose track of where things are, and their own edits break their
-references. So the agent doesn't address `C7`. It addresses
-**`(block, row_key, field)`**:
+### It doesn't burn context on round trips
 
-> set the `price` field of the `2025` record in the `revenue` block
+```
+preview_changes  scenarios: WACC × terminal growth, 4 × 4
+  →  16 answers, one call, 950 bytes, nothing written to the workbook
 
-Insert a row, move the block, add a column — that address still resolves. This
-is the whole point: **memory that survives the agent's own edits.**
+goal_seek        per_share = 30, by varying WACC
+  →  0.080699, one call
+```
 
-### vs. a Python sandbox
+A whole sensitivity table and an inverse solve are single questions, asked on a
+temp branch that is discarded. No loop of write-recalculate-read, and no risk of
+leaving a scenario behind in the model.
 
-A code interpreter can compute, but you get a throwaway script result. Here you
-get a real `.xlsx` with **live formulas still in it** — open it in Excel, change
-an input, and the model recalculates. It round-trips the human's existing files,
-and it runs on your machine, which matters when the data can't leave.
+---
 
+**And the file at the end is a real spreadsheet.** Live formulas, not baked
+numbers — open it in Excel, change an input, watch it recompute. Formulas can be
+written out as `BLOCKREF("proj","Y3","pv")` for a person to read, or resolved to
+plain coordinates for Excel to chew on.
 ## Install
 
 Requires Node 20+.
@@ -123,7 +142,7 @@ falls as the list grows, and every description costs context on every turn.
 | `describe_block` | A block's schema, keys, and (optionally) its current values. |
 | `eval_formula` | Evaluate an Excel formula and return the value. Nothing is stored. |
 | `create_block` | Create a named, structured table. First field is the row key. |
-| `convert_to_block` | Turn a table that is already in ordinary cells into a block, in place. |
+| `convert_to_block` | Adopt a table that is already in ordinary cells, in place. Reads the field names off the header row and works out which column is the row key. |
 | `add_block_rows` | Add records — at the end, or `after_key` / `before_key` to place them. |
 | `delete_block_rows` | Remove records. |
 | `move_block_row` | Reorder rows, by key. Presentation only: no computed value changes. |
@@ -213,45 +232,6 @@ Because blocks are created *by the agent as it works*, this needs no
 pre-prepared file — you can point it at a blank workbook or at a spreadsheet
 someone sent you.
 
-## Use as a library
-
-```ts
-import {createServer} from 'logisheets-mcp'
-import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js'
-
-const {server, session} = createServer({mode: 'full'})
-await server.connect(new StreamableHTTPServerTransport(/* … */))
-```
-
-`createServer` returns the MCP `Server`, the `WorkbookSession`, and the tool map,
-so you can host it over any transport or embed it in an agent framework.
-
-## Development
-
-The server is a thin shell over three LogiSheets packages:
-[`logisheets-runtime`](https://www.npmjs.com/package/logisheets-runtime) (the
-headless engine), `logisheets-logician` (the agent tool definitions), and the
-Rust/WASM core. Working on the server alone needs nothing special:
-
-```bash
-git clone https://github.com/logisky/logisheets-mcp.git
-cd logisheets-mcp
-npm install
-npm test
-```
-
-Working on the engine at the same time is the other mode. Check out
-[LogiSheets](https://github.com/logisky/LogiSheets) as a sibling directory,
-build its packages, then:
-
-```bash
-npm run link:local     # re-run after any npm install
-```
-
-That symlinks the three packages into `node_modules` so local engine changes
-take effect without reinstalling. `scripts/release-deps.mjs` puts the registry
-ranges back before publishing.
-
 ## Getting the file back
 
 `save_workbook` writes a real `.xlsx` and its result carries an MCP
@@ -306,6 +286,130 @@ That is the `logisheets-mcp` binary, which is what an MCP host runs. Using it
 [as a library](#use-as-a-library) you can attach any transport you like,
 including an HTTP one — but then the socket is yours, opened deliberately.
 
+## Benchmarks
+
+The claims above are measured, not asserted. The harness is in
+[`bench/`](bench/): tasks written down and committed *before* any other server
+was looked at ([`bench/TASKS.md`](bench/TASKS.md)), every expected value derived
+independently in Python, so you can re-run it and disagree.
+
+Against the two other MCP servers that work on a local `.xlsx` —
+[spreadsheet-kit](https://github.com/PSU3D0/spreadsheet-mcp) 0.11.1, which has
+its own Rust recalc engine, and
+[excel-mcp-server](https://github.com/haris-musa/excel-mcp-server) 0.1.8, the
+most-installed one, on openpyxl:
+
+| | this | spreadsheet-kit | excel-mcp-server |
+| --- | --- | --- | --- |
+| Write a formula, read its value | **30** | **30** | `"=SUM(A1:A2)"` |
+| Five-year DCF, value per share | **20.803603** · 15 calls | **20.803603** · 6 calls | formula text |
+| 4×4 sensitivity, 16 answers | **1 call**, 950 B | 16 calls, 1245 B | can't |
+| Solve backwards for an input | **1 call**, 202 B | 18 calls, 1399 B | can't |
+| Reopen it later and explain it | 4 calls, **2.4 kB** | 5 calls, 21 kB | 2 calls, 24 kB |
+| Answer again after the shape changed | **19.383943** | `#VALUE!` | formula text |
+| Keep a handed-over file's features | **8 of 8** | **8 of 8** | **8 of 8** |
+
+That last row started at 0 of 8. Writing the task is what found it: a defined
+name, an Excel table, the document's own author and timestamps — everything the
+engine has no opinion about — was being dropped on every save, and the file was
+not even loading. An Excel table now also arrives as a block named after the
+table (`BLOCKREF("Sales","south","q1")` on a file nobody prepared), and goes
+back out as a table whose range follows the block it became.
+
+`"=SUM(A1:A2)"` in the third column is not a bug — openpyxl stores formulas
+without evaluating them, so no scenario can be read back and no inverse solve is
+possible. It writes a correct model; it just cannot answer a question about one.
+
+spreadsheet-kit is a genuine peer, correct on everything it can attempt, and
+needed fewer calls than we did to build the model — our extra calls declare a
+schema rather than write cells, which is the trade that pays off in the rows
+below it. It also has forks with undo, branching and checkpoints, and
+LibreOffice-backed screenshots, none of which are here.
+
+One caveat on the reading row: each server was reading back a file *it* wrote,
+so ours had blocks in it because we put them there. Given a plain spreadsheet
+from a person, `convert_to_block` adopts the table first — reading the field
+names off the header row and working out the key column — and then `BLOCKREFS`
+by name works. The individual cell formulas stay in coordinates, so only half of
+that advantage transfers.
+
+Building this turned up defect after defect in our own engine before it said
+anything about anyone else's: a workbook openpyxl wrote failing to load, every
+inline-string label dropped on the way in, adoption freezing the model it
+adopted into static numbers. Every one presented as a wrong answer reported as a
+success — never as a crash — and fuzzing had found none of them.
+
+## Use as a library
+
+```ts
+import {createServer} from 'logisheets-mcp'
+import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+
+const {server, session} = createServer({mode: 'full'})
+await server.connect(new StreamableHTTPServerTransport(/* … */))
+```
+
+`createServer` returns the MCP `Server`, the `WorkbookSession`, and the tool map,
+so you can host it over any transport or embed it in an agent framework.
+
+## Development
+
+The server is a thin shell over three LogiSheets packages:
+[`logisheets-runtime`](https://www.npmjs.com/package/logisheets-runtime) (the
+headless engine), `logisheets-logician` (the agent tool definitions), and the
+Rust/WASM core. Working on the server alone needs nothing special:
+
+```bash
+git clone https://github.com/logisky/logisheets-mcp.git
+cd logisheets-mcp
+npm install
+npm test
+```
+
+Working on the engine at the same time is the other mode. Check out
+[LogiSheets](https://github.com/logisky/LogiSheets) as a sibling directory,
+build its packages, then:
+
+```bash
+npm run link:local     # re-run after any npm install
+```
+
+That symlinks the three packages into `node_modules` so local engine changes
+take effect without reinstalling. `scripts/release-deps.mjs` puts the registry
+ranges back before publishing.
+
+### Releasing
+
+A tag does it. `.github/workflows/publish.yaml` runs the tests, publishes to
+npm with provenance, and registers the new version with the MCP Registry:
+
+```bash
+npm version 0.2.0        # bumps both files, commits, tags v0.2.0
+npm run check-release    # optional; CI runs it too
+git push --follow-tags
+```
+
+The workflow can also be run by hand from the Actions tab, which takes the
+version from `package.json` instead of a tag. The npm step skips a version that
+is already published, so a run that failed at the registry step can just be
+re-run — the two publishes are not a transaction.
+
+`npm version` also rewrites `server.json`, via the `version` lifecycle script.
+The registry keeps the version in two places — the server's own `version` and
+the version of the npm package it points at — and hand-editing them is the step
+most likely to be missed.
+
+`check-release` is the gate. Four things have to agree: the tag, `package.json`,
+and both `server.json` version fields. `mcpName` also has to equal
+`server.json`'s `name`, because the registry proves ownership by reading
+`mcpName` out of the *published* npm package. `npm publish` cannot be undone —
+a version number is spent the moment it lands — so the workflow runs this check
+before publishing, not after.
+
+Registry auth needs no secret: the workflow authenticates with GitHub OIDC,
+which is what grants the `io.github.logisky/` namespace. The one secret is
+`NPM_TOKEN`.
+
 ## License
 
 MIT. Part of the [LogiSheets](https://github.com/logisky/LogiSheets) project.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-mcp",
-    "version": "0.1.0",
+    "version": "0.3.0",
     "description": "An MCP server that gives an AI agent a real, Excel-compatible spreadsheet engine to compute in and remember in — deterministic formulas, structured block memory addressed by (block, key, field), and a real .xlsx out.",
     "mcpName": "io.github.logisky/logisheets-mcp",
     "type": "module",
@@ -23,15 +23,17 @@
         "typecheck": "tsc --noEmit",
         "test": "vitest run",
         "link:local": "node scripts/link-local.mjs",
-        "prepack": "yarn build",
+        "prepack": "npm run build",
         "release:deps": "node scripts/release-deps.mjs",
         "demo": "node examples/revenue-model.mjs",
-        "pretest": "yarn build"
+        "pretest": "npm run build",
+        "check-release": "node scripts/check-release.mjs",
+        "version": "node scripts/sync-server-json.mjs && git add server.json"
     },
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.30.0",
-        "logisheets-logician": "^1.12.0",
-        "logisheets-runtime": "^1.12.0"
+        "logisheets-logician": "^1.13.0",
+        "logisheets-runtime": "^1.13.0"
     },
     "devDependencies": {
         "@types/node": "^22",