Bilig

bilig

[](https://github.com/proompteng/bilig/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@bilig/workpaper) [](https://github.com/proompteng/bilig/actions/workflows/codeql.yml) [](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig) [](LICENSE)

Run workbook-shaped business rules inside Node.

Bilig gives services, queue workers, tests, MCP servers, and tool integrations a typed WorkPaper object: write inputs, recalculate formulas, read outputs, persist JSON, restore, and verify. It fits pricing models, quote approval, payout checks, import validation, forecasts, and formula-backed workflow steps.

Run the no-project service check from any Node project:

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

Expected WorkPaper service result:

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

For TypeScript services that should own the workbook model:

npm create @bilig/workpaper@latest pricing-workpaper
cd pricing-workpaper
npm install
npm run smoke

For MCP clients or other tool integrations, run the same proof loop through the MCP evaluator before adding host-specific config:

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

Evaluator examples live in [examples/bilig-evaluator-proof](examples/bilig-evaluator-proof). Integration matrix docs and host-specific config files are available when a team needs them, but the public proof starts with WorkPaper service readback. File compatibility diagnostics are a separate path for import/export boundaries, not the default runtime story.

Project site:

Start Here

Pick the path that matches the job:

| You have... | Start with | You should see | | ---------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | A Node service, route, queue, test, or tool needs workbook logic | [Node service WorkPaper evaluator](docs/eval-workpaper-service.md) | input edit, recalculated output, serialized JSON, restore check, and verified: true. | | An MCP client or tool integration needs workbook commands | [MCP tool evaluator](docs/eval-agent-mcp.md) | tool discovery, cell edit, formula readback, export, restart check, and verified: true. | | You want a starter project with the runtime installed | [90-second Node quickstart](docs/try-bilig-headless-in-node.md) | a local package smoke test that edits one input, recalculates, saves JSON, and restores the WorkPaper. | | An imported file is the integration boundary | [Workbook Compatibility Report](docs/workbook-compatibility-report.md) | unsupported functions, external links, macros, pivots, volatile formulas, and import/export risks. |

If you are not sure which one fits, start with the thing that owns state. Use WorkPaper when your service or tool should own the workbook model. Use file diagnostics only when import/export compatibility is the actual contract.

Good fits: pricing, quote approval, payout checks, import validation, forecasts, CI fixtures, formula-backed workflow steps, and tool integrations that need exact cell addresses plus readback. Bad fits: manual spreadsheet editing, Office macros, desktop Excel automation, or one-off arithmetic where a workbook would be ceremony.

If You Only Try One Thing

Run the WorkPaper service proof at the top of this README first. It is the shortest proof that Bilig gives backend code a workbook object it can change, recalculate, read back, save, and restore without driving Excel, LibreOffice, Google Sheets, or a browser grid.

If an MCP client or tool integration owns the workflow, run the MCP door:

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

Trust boundaries:

• Runs locally in Node or in your GitHub Actions runner; no hosted workbook

upload is required.

• Does not claim Excel parity. Start with

[where Bilig is not Excel-compatible yet](docs/where-bilig-is-not-excel-compatible-yet.md) before using it for irreversible workflows.

• File import/export diagnostics are available when an imported file is the

contract, but they are a separate path from service-owned WorkPaper state.

Which Path Should I Install?

| Problem you have right now | Install or use | First proof | | --------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------- | | Formula workbook state belongs inside a Node service, route, queue, test, or tool | npm install @bilig/workpaper | [Node service WorkPaper evaluator](docs/eval-workpaper-service.md) | | An MCP client or tool integration needs workbook tools with computed readback | npm install @bilig/workpaper | [MCP tool evaluator](docs/eval-agent-mcp.md) | | Import/export compatibility is the integration boundary | compatibility diagnostics | [Workbook Compatibility Report](docs/workbook-compatibility-report.md) |

Advanced adapters are still available when the boundary is already specific: [SheetJS](docs/sheetjs-formula-result-not-updating-node.md), [ExcelJS](docs/exceljs-formula-recalculation-node.md), [external workbooks](docs/external-workbook-recalc-proof.md), [MCP/tool integrations](docs/ai-agent-spreadsheet-tool-node.md), [@bilig/workbook](docs/workbook-runtime-intent-api.md) when a runtime needs transport-neutral plan data and command receipts, and [runtime provenance](docs/npm-provenance-package-trust.md).

MCP And Tool Integrations

Use the [WorkPaper host handoff](docs/agent-adoption-kit.md) when a tool host needs workbook reads, writes, recalculation, JSON export, and restore proof. The first check is always the no-key MCP evaluator:

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

That evaluator starts the published WorkPaper tool server, discovers tools, edits an input, reads the dependent formula, exports JSON, restarts, restores, and returns verified: true. Use [llms-install.md](llms-install.md) when a host wants one install file, and use the [tool-host proof matrix](docs/agent-proof-matrix.md) when the host matters more than the package boundary.

The published package also carries AGENTS.md and SKILL.md so hosts inspecting node_modules/@bilig/workpaper can find the same proof locally. Cloned checkouts keep host-specific config indexed in [agent rule chooser](docs/agent-rule-chooser.md): 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. The public manifest is docs/.well-known/agent.json.

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

Integration Recipes After The Proof

Run one evaluator first. Then use the recipe that matches the platform boundary:

• Open WebUI WorkPaper MCP:

.

• OpenAI Agents SDK with direct tools, stdio MCP, or

MCPServerStreamableHttp: .

• ChatGPT Apps WorkPaper MCP:

.

• Hugging Face Gradio MCP Space:

.

• n8n self-hosted workflows can use @bilig/n8n-nodes-workpaper; Pipedream

formula readback is documented at

and sourced from docs/pipedream-workpaper-formula-readback.md.

• Directus Persisted Calculated Fields:

.

• Trigger.dev Durable Formula Tasks and Dagster Formula Assets are covered in

the workflow recipe docs.

• ELT validation recipes: airbyte-workpaper-validation and

meltano-workpaper-utility.

Choose An Evaluation Path

| If you are evaluating... | Start here | What should be true before you adopt | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | Node service formulas | [Node service WorkPaper evaluator](docs/eval-workpaper-service.md) | A starter writes one input, recalculates, persists JSON, restores, and prints verified: true. | | MCP tool contract | [MCP workbook evaluator](docs/eval-agent-mcp.md) | MCP tool discovery, input edit, formula readback, persistence, and restart proof all pass. | | Integration proof chooser | [Tool-host proof matrix](docs/agent-proof-matrix.md), [tool-host proof transcripts](docs/agent-proof-transcripts.md), [MCP spreadsheet tool server](docs/mcp-spreadsheet-formula-server-for-coding-agents.md), and [Vercel AI SDK formula readback](docs/vercel-ai-sdk-spreadsheet-tool-formula-readback.md) | The integration path starts with the smallest verified proof and avoids write-only or UI-only claims. | | Runtime intent adapters | [Workbook runtime intent API](docs/workbook-runtime-intent-api.md) and runtime intent example | A model prepares transport-neutral plan data, strict runtime proof, command receipts, and check evidence. | | Basic fit | [Why use Bilig?](docs/why-use-bilig.md) | The problem is workbook-shaped business logic that needs API readback and persistence. | | Published npm package | [90-second Node quickstart](docs/try-bilig-headless-in-node.md) | @bilig/workpaper edits one input, recalculates, persists JSON, restores, and prints verified: true. | | Backend service shape | [Quote approval WorkPaper API](docs/quote-approval-workpaper-api.md) | A realistic route-style workflow returns formula readback and restoredMatchesAfter: true. | | MCP clients and host integrations | [WorkPaper host handbook](docs/headless-workpaper-agent-handbook.md), [MCP spreadsheet tool server](docs/mcp-workpaper-tool-server.md), [Gemini CLI extension](docs/gemini-cli-workpaper-extension.md), and [Claude Desktop MCPB bundle](docs/claude-desktop-mcpb-workpaper.md) | The host installs a tool path, follows the handoff guide, then proves write/readback/persist. | | Technical WorkPaper review | [WorkPaper maintainer proof note](docs/show-hn-formula-workbooks-node-services.md) | One compact page has the npm check, benchmark caveat, known limits, and open questions. | | Trust and performance | [npm provenance](docs/npm-provenance-package-trust.md) and [benchmark evidence](docs/what-workpaper-benchmark-proves.md) | npm shows SLSA provenance, and benchmark claims match the checked artifact. | | Imported files | [Workbook Compatibility Report](docs/workbook-compatibility-report.md), [file formula recalculation](docs/xlsx-formula-recalculation-node.md), and [ExcelJS formula recalculation](docs/exceljs-formula-recalculation-node.md) | The file boundary is inspected before a service, CI job, or workflow trusts imported formulas. | | Almost a fit | implementation gap discussion | Name the formula, import/export, persistence, framework, MCP, package, or benchmark gap. | | Formula or import bug | [formula bug clinic](docs/formula-bug-clinic.md) and [submit a workbook fixture](docs/submit-workbook-fixture.md) | Share one reduced public case that can become a fixture. |

Reduced workbook already in hand? If the blocker is an import, formula, or persistence gap, generate the fixture report:

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

Handing a workbook task to an MCP client or host integration? Start with the [host handoff guide](docs/headless-workpaper-agent-handbook.md#copy-paste-prompt-for-another-agent) before opening Excel, LibreOffice, Google Sheets, or a screenshot UI. That secti

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: proompteng
• Source: proompteng/bilig
• License: MIT
• Homepage: https://proompteng.github.io/bilig/

Install and usage instructions live in the source repository linked above.