logisheets-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy He
+
+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.

package/README.md

@@ -0,0 +1,311 @@
+# logisheets-mcp
+
+**A real spreadsheet engine your AI agent can think in.**
+
+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.
+
+Built on [LogiSheets](https://github.com/logisky/LogiSheets), a spreadsheet
+engine written in Rust. MIT licensed, self-hostable, no cloud dependency.
+
+## Why
+
+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.
+
+**Arithmetic.** Agents mis-sum and mis-multiply. Here they don't have to: they
+write a formula and a deterministic engine evaluates it.
+
+**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.
+
+**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)`**:
+
+> set the `price` field of the `2025` record in the `revenue` block
+
+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.**
+
+### vs. a Python sandbox
+
+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.
+
+## Install
+
+Requires Node 20+.
+
+```bash
+npm install -g logisheets-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "logisheets": {
+            "command": "npx",
+            "args": ["-y", "logisheets-mcp"]
+        }
+    }
+}
+```
+
+On macOS that file lives at
+`~/Library/Application Support/Claude/claude_desktop_config.json`; on Windows,
+`%APPDATA%\Claude\claude_desktop_config.json`. Restart Claude Desktop
+afterwards.
+
+### Cursor / Cline / other hosts
+
+Any MCP host that can spawn a stdio server works — point it at the
+`logisheets-mcp` command. For Cursor, add the same block to
+`~/.cursor/mcp.json`.
+
+## Try it
+
+> Build me a three-year revenue model: 100 units at $9.50 growing 40% a year,
+> with a 30% cost of goods. Then save it to ~/model.xlsx.
+
+The agent creates a block, fills it, writes the formulas, and hands back a file.
+The numbers are the engine's, not the model's guesses — and the `.xlsx` has real
+formulas in it, so you can change an assumption in Excel and watch it recompute.
+
+## See it work
+
+```bash
+npm run build && npm run demo
+```
+
+Builds a small revenue model over real MCP-on-stdio against `dist/cli.js` — the
+same code path Claude Desktop drives — and checks every claim as it goes: totals
+the engine computed, a rule that reaches rows added later, blocks that keep
+resolving after the model grows underneath them, and a real `.xlsx` whose
+formulas are verified by reading the file's own bytes. No LLM is involved; the
+engine is the subject, and hard-coding the calls is what makes the guarantees
+checkable rather than a story about a chat session.
+
+## The agent loop
+
+```
+list_blocks                     orient: what do I have?
+create_block                    open a structured workspace
+add_block_rows / set_block_cells    fill it, addressed by (block, key, field)
+eval_formula / a stored formula      the engine does the math
+describe_block                  read structured results back
+save_workbook                   hand the human a real .xlsx
+```
+
+## Tools
+
+The default surface is deliberately small — 20 tools. Tool-selection accuracy
+falls as the list grows, and every description costs context on every turn.
+
+| Tool | What it does |
+| --- | --- |
+| `open_workbook` | Start a fresh workbook, or load an existing `.xlsx` from disk. Optional — one appears on first use. |
+| `save_workbook` | Write to a real `.xlsx` file. This is how work gets handed back. |
+| `export_xlsx` | The file as base64, for hosts with no shared filesystem. |
+| `list_blocks` | Every sheet and block, plus where the next block should go. |
+| `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. |
+| `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. |
+| `set_block_cells` | Write cells by `(block, row_key, field)`. Batched, atomic. |
+| `set_field_rule` | Give a field a formula, a validation rule, or an editability rule. |
+| `list_violations` | Which cells break their field's validation rule, and why. |
+| `preview_changes` | What edits *would* do, without doing them. One hypothetical, or a whole grid of scenarios in a single call. |
+| `trace` | What a cell reads, and what reads it — from the engine's dependency graph. |
+| `goal_seek` | What input makes a chosen output equal a target. Searches inside the engine; changes nothing. |
+| `create_sheet` | Add a sheet. |
+| `get_cells` / `set_cells` | Raw-cell escape hatch for data with no structure. |
+
+Formulas are Excel-compatible, plus `BLOCKREF(block, key, field)` for reading a
+block cell semantically. Inside a field rule, `#FIELD("name")` is the same row's
+sibling and `#FIELD("name", "key")` is another row of the same block — the one
+carrying that key, never a positional offset, so reordering rows cannot change
+what a formula means.
+
+### Analysing a model, not just building one
+
+`preview_changes` takes a list of `scenarios` and an optional `watch`, which is
+what turns exploration from dozens of round trips into one:
+
+```jsonc
+{
+  "scenarios": [
+    {"label": "wacc 9%",  "changes": [{"block":"assum","row_key":"wacc","field":"v","value":0.09}]},
+    {"label": "wacc 12%", "changes": [{"block":"assum","row_key":"wacc","field":"v","value":0.12}]}
+  ],
+  "watch": [{"block":"valuation","row_key":"per_share","field":"v"}]
+}
+```
+
+Each scenario runs on its own temp branch and is discarded, so the live model is
+never touched — no mutate-and-revert, and nothing left behind if a scan fails
+half way. A 4×4 sensitivity grid is one call returning sixteen numbers.
+
+`goal_seek` runs the same trick backwards — "what discount rate gives a value per
+share of 30" — with the search inside the engine rather than as a conversation,
+so it is one call instead of one per bisection step. It says when a target is
+simply not reachable in the bracket instead of returning the nearest number it
+happened to stop on.
+
+`trace` answers the two audit questions from the engine's dependency graph:
+what a cell reads, and what reads it. The second one is why it exists — formula
+text can be read forwards but not backwards, and "what breaks if I change this"
+is the question you want before touching an assumption.
+
+Reading a model is semantic too: `describe_block` returns each field's rule, so
+an agent learns the model's logic without visiting a cell, and formulas come back
+naming what they read (`B24 / BLOCKREF("assum","shares","v")`) rather than as
+coordinate chains you have to chase.
+
+### The full surface
+
+Set `LOGISHEETS_MCP_TOOLS=full` for 50 tools: undo/redo, cell formatting,
+merges, comments, checkpoints, block move/resize, cross-block links, and raw
+row/column structure.
+
+```json
+{
+    "mcpServers": {
+        "logisheets": {
+            "command": "npx",
+            "args": ["-y", "logisheets-mcp"],
+            "env": {"LOGISHEETS_MCP_TOOLS": "full"}
+        }
+    }
+}
+```
+
+Mutating tools are marked with MCP's `readOnlyHint` / `destructiveHint`
+annotations, so a host can gate them behind user approval.
+
+## Blocks, briefly
+
+A **block** is a named, structured region of a sheet — a table with a schema.
+
+- The first field is the **row key**: the stable name of each record.
+- Fields can carry a **value formula** (engine-computed, so the agent can't
+  write a stale number into it), a **validation** rule, or an **editability**
+  rule.
+- Everything is addressed by name. Row and column indices never enter the
+  agent's reasoning.
+
+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
+**resource link** — a uri, media type and size — not the file. The workbook is
+also listed as a resource (`workbook://current.xlsx`), so a host that wants the
+bytes reads them with `resources/read` and hands the human a download.
+
+That split is the point: a tool result goes into the model's context, where a
+200 KB workbook would cost roughly 280 KB of text and teach the model nothing.
+The link costs a line. `export_xlsx` still returns base64 for hosts that
+implement no resources at all, but it is the fallback, not the mechanism.
+
+Reads go through the same serialization lane as tool calls, so a host fetching
+the file can never catch a half-applied transaction.
+
+`open_workbook` and `save_workbook` read and write wherever the server process
+can — normal for a local stdio server, and the same posture as the official
+filesystem server. Both are marked as mutating so a host can prompt before they
+run; if you need tighter limits, run the server as a user with only the access
+you intend it to have.
+
+## State model
+
+One MCP session holds one active workbook, alive across tool calls — that
+persistence is what makes it memory rather than a calculator. `open_workbook`
+replaces it. Multiple named workbooks per session may come later.
+
+## No network
+
+The server opens no sockets and listens on no ports. "stdio transport" is
+literal: your MCP host spawns this as a child process and they exchange
+newline-delimited JSON-RPC over its stdin and stdout — the same pipes any
+command-line program gets. The engine is WASM running in that same process,
+so a formula is a function call, not a request.
+
+Checked rather than asserted. After a full session — create a block, attach a
+field rule, evaluate a formula, save an `.xlsx` — the process holds:
+
+```
+fd types: {CHR: 2, DIR: 4, KQUEUE: 3, PIPE: 6, REG: 13}
+network files (lsof -a -i):     0
+unix sockets  (lsof -a -U):     0
+listening ports:                0
+```
+
+Six pipes, no sockets. Nothing is uploaded, no telemetry is collected, and an
+air-gapped machine is a supported way to run this. The only things it touches
+outside its own memory are the files you name — see the filesystem note under
+[Getting the file back](#getting-the-file-back).
+
+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.
+
+## License
+
+MIT. Part of the [LogiSheets](https://github.com/logisky/LogiSheets) project.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * stdio entry point — what an MCP host (Claude Desktop, Cursor, Cline) spawns.
+ *
+ * stdout is the JSON-RPC channel and must carry nothing else, so every
+ * diagnostic in this process goes to stderr.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * stdio entry point — what an MCP host (Claude Desktop, Cursor, Cline) spawns.
+ *
+ * stdout is the JSON-RPC channel and must carry nothing else, so every
+ * diagnostic in this process goes to stderr.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer, SERVER_VERSION } from './server.js';
+import { toolModeFromEnv } from './surface.js';
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stderr.write([
+            'logisheets-mcp — a real spreadsheet engine as an MCP server (stdio).',
+            '',
+            'Environment:',
+            '  LOGISHEETS_MCP_TOOLS=core|full   tool surface (default: core)',
+            '',
+            'Configure your MCP host to run this command; it speaks MCP on stdio,',
+            'not something you interact with directly in a terminal.',
+            '',
+        ].join('\n'));
+        return;
+    }
+    if (argv.includes('--version') || argv.includes('-v')) {
+        process.stderr.write(`${SERVER_VERSION}\n`);
+        return;
+    }
+    const { server, session, tools } = createServer();
+    process.stderr.write(`logisheets-mcp ${SERVER_VERSION}: ${tools.size} tools (${toolModeFromEnv()} surface)\n`);
+    const shutdown = () => {
+        session.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    process.stderr.write(`logisheets-mcp failed to start: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * logisheets-mcp — a real, Excel-compatible spreadsheet engine as an MCP server.
+ *
+ * Library entry point, for embedding the server in another host (an HTTP
+ * transport, an agent framework, a test). The stdio binary lives in ./cli.ts.
+ */
+export { createServer, INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, type CreatedServer, type CreateServerOptions, } from './server.js';
+export { selectTools, toolModeFromEnv, type ToolMode, } from './surface.js';
+export { WorkbookSession, type OpenResult, type SaveResult, type WorkbookClient, } from './session.js';
+export { createLifecycleTools, type OpenWorkbookInput } from './lifecycle.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * logisheets-mcp — a real, Excel-compatible spreadsheet engine as an MCP server.
+ *
+ * Library entry point, for embedding the server in another host (an HTTP
+ * transport, an agent framework, a test). The stdio binary lives in ./cli.ts.
+ */
+export { createServer, INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, } from './server.js';
+export { selectTools, toolModeFromEnv, } from './surface.js';
+export { WorkbookSession, } from './session.js';
+export { createLifecycleTools } from './lifecycle.js';

package/dist/lifecycle.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Workbook lifecycle tools — the one part of the surface logician doesn't
+ * already provide.
+ *
+ * logician's tools operate on an *open* workbook (it was written for the
+ * in-app assistant, where the host owns the file). A standalone MCP server has
+ * to own opening and handing back the file itself, so those three tools live
+ * here. They are ordinary logician `Tool`s that close over the session, which
+ * means the MCP adapter treats them identically to every engine tool.
+ *
+ * File paths are the primary interface: this server runs next to the agent, and
+ * a `.xlsx` round-tripped through base64 would cost tens of thousands of tokens
+ * in the model's context for no benefit. base64 stays available for hosts with
+ * no shared filesystem.
+ */
+import type { Tool } from 'logisheets-logician';
+import type { WorkbookSession } from './session.js';
+/**
+ * The active workbook, addressable as an MCP resource.
+ *
+ * A tool result goes into the model's context, so returning the file itself
+ * there costs roughly 1.4 KB of text per KB of workbook and teaches the model
+ * nothing. The protocol's answer is a resource: the tool returns a *link* — uri,
+ * mime type, size — and a host that wants the bytes fetches them with
+ * `resources/read`, outside the conversation. That is how the workbook gets
+ * handed back without the model paying for it.
+ */
+export declare const WORKBOOK_URI = "workbook://current.xlsx";
+/** The OOXML spreadsheet media type, as Excel and every host expect it. */
+export declare const XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+/**
+ * Tools whose result should carry a link to the workbook, so the host can offer
+ * the finished file to the human.
+ */
+export declare const TOOLS_YIELDING_WORKBOOK: ReadonlySet<string>;
+export interface OpenWorkbookInput {
+    path?: string;
+    xlsx_base64?: string;
+    name?: string;
+}
+/** The lifecycle tools, bound to one session. */
+export declare function createLifecycleTools(session: WorkbookSession): Tool[];

package/dist/lifecycle.js

@@ -0,0 +1,156 @@
+/**
+ * Workbook lifecycle tools — the one part of the surface logician doesn't
+ * already provide.
+ *
+ * logician's tools operate on an *open* workbook (it was written for the
+ * in-app assistant, where the host owns the file). A standalone MCP server has
+ * to own opening and handing back the file itself, so those three tools live
+ * here. They are ordinary logician `Tool`s that close over the session, which
+ * means the MCP adapter treats them identically to every engine tool.
+ *
+ * File paths are the primary interface: this server runs next to the agent, and
+ * a `.xlsx` round-tripped through base64 would cost tens of thousands of tokens
+ * in the model's context for no benefit. base64 stays available for hosts with
+ * no shared filesystem.
+ */
+/**
+ * The active workbook, addressable as an MCP resource.
+ *
+ * A tool result goes into the model's context, so returning the file itself
+ * there costs roughly 1.4 KB of text per KB of workbook and teaches the model
+ * nothing. The protocol's answer is a resource: the tool returns a *link* — uri,
+ * mime type, size — and a host that wants the bytes fetches them with
+ * `resources/read`, outside the conversation. That is how the workbook gets
+ * handed back without the model paying for it.
+ */
+export const WORKBOOK_URI = 'workbook://current.xlsx';
+/** The OOXML spreadsheet media type, as Excel and every host expect it. */
+export const XLSX_MIME = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+/**
+ * Tools whose result should carry a link to the workbook, so the host can offer
+ * the finished file to the human.
+ */
+export const TOOLS_YIELDING_WORKBOOK = new Set([
+    'save_workbook',
+]);
+function openWorkbook(session) {
+    return {
+        namespace: 'workbook',
+        name: 'open_workbook',
+        description: [
+            'Start the workbook you will work in. Call with no arguments for a fresh, empty one; pass `path` to load an existing .xlsx from disk and work on the human\'s real file.',
+            '',
+            'This replaces whatever workbook the session currently holds, discarding unsaved changes — so call it once at the start, not between steps. You do NOT have to call it at all: an empty workbook appears automatically the moment any other tool touches the session.',
+            '',
+            'Prefer `path` over `xlsx_base64`. `xlsx_base64` exists for hosts with no shared filesystem and costs enormous context for a file of any size.',
+        ].join('\n'),
+        mutates: true,
+        confirmation: 'always',
+        inputSchema: {
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to an existing .xlsx to load. Omit for an empty workbook.',
+                },
+                xlsx_base64: {
+                    type: 'string',
+                    description: 'A .xlsx as base64, for when no shared filesystem exists. Use `path` when you can.',
+                },
+                name: {
+                    type: 'string',
+                    description: 'File name to report to the engine when loading from base64.',
+                },
+            },
+        },
+        handler: async (input) => {
+            const result = await session.open({
+                path: input.path,
+                xlsxBase64: input.xlsx_base64,
+                name: input.name,
+            });
+            const where = result.path !== undefined
+                ? ` from ${result.path}`
+                : result.source === 'bytes'
+                    ? ' from uploaded bytes'
+                    : '';
+            return {
+                data: result,
+                display: `Opened ${result.source} workbook${where}: ${result.sheets.length} sheet(s) — ${result.sheets.join(', ')}`,
+            };
+        },
+    };
+}
+function saveWorkbook(session) {
+    return {
+        namespace: 'workbook',
+        name: 'save_workbook',
+        description: [
+            'Write the workbook to a real .xlsx file the human can open in Excel. This is how you hand your work back — do it when the task is done.',
+            '',
+            'Defaults to the path it was opened from, or last saved to; pass `path` to write somewhere else. Values, formulas and the block structure are all saved.',
+            '',
+            'IMPORTANT — if the human is going to work on this in Excel, pass `resolve_block_refs: true`. Formulas that read blocks are written as BLOCKREF/BLOCKREFS, which only LogiSheets understands: Excel shows the saved numbers but turns those cells into #NAME? the moment it recalculates. Resolving rewrites them as ordinary A1 references so Excel can recompute the model. Leave it off when the file is coming back here — the named form is readable and survives rows moving.',
+            '',
+            'The result carries a link to the workbook rather than its bytes, so the host can offer the human the file without any of it passing through your context.',
+        ].join('\n'),
+        // Writes to the filesystem: not a workbook mutation, but very much an
+        // effect on the world, so hosts should gate it.
+        mutates: true,
+        confirmation: 'always',
+        inputSchema: {
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Destination .xlsx path. Defaults to the path the workbook was opened from.',
+                },
+                resolve_block_refs: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Rewrite BLOCKREF/BLOCKREFS as ordinary A1 references. Set this when the human will open the file in Excel; Excel has no BLOCKREF function and would show #NAME? on recalculation. One-way: a resolved file is an export, not a round trip.',
+                },
+            },
+        },
+        handler: async (input) => {
+            const result = await session.saveTo(input.path, {
+                resolveBlockRefs: input.resolve_block_refs === true,
+            });
+            return {
+                data: result,
+                display: `Saved ${result.bytes} bytes to ${result.path}` +
+                    (input.resolve_block_refs === true
+                        ? ' (block formulas resolved to A1 — Excel can recalculate it)'
+                        : ''),
+            };
+        },
+    };
+}
+function exportXlsx(session) {
+    return {
+        namespace: 'workbook',
+        name: 'export_xlsx',
+        description: [
+            'Return the workbook as base64-encoded .xlsx bytes.',
+            '',
+            'Last resort. The bytes land in your context and cost roughly 1.4 KB of text per KB of file. Prefer `save_workbook`, which writes a real file and hands the host a link to it — the host can give the human the workbook without any of it passing through you.',
+        ].join('\n'),
+        mutates: false,
+        confirmation: 'never',
+        cost: 'expensive',
+        inputSchema: { properties: {} },
+        handler: async () => {
+            const result = session.exportBase64();
+            return {
+                data: result,
+                display: `Exported ${result.bytes} bytes as base64`,
+            };
+        },
+    };
+}
+/** The lifecycle tools, bound to one session. */
+export function createLifecycleTools(session) {
+    return [
+        openWorkbook(session),
+        saveWorkbook(session),
+        exportXlsx(session),
+    ];
+}

package/dist/server.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The MCP shell: logician tools in, MCP protocol out.
+ *
+ * We use the SDK's low-level `Server` rather than `McpServer` on purpose.
+ * `McpServer.registerTool` wants Zod schemas, while logician tools already
+ * carry hand-written JSON Schema — which is what MCP puts on the wire anyway.
+ * Going low-level passes those straight through instead of round-tripping them
+ * through a Zod translation layer.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Tool } from 'logisheets-logician';
+import { WorkbookSession } from './session.js';
+import { type ToolMode } from './surface.js';
+export declare const SERVER_NAME = "logisheets";
+export declare const SERVER_VERSION = "0.1.0";
+/**
+ * How the agent should approach this server. Sent as MCP `instructions`, so a
+ * host can put it in front of the model before it starts guessing.
+ */
+export declare const INSTRUCTIONS: string;
+export interface CreateServerOptions {
+    /** Reuse an existing session (tests, embedding). Defaults to a fresh one. */
+    session?: WorkbookSession;
+    /** Override the tool surface; defaults to `LOGISHEETS_MCP_TOOLS` or `core`. */
+    mode?: ToolMode;
+    /**
+     * Where tool progress lines go. Defaults to stderr — on the stdio
+     * transport, stdout carries JSON-RPC frames and writing anything else
+     * there corrupts the stream.
+     */
+    log?: (msg: string) => void;
+}
+export interface CreatedServer {
+    server: Server;
+    session: WorkbookSession;
+    /** The tools exposed, by MCP name. */
+    tools: Map<string, Tool>;
+}
+/**
+ * Build the server. Nothing is started — hand the result to a transport.
+ */
+export declare function createServer(opts?: CreateServerOptions): CreatedServer;