Bilig WorkPaper

Official8 toolsLive

by proompteng · TypeScript

Formula-backed WorkPaper tools for workbook readback, input edits, and JSON persistence.

io.github.proompteng/bilig-workpaper MCP Server

The io.github.proompteng/bilig-workpaper Model Context Protocol (MCP) server provides formula-backed WorkPaper tools for workbook readback, input edits, and JSON persistence. It is implemented as a Node.js package (Node.js >= 22) and exposes 8 tools for working with workbook runtime behavior and formula recalculation.

🛠️ Key Features

Formula-engine support for server-side formulas
Workbook readback and workbook automation
Input edits and workbook runtime updates
JSON persistence via workpaper-json

🚀 Use Cases

Recomputing formulas and reflecting workbook-formulas changes
Automating workpaper-runtime workflows
Persisting and restoring workpaper state as JSON

⚡ Developer Benefits

Node.js (>= 22) integration
TypeScript-oriented tooling (topics include typescript)
MCP tooling aligned with model-context-protocol and mcp-server usage

⚠️ Limitations

Only documented tool scope is for WorkPaper readback/edit/persistence; no other domains are indicated

Topics

typescriptformula-engineformula-recalculationworkbook-apimcpmcp-servermodel-context-protocolnodejsworkpaperworkbook-runtimeworkbook-automationnode-servicesworkflow-automationmcp-toolsnode-formulasserver-side-formulasworkpaper-jsonformula-workbookworkbook-formulasworkpaper-runtime

Captured live from the server via tools/list.

list_sheets

Discover sheet names and used dimensions before reading or editing a WorkPaper. Returns metadata only; use read_range or read_cell for values.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "additionalProperties": false
}

read_range

Read calculated values plus serialized formulas/inputs for an A1 range. Use for audit readback after edits; use read_cell for one address.

Parameters2

range	string	required	A1 range such as Summary!A1:B5. If omitted from the range, pass sheetName separately.
sheetName	string	optional	Default sheet name when range omits a sheet name, for example Summary.

Raw schema

{
  "type": "object",
  "properties": {
    "range": {
      "type": "string",
      "description": "A1 range such as Summary!A1:B5. If omitted from the range, pass sheetName separately."
    },
    "sheetName": {
      "type": "string",
      "description": "Default sheet name when range omits a sheet name, for example Summary."
    }
  },
  "required": [
    "range"
  ],
  "additionalProperties": false
}

read_cell

Read one cell with calculated value, display text, formula text, formula diagnostics, and serialized content. Use after set_cell_contents to verify readback.

Parameters2

sheetName	string	required	Existing sheet name.
address	string	required	Single A1 cell address such as B3.

Raw schema

{
  "type": "object",
  "properties": {
    "sheetName": {
      "type": "string",
      "description": "Existing sheet name."
    },
    "address": {
      "type": "string",
      "description": "Single A1 cell address such as B3."
    }
  },
  "required": [
    "sheetName",
    "address"
  ],
  "additionalProperties": false
}

set_cell_contents

Write raw content to one cell and recalculate dependents in memory only. Start with --writable when the edit should persist to JSON.

Parameters3

sheetName	string	required	Existing sheet name, for example Inputs.
address	string	required	Single A1 cell address such as B3. Ranges are not accepted.
value	string	required	Raw cell content. Formula strings must start with =; plain strings are stored as literals. Strict MCP hosts such as Semantic Kernel require a single parameter type, so pass evaluated numbers/booleans as formulas such as =0.4 or =TRUE(). The server still accepts JSON number, boolean, or null arguments from clients that support them.

Raw schema

{
  "type": "object",
  "properties": {
    "sheetName": {
      "type": "string",
      "description": "Existing sheet name, for example Inputs."
    },
    "address": {
      "type": "string",
      "description": "Single A1 cell address such as B3. Ranges are not accepted."
    },
    "value": {
      "type": "string",
      "description": "Raw cell content. Formula strings must start with =; plain strings are stored as literals. Strict MCP hosts such as Semantic Kernel require a single parameter type, so pass evaluated numbers/booleans as formulas such as =0.4 or =TRUE(). The server still accepts JSON number, boolean, or null arguments from clients that support them."
    }
  },
  "required": [
    "sheetName",
    "address",
    "value"
  ],
  "additionalProperties": false
}

set_cell_contents_and_readback

Write raw content to one cell, recalculate dependents, read a dependent range in the same tool call, and return persistence proof. Use this for stateless MCP clients such as hosted Open WebUI integrations.

Parameters5

sheetName	string	required	Existing sheet name for the cell to edit, for example Inputs.
address	string	required	Single A1 cell address to edit, such as B3. Ranges are not accepted.
value	string	required	Raw cell content. Formula strings must start with =; plain strings are stored as literals. Strict MCP hosts require a single parameter type, so pass evaluated numbers/booleans as formulas such as =0.4 or =TRUE(). The server still accepts JSON number, boolean, or null arguments from clients that support them.
readbackRange	string	required	Dependent A1 range to read before and after the edit, for example Summary!A1:B5.
readbackSheetName	string	optional	Default sheet name when readbackRange omits a sheet name.

Raw schema

{
  "type": "object",
  "properties": {
    "sheetName": {
      "type": "string",
      "description": "Existing sheet name for the cell to edit, for example Inputs."
    },
    "address": {
      "type": "string",
      "description": "Single A1 cell address to edit, such as B3. Ranges are not accepted."
    },
    "value": {
      "type": "string",
      "description": "Raw cell content. Formula strings must start with =; plain strings are stored as literals. Strict MCP hosts require a single parameter type, so pass evaluated numbers/booleans as formulas such as =0.4 or =TRUE(). The server still accepts JSON number, boolean, or null arguments from clients that support them."
    },
    "readbackRange": {
      "type": "string",
      "description": "Dependent A1 range to read before and after the edit, for example Summary!A1:B5."
    },
    "readbackSheetName": {
      "type": "string",
      "description": "Default sheet name when readbackRange omits a sheet name."
    }
  },
  "required": [
    "sheetName",
    "address",
    "value",
    "readbackRange"
  ],
  "additionalProperties": false
}

get_cell_display_value

Return the formatted display string for one cell. Use when an agent needs what a user would see, not the raw numeric value.

Parameters2

sheetName	string	required	Existing sheet name.
address	string	required	Single A1 cell address such as B3.

Raw schema

{
  "type": "object",
  "properties": {
    "sheetName": {
      "type": "string",
      "description": "Existing sheet name."
    },
    "address": {
      "type": "string",
      "description": "Single A1 cell address such as B3."
    }
  },
  "required": [
    "sheetName",
    "address"
  ],
  "additionalProperties": false
}

export_workpaper_document

Export the current WorkPaper JSON document for persistence, review, or handoff to another agent. Does not write files by itself.

Parameters1

includeConfig

boolean

optional

Include workbook configuration metadata in the exported JSON. Defaults to true.

Raw schema

{
  "type": "object",
  "properties": {
    "includeConfig": {
      "type": "boolean",
      "default": true,
      "description": "Include workbook configuration metadata in the exported JSON. Defaults to true."
    }
  },
  "additionalProperties": false
}

validate_formula

Validate formula syntax with the WorkPaper parser before writing it to a cell. This checks syntax only; use set_cell_contents plus readback to evaluate.

Parameters1

formula

string

required

Formula string including the leading =, for example =SUM(Inputs!B2:B4).

Raw schema

{
  "type": "object",
  "properties": {
    "formula": {
      "type": "string",
      "description": "Formula string including the leading =, for example =SUM(Inputs!B2:B4)."
    }
  },
  "required": [
    "formula"
  ],
  "additionalProperties": false
}

README.md15 KBView on GitHub

Bilig

OpenSSF Scorecard

Keep the workbook model. Run the rule in Node.

Bilig is a TypeScript-native, headless WorkPaper runtime for Node.js services, tests, and AI agents. Set inputs, recalculate formulas, read computed outputs, persist WorkPaper JSON, restore it, and verify the result—without driving Excel or a browser grid.

Docs · Quick start · TypeScript API · MCP · Examples · Discussions

A WorkPaper input edit recalculating a formula, then surviving JSON restore

NOTE

Bilig is a headless workbook runtime, not a visual spreadsheet app or a claim of full Excel compatibility. If an .xlsx file is your contract, start with the compatibility report.

Quick Start

Prove the published package before installing it:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json

The evaluator edits Inputs!B2, recalculates Summary!B2, saves the WorkPaper, restores it, and compares the restored value:

json

{
  "schemaVersion": "bilig-evaluator.v1",
  "door": "workpaper-service",
  "evidence": {
    "editedCell": "Inputs!B2",
    "dependentCell": "Summary!B2",
    "before": 24000,
    "after": 38400,
    "afterRestore": 38400
  },
  "verified": true
}

verified: true means the write, formula readback, JSON export, and restored readback all passed. It is stronger evidence than a successful write call.

Use It From TypeScript

npm install @bilig/workpaper

import { buildA1WorkPaper } from "@bilig/workpaper";

const pricing = buildA1WorkPaper({
  Inputs: [
    ["Metric", "Value"],
    ["Units", 20],
    ["Price", 1200],
  ],
  Summary: [
    ["Metric", "Value"],
    ["Revenue", "=Inputs!B2*Inputs!B3"],
  ],
});

const proof = pricing.editAndReadback("Inputs!B2", 32, {
  readbackRange: "Summary!B2",
});

console.log(proof.afterReadback.displayValues[0]?.[0]); // 38400
console.log(proof.verified); // true

pricing.dispose();

For ordinary operations, use set(), setMany(), readMany(), display(), and saveJson(). Use editManyAndReadback() when multiple inputs must be committed and verified as one edit. The complete public API is documented in packages/workpaper/README.md.

The lifecycle is deliberately small:

inputs → formula recalculation → typed readback → JSON persistence → restore verification

Why Bilig

Capability	What it gives you
Workbook-shaped models	Sheets, A1 addresses, formulas, ranges, and named expressions without a spreadsheet UI.
Verified mutations	Before/after computed values plus persistence and restore checks.
Service-owned state	Portable WorkPaper JSON for routes, queues, tests, tools, and audit trails.
Agent-safe tools	Narrow read/write tools with exact cells, computed readback, and writable-sheet boundaries.
Explicit file boundaries	Separate XLSX import, export, risk inspection, and Excel-oracle workflows.

Use Bilig for pricing, quote approval, payouts, forecasts, validation rules, formula-backed workflows, and tests where a service or tool should own the model. Choose a spreadsheet application or hosted spreadsheet API when you need visual editing, collaboration, macros, interactive pivots or charts, or desktop fidelity.

Agents And MCP

Agents should first ask which system owns state, then run the smallest matching proof. For a tool host or MCP client:

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

The MCP evaluator proves tool discovery, mutation, recalculated readback, JSON export, disk persistence, process restart, and restored readback. For a local, writable WorkPaper:

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

Use that local stdio path for private or persistent project state. The hosted https://bilig.proompteng.ai/mcp endpoint is request-local and only intended for stateless connector discovery and smoke tests; do not send private workbook data to it.

The server exposes list_sheets, read_range, read_cell, set_cell_contents, set_cell_contents_and_readback, get_cell_display_value, export_workpaper_document, and validate_formula. It also publishes MCP resources and prompts so capable hosts can discover the workflow before editing cells.

Machine-readable entry points:

Need	Entry point
A compact routing card	`docs/agent-start.txt`
A concise model index	`docs/llms.txt`
Full agent documentation	`docs/llms-full.txt`
Installation context	`docs/llms-install.md`
Structured capabilities	`docs/agent.json`
Reusable skill	`skills/bilig-workpaper/SKILL.md`
Proof and host matrix	`docs/agent-adoption-kit.md`

The published package also carries AGENTS.md and SKILL.md, so an agent can discover the same proof contract from node_modules. Install or inspect the public skill with either source:

npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list

Host-specific project files

Use the agent rule chooser or the host handoff prompt. The repository includes CLAUDE.md, .claude/skills/bilig-workpaper/SKILL.md, .claude/commands/bilig-workpaper-proof.md, .cursor/rules/bilig-workpaper.mdc, .devin/rules/bilig-workpaper.md, .windsurf/rules/bilig-workpaper.md, .clinerules/bilig-workpaper.md, .continue/rules/bilig-workpaper.md, .zed/settings.json, opencode.jsonc, and .opencode/agents/bilig-workpaper.md.

Integration Recipes After The Proof

Run an evaluator first, then use the recipe owned by your host:

OpenAI Agents SDK: direct tools, MCPServerStdio, and MCPServerStreamableHttp.
OpenAI Responses API: function-call readback with explicit before/after evidence.
Vercel AI SDK: generateText() and streamText() tool loops.
Open WebUI: local or hosted MCP discovery.
n8n: the @bilig/n8n-nodes-workpaper community node.

Choose An Evaluation Path

Your state owner	Start here	Evidence to require
TypeScript application	`npm install @bilig/workpaper`	direct A1 API and focused application tests
Node service, route, queue, or test	`bilig-evaluate --door workpaper-service --json`	edit, recalculation, JSON export, restore, `verified: true`
MCP client or tool host	`bilig-evaluate --door agent-mcp --json`	discovery, readback, disk persistence, restart
Imported `.xlsx` is the contract	`workbook-compatibility-report workbook.xlsx --json`	unsupported formulas and workbook risk reasons for that file
Cached `.xlsx` values look stale	`xlsx-cache-doctor workbook.xlsx --json`	stale-cache diagnosis, recalculation, and readback for that file

The workbook-compatibility and xlsx-cache evaluator doors use bundled demo workbooks to smoke-test the published package; they do not inspect your file. Do not treat any evaluator as proof of desktop Excel parity.

Examples And Deeper Guides

Start with one maintained example, not the whole monorepo:

examples/headless-workpaper: pricing, invoice, budget, fulfillment, subscription, persistence, and agent examples.
examples/serverless-workpaper-api: quote approval through Hono, Next.js, and persistence adapters.
examples/xlsx-recalculation-node: import, recalculate, export, reimport, and verify an XLSX workbook.
examples/recalc-bridge-workflows: focused bridges for existing SheetJS, xlsx-populate, and ExcelJS workflows.

Useful decision guides:

Runnable integration and diagnostic commands

pnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-text
pnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-text
pnpm --dir examples/headless-workpaper run agent:openai-responses
pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
pnpm --dir examples/serverless-workpaper-api run hono-route
pnpm --dir examples/serverless-workpaper-api run next-server-action
pnpm --dir examples/serverless-workpaper-api run next-server-action-formdata

The AI SDK generateText() smoke lives at ai-sdk-generate-text-tool-smoke.ts. The OpenAI example is documented in openai-responses-workpaper-tool-call.

For a reduced formula or import bug:

npm exec --yes --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells "Summary!B7,Inputs!B2"

XLSX And Excel Compatibility

Bilig can import and export workbook files, but cached formula values inside an .xlsx are diagnostics—not an accuracy oracle. Inspect the file before trusting it:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor workbook.xlsx --json

The first command is a package smoke test over a bundled demo. The next two inspect the named file. The compatibility report identifies unsupported functions, external links, macros, pivots, volatile formulas, and other risks; it does not certify Excel compatibility. When correctness matters, compare against a workbook freshly recalculated by Excel. See the compatibility limits and Excel oracle walkthrough.

Packages And Repository Map

Path	Role
`packages/workpaper`	Recommended `@bilig/workpaper` API, evaluators, AI SDK adapter, MCP server, and XLSX boundary.
`packages/headless`	Lower-level WorkPaper runtime and integration primitives.
`packages/xlsx-formula-recalc`	Real-file compatibility and stale-cache diagnostics.
`packages/formula`	Formula parser, binder, compiler, and evaluator.
`packages/core`	Workbook state, mutations, snapshots, and scheduling.
`apps/web`	Browser spreadsheet shell.
`apps/bilig`	Full-stack runtime, APIs, and static site host.

The public package requires Node.js >=22. Local monorepo development uses Node.js 24+, Bun, and pnpm@10.32.1.

Published releases include npm registry signatures and provenance attestations:

npm view @bilig/workpaper version dist.attestations dist.signatures --json
npm audit signatures

Development

Choose one long-running development server:

pnpm dev:web
pnpm dev:web-local

Install and validate the repository with:

pnpm install
pnpm build
pnpm lint
pnpm typecheck
pnpm test
pnpm run ci

Architecture lives in docs/architecture.md. Read CONTRIBUTING.md before opening a pull request; first-time contributors can start with the new contributor guide and starter issues. All participation follows the CODE_OF_CONDUCT.md.

Support And Security

Ask adoption and design questions in Discussions.
Follow versioned changes through GitHub Releases.
Report reproducible bugs through Issues; reduced workbooks can use the formula bug clinic and fixture form.
Read SUPPORT.md for the evidence that makes a report actionable.
Follow SECURITY.md for private vulnerability reporting. Never attach private workbook data, credentials, or tokens to a public issue.

If Bilig fits one of your services or agent workflows, star the repository to follow releases and help other Node developers find it. Tell us what proof or formula is still missing.

License

MIT

Install

Tools (8)

list_sheetsread_rangeread_cellset_cell_contentsset_cell_contents_and_readbackget_cell_display_valueexport_workpaper_documentvalidate_formula

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "bilig-workpaper": {
      "command": "npx",
      "args": [
        "-y",
        "@bilig/workpaper@0.164.11"
      ]
    }
  }
}

io.github.proompteng/bilig-workpaper MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

list_sheets

read_range

read_cell

set_cell_contents

set_cell_contents_and_readback

get_cell_display_value

export_workpaper_document

validate_formula

Bilig

Quick Start

Use It From TypeScript

Why Bilig

Agents And MCP

Integration Recipes After The Proof

Choose An Evaluation Path

Examples And Deeper Guides

XLSX And Excel Compatibility

Packages And Repository Map

Development

Support And Security

License

Install

Related servers