Bilig WorkPaper

io.github.proomptengPublished by GitHub account proomptengv1.1.0Updated Oct 25, 2026

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

VerifiedStreamable HTTPWeb executableDeveloper ToolsData & Analytics

Overview

AI-generated overview

A headless WorkPaper runtime that lets an assistant read, edit and recalculate formula-backed workbook cells and export the workbook as JSON.

What you can do
List sheets and their used dimensions before reading or editing a WorkPaper. Read a cell or an A1 range, returning calculated values, display text, formulas and diagnostics. Write raw content to a cell, recalculate dependents, and optionally read back a dependent range in the same call. Check the formatted display string a user would see. Validate formula syntax before writing it. Export the current WorkPaper JSON document for persistence or handoff.
When to use it
Useful when a service, test or agent should own a formula-backed model such as pricing, quotes, payouts or forecasts without driving Excel or a browser grid. Fits workflows that need verified edits with before/after readback and JSON persistence.
Requirements
Either the hosted remote endpoint or a local process from the npm package @bilig/workpaper over stdio. The local path needs Node.js 24 or later and is started with a WorkPaper file path; add the writable flag when edits should persist to JSON. No authentication, environment variables or headers are declared.
Before you install
The hosted endpoint is request-local and intended only for stateless discovery and smoke tests; do not send private workbook data to it. Use the local stdio path for private or persistent state. Writes recalculate dependents and persist to JSON only when started in writable mode. The project states it is not fully Excel-compatible, so verify results against a workbook recalculated by Excel when correctness matters.

Installation

In SourceWeft

  1. Open Bilig WorkPaper in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.proompteng%2Fbilig-workpaper/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "bilig-workpaper": {
      "type": "http",
      "url": "https://bilig.proompteng.ai/mcp"
    }
  }
}

README

Bilig

[CI] [npm] [Node.js] [OpenSSF Scorecard] [License: MIT]

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

Node runtime

Prove the published package before installing it:

sh
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

sh
npm install @bilig/workpaper
ts
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]) // 38400console.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

CapabilityWhat it gives you
Workbook-shaped modelsSheets, A1 addresses, formulas, ranges, and named expressions without a spreadsheet UI.
Verified mutationsBefore/after computed values plus persistence and restore checks.
Service-owned statePortable WorkPaper JSON for routes, queues, tests, tools, and audit trails.
Agent-safe toolsNarrow read/write tools with exact cells, computed readback, and writable-sheet boundaries.
Explicit file boundariesSeparate 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:

sh
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --jsonnpm 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:

sh
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:

NeedEntry point
A compact routing carddocs/agent-start.txt
A concise model indexdocs/llms.txt
Full agent documentationdocs/llms-full.txt
Installation contextdocs/llms-install.md
Structured capabilitiesdocs/agent.json
Reusable skillskills/bilig-workpaper/SKILL.md
Proof and host matrixdocs/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:

sh
npx --yes skills@latest add https://bilig.proompteng.ai --listnpx --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 ownerStart hereEvidence to require
TypeScript applicationnpm install @bilig/workpaperdirect A1 API and focused application tests
Node service, route, queue, or testbilig-evaluate --door workpaper-service --jsonedit, recalculation, JSON export, restore, verified: true
MCP client or tool hostbilig-evaluate --door agent-mcp --jsondiscovery, readback, disk persistence, restart
Imported .xlsx is the contractworkbook-compatibility-report workbook.xlsx --jsonunsupported formulas and workbook risk reasons for that file
Cached .xlsx values look stalexlsx-cache-doctor workbook.xlsx --jsonstale-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:

Useful decision guides:

Runnable integration and diagnostic commands
sh
pnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-textpnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-textpnpm --dir examples/headless-workpaper run agent:openai-responsespnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflightpnpm --dir examples/serverless-workpaper-api run hono-routepnpm --dir examples/serverless-workpaper-api run next-server-actionpnpm --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:

sh
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:

sh
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --jsonnpm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --jsonnpm 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

PathRole
packages/workpaperRecommended @bilig/workpaper API, evaluators, AI SDK adapter, MCP server, and XLSX boundary.
packages/xlsx-formula-recalcReal-file compatibility and stale-cache diagnostics.
packages/formulaFormula parser, binder, compiler, and evaluator.
packages/coreWorkbook state, mutations, snapshots, and scheduling.
apps/webBrowser spreadsheet shell.
apps/biligFull-stack runtime, APIs, and static site host.

The public WorkPaper package requires Node.js >=24. Local monorepo development uses Node.js 24+, Bun, and [email protected].

Published releases include npm registry signatures and provenance attestations:

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

Development

Choose one long-running development server:

sh
pnpm dev:webpnpm dev:web-local

Install and validate the repository with:

sh
pnpm installpnpm buildpnpm lintpnpm typecheckpnpm testpnpm 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

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

Source: README.md at commit 49db26b

Tools

8

list_sheets

List WorkPaper Sheets

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

Takes no parameters.

read_range

Read WorkPaper Range

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

ParametersrangerequiredsheetName

read_cell

Read WorkPaper Cell

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

ParametersaddressrequiredsheetNamerequired

set_cell_contents

Set WorkPaper Cell Contents

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

ParametersvaluerequiredaddressrequiredsheetNamerequired

set_cell_contents_and_readback

Set WorkPaper Cell Contents And Read Back

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.

ParametersvaluerequiredaddressrequiredsheetNamerequiredreadbackRangerequiredreadbackSheetName

get_cell_display_value

Get WorkPaper 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.

ParametersaddressrequiredsheetNamerequired

export_workpaper_document

Export WorkPaper Document

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

ParametersincludeConfig

validate_formula

Validate WorkPaper 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.

Parametersformularequired

Version history

2
  1. v1.1.0LatestOct 4, 2026
  2. v0.164.11Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts