Workbook tools for agent frameworks

June 5, 2026 · View on GitHub

Use this page when an agent, assistant, or tool host needs spreadsheet formulas but should not drive Excel through screenshots. Pick the smallest integration boundary that can write inputs, recalculate formulas, verify readback, and persist WorkPaper JSON.

Decision

Use @bilig/workpaper when the workbook model can live in a Node service, agent tool, route handler, or MCP server. The tool contract is explicit:

read the relevant sheet or range;
write the requested input cell;
read the dependent calculated value;
export or serialize the WorkPaper document;
restore it when a file boundary matters;
return editedCell, before, after, afterRestore, persistedDocumentBytes, verified, and limitations.

Use @bilig/workbook when a framework integration needs a transport-neutral command, check, and proof model while an existing runtime owns calculation.

Use @bilig/xlsx-formula-recalc, @bilig/sheetjs-formula-recalc, or @bilig/exceljs-formula-recalc when the product already owns an .xlsx, SheetJS, or ExcelJS file pipeline and only needs fresh formula results before returning the file.

Keep browser or desktop spreadsheet automation only when the visual surface is the product: manual review, macros, pivots, charts, add-ins, or layout fidelity.

Start here

For a coding agent that only needs the shortest no-key path, use the Agent Adoption Kit:

npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

For a generated project with agent files and MCP config:

npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify

For a direct package proof without creating a project:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json

For MCP clients:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable

Framework map

Host	Use	Link
Codex	Local stdio MCP server or direct package import in repo tools.	MCP client setup
Claude Code and Claude Desktop	File-backed MCP server, or MCPB when a desktop extension is easier.	Claude MCPB guide
Cursor	Project-local `.cursor/mcp.json` pointing at `bilig-workpaper-mcp`.	MCP client setup
Kiro	Project `.kiro/steering/bilig-workpaper.md` plus `.kiro/settings/mcp.json` for the file-backed WorkPaper MCP server.	Coding agent rule chooser
Roo Code	Project `.roo/rules/bilig-workpaper.md` plus `.roo/mcp.json` for the file-backed WorkPaper MCP server.	Coding agent rule chooser
Trae	Project `.trae/rules/bilig-workpaper.md` plus `.trae/mcp.json` Project MCP for the file-backed WorkPaper MCP server.	Trae WorkPaper MCP setup
Qodo IDE	Qodo Agentic Tools MCP JSON for the file-backed WorkPaper MCP server, with root `AGENTS.md` as the project policy.	Qodo WorkPaper MCP setup
Zed	Project `.zed/settings.json` `context_servers.bilig-workpaper` plus `AGENTS.md` and `.agents/skills/bilig-workpaper/SKILL.md`.	MCP client setup
JetBrains Junie	Project-local `.junie/mcp/mcp.json` using the file-backed WorkPaper MCP server, with `AGENTS.md` for the shared workbook proof rule.	Coding agent rule chooser
VS Code and Cline	Project-local MCP config with a writable WorkPaper file.	MCP client setup
OpenHands	`AGENTS.md`, `.agents/skills/bilig-workpaper/SKILL.md`, and `openhands mcp add` for a file-backed stdio WorkPaper server.	OpenHands WorkPaper MCP setup
OpenCode	`opencode.jsonc` for local MCP plus `.opencode/agents/bilig-workpaper.md` for a readback-first workbook subagent.	OpenCode WorkPaper MCP setup
Aider	`CONVENTIONS.md` loaded by `.aider.conf.yml`, with WorkPaper readback and persistence proof before workbook success claims.	Aider WorkPaper conventions
Goose	`examples/goose-workpaper-mcp/recipe.yaml` launching a local file-backed stdio WorkPaper MCP server, with hosted Streamable HTTP only for stateless smoke.	Goose WorkPaper MCP recipe
Open WebUI	Hosted OpenAPI for no-bridge smoke tests, native Streamable HTTP MCP, or `mcpo` around the npm stdio server for local writable files.	Open WebUI WorkPaper setup
LobeHub	Custom MCP import JSON for hosted Streamable HTTP, or desktop STDIO for a writable WorkPaper file.	LobeHub WorkPaper MCP setup
AnythingLLM	`anythingllm_mcp_servers.json` with hosted Streamable HTTP, Desktop stdio, or Docker storage-backed stdio.	AnythingLLM WorkPaper MCP setup
Browser Use	Browser agent gathers web context; custom Bilig tool or file-backed MCP owns formula readback and WorkPaper persistence.	Browser Use WorkPaper formula tool
OpenAI Agents SDK	Function tools, `MCPServerStdio`, or hosted `MCPServerStreamableHttp` with computed WorkPaper readback.	OpenAI Agents SDK WorkPaper tool
ChatGPT Apps / Developer Mode	Remote MCP app using the hosted Streamable HTTP endpoint for no-key WorkPaper readback proof.	ChatGPT Apps WorkPaper MCP
OpenAI Responses API	Function-call wrapper returning proof objects.	OpenAI Responses WorkPaper tool call
Vercel AI SDK	Tool definitions that call a WorkPaper service function.	Vercel AI SDK spreadsheet tools
LangChain.js	Tool wrappers around the same WorkPaper contract.	Vercel AI SDK and LangChain spreadsheet tools
LangGraph.js	`ToolNode` with verified readback after mutation.	LangGraph WorkPaper ToolNode
LlamaIndex.TS	`tool(fn, { parameters })` with a compact proof return.	LlamaIndex.TS WorkPaper tool
Open Multi-Agent	`connectMCPTools()` with the file-backed WorkPaper MCP server registered on an `Agent`.	Open Multi-Agent WorkPaper MCP example
Agno	`MCPTools` with the file-backed WorkPaper MCP server and explicit readback checks.	Agno WorkPaper MCP tools
Pydantic AI	`MCPToolset` with typed proof validation before an agent trusts workbook calculations.	Pydantic AI WorkPaper MCP tools
Google ADK	`McpToolset` with file-backed stdio WorkPaper tools and explicit formula readback proof.	Google ADK WorkPaper MCP tools
Microsoft Agent Framework	`MCPStdioTool` or `MCPStreamableHTTPTool` with file-backed or hosted WorkPaper tools; .NET hosts can convert MCP tools to `AITool`.	Microsoft Agent Framework WorkPaper MCP tools
Mastra	Real `@mastra/core` `createTool()` smoke for formula-backed workbook edits.	Mastra WorkPaper tool
Cloudflare Agents	Agent tool calling a Node-compatible WorkPaper boundary.	Cloudflare Agents WorkPaper tool
Runtime adapter authors	`@bilig/workbook` models, plan data, checks, schemas, command receipts, and strict proof.	Workbook agent intent API
MCP directories and remote clients	Hosted server card or local file-backed server.	MCP WorkPaper server

Proof object

Every agent integration should return a small object like this instead of a generic "cell updated" message:

type SpreadsheetAgentProof = {
  editedCell: { sheet: string; cell: string; value: unknown }
  before: { cell: string; displayValue: string }
  after: { cell: string; displayValue: string }
  afterRestore: { cell: string; displayValue: string }
  persistedDocumentBytes: number
  verified: boolean
  limitations: string[]
}

verified is true only when the dependent formula output changed as expected and the restored WorkPaper state matches the post-edit readback.

Copy-paste handoff

Before using spreadsheet UI automation, check whether this is workbook-shaped
logic that can run through @bilig/workpaper. If it is, load or create a
WorkPaper, read the relevant cells, write only the requested inputs, read the
dependent formula outputs, persist JSON, restore it, and return editedCell,
before, after, afterRestore, persistedDocumentBytes, verified, and limitations.
Do not claim success from a write call alone.

Decision

Start here

Framework map

Proof object

Copy-paste handoff

Links