@bilig/workpaper
Advanced tools
Bilig WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.
Bilig WorkPaper is an API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.
Use this when business logic is easiest to review as workbook cells and formulas, but the calculation needs to run in a backend service, queue worker, serverless route, test, or coding-agent tool.
@bilig/workpaper is the canonical scoped npm entrypoint. The unscoped
bilig-workpaper package remains published as a compatibility and search alias.
npm install @bilig/workpaper
Pick the door that matches the state you own:
| Door | Run first | What it proves |
|---|---|---|
| Unsure / agent handoff | npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json | compact decision card before the agent opens Excel, Sheets, or a browser grid. |
| Node service or test | npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json | edit input, recalculate output, persist JSON, restore, and return verified: true. |
| Coding agent or MCP client | npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json | tool discovery, cell mutation, formula readback, JSON export, restart proof, and verified: true. |
| New project | npm create @bilig/workpaper@latest pricing-agent -- --agent | a starter with AGENTS.md, MCP config, and npm run agent:verify wired to the same proof loop. |
bilig-agent-start --json is intentionally small. It gives an agent the
workbook-vs-XLSX decision card, first proof commands, required evidence fields,
expected MCP tools, and public discovery links without asking it to read the
whole site.
Run the agent proof without cloning the repo:
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario revenue-plan --json
The useful output is not a write-call status. It is readback proof:
{
"schemaVersion": "bilig-evaluator.v1",
"door": "agent-mcp",
"verified": true,
"packageVersions": {
"@bilig/workpaper": "0.163.0"
},
"evidence": {
"scenario": "revenue-plan",
"editedCell": "Deals!C2",
"readbackRange": "Summary!B2:B8",
"after": {
"totalRevenue": 36900,
"westCustomers": 38
},
"checks": {
"totalRevenueRecalculated": true,
"sumifReadbackChanged": true,
"xlookupReadbackStable": true,
"filterSpillUpdated": true,
"persistedToDisk": true,
"restartReadbackMatchesAfter": true
}
}
}
If that is the contract your service or agent needed, star the repo so you can find it again: https://github.com/proompteng/bilig/stargazers. Watch releases if this is close to production: https://github.com/proompteng/bilig/subscription.
For a richer agent check, add --scenario revenue-plan to the agent-mcp
evaluator. It proves SUM, SUMIF, XLOOKUP, FILTER, a named expression,
JSON persistence, and restart readback.
If the workbook has provider-backed formulas such as IMPORTRANGE, run
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario provider-backed --json.
That proves the formula fails closed with an adapter diagnostic, then verifies a
local synthetic adapter readback. It does not call Google Sheets.
If one of those matches your workflow, keep Bilig nearby: https://github.com/proompteng/bilig.
Framework examples live in the repo instead of this first screen. Start with the closest runtime:
.xlsx files: use @bilig/xlsx-formula-recalc for stale formula
caches and exported workbook readback.These are integration guide names that users search for on npm. They are links, not the first-run path:
import { buildA1WorkPaper } from '@bilig/workpaper'
const book = buildA1WorkPaper({
Inputs: [
['Metric', 'Value'],
['Units', 40],
['Price', 1200],
],
Summary: [
['Metric', 'Value'],
['Revenue', '=Inputs!B2*Inputs!B3'],
],
})
const proof = book.editAndReadback('Inputs!B2', 48, {
readbackRange: 'Summary!B2',
})
console.log({
editedCell: proof.editedCell,
before: proof.beforeReadback.displayValues,
after: proof.afterReadback.displayValues,
afterRestore: proof.restoredReadback.displayValues,
persistedDocumentBytes: proof.persistedDocumentBytes,
verified: proof.verified,
})
book.dispose()
Use book.set('Inputs!B2', 48), book.setMany({ 'Inputs!B3': 1500 }),
book.readMany(['Inputs!B2', 'Summary!B2']), book.display('Summary!B2'),
and book.saveJson() when you do not need the full proof object. Use
book.editManyAndReadback() when several inputs should commit as one atomic
proof with typed readback comparison, formula diagnostics, persistence, and
restore checks.
Install the AI SDK and Zod in the application that owns the agent loop:
npm install @bilig/workpaper ai zod
Then expose a WorkPaper as normal AI SDK tools:
import { generateText, stepCountIs } from 'ai'
import { WorkPaper } from '@bilig/workpaper'
import { createAiSdkWorkPaperTools } from '@bilig/workpaper/ai-sdk'
const workpaper = WorkPaper.buildFromSheets({
Inputs: [
['Metric', 'Value'],
['Qualified opportunities', 20],
['Win rate', 0.25],
['Average ARR', 12000],
],
Summary: [
['Metric', 'Value'],
['Expected customers', '=Inputs!B2*Inputs!B3'],
['Expected ARR', '=B2*Inputs!B4'],
],
})
const tools = createAiSdkWorkPaperTools({
workpaper,
defaultReadRange: 'Summary!A1:B3',
proofRange: 'Summary!A1:B3',
writableSheets: ['Inputs'],
})
const result = await generateText({
model,
tools,
stopWhen: stepCountIs(2),
prompt: 'Read the summary, set Inputs!B3 to 0.4, then report the computed ARR change.',
})
console.log(result.text)
The mutating tool returns editedCell, before, after, restored, and
checks. Keep writableSheets narrow so the model can edit inputs without
rewriting formula sheets.
The package ships evaluator and direct proof commands:
npm exec --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json
npm exec --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
npm exec --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario provider-backed --json
npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-n8n-formula-server --port 4321
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx --workpaper ./.bilig/pricing.workpaper.json --writable
bilig-evaluate prints a bilig-evaluator.v1 object with door, evidence,
verified, limitations, and the source command output.
The challenge commands edit one input, recalculate dependent formulas, export
WorkPaper JSON, restore it, and print a verified: true proof object.
Use --from-xlsx when the agent already has an XLSX file: Bilig imports it once
into an in-memory MCP server by default, or into persisted WorkPaper JSON when
--workpaper --writable is also supplied. That XLSX-backed MCP path also lists
analyze_workbook_risk, a read-only tool fixed to the source workbook passed at
startup. It reports workbook risk indicators before an agent trusts the imported
WorkPaper and does not certify Excel compatibility.
When another coding agent is about to solve a spreadsheet task by opening Excel, LibreOffice, Google Sheets, or a screenshot grid, hand it the adoption kit instead:
npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
The kit gives the agent one path: install the instructions, run the no-key
agent evaluator, paste a workbook edit task, and require computed readback plus
persisted state before reporting success. Use bilig-mcp-challenge --json only
when debugging the lower-level MCP transcript.
Docs: https://proompteng.github.io/bilig/agent-adoption-kit.html
Use the local formula-readback server when an agent workflow platform should orchestrate the task but Bilig should own workbook state:
npm exec --package @bilig/workpaper@latest -- bilig-n8n-formula-server --port 4321
Start from the repo examples:
examples/directus-workpaper-flow-operationexamples/windmill-workpaper-scriptexamples/triggerdev-workpaper-taskexamples/airbyte-workpaper-validationexamples/meltano-workpaper-utilityexamples/temporal-workpaper-activityexamples/airflow-workpaper-dagexamples/dagster-workpaper-assetexamples/kestra-workpaper-flowexamples/prefect-workpaper-flowexamples/n8n-workpaper-formula-readback/bilig-workpaper-formula-readback.n8n.jsonexamples/dify-workpaper-formula-readback mirrors the Dify plugin source;
the package was merged upstream in
https://github.com/langgenius/dify-plugins/pull/2451examples/flowise-workpaper-formula-readback/bilig-workpaper-formula-readback.flowise-tool.jsonintegrations/pipedream-bilig-workpaper mirrors the Pipedream action shape;
the public review is https://github.com/PipedreamHQ/pipedream/pull/20972examples/fastmcp-workpaper-clientexamples/langchain-mcp-workpaper-toolnodeexamples/smolagents-workpaper-toolDocs:
import { WorkPaper } from '@bilig/workpaper'
import { exportXlsx, importXlsx } from '@bilig/workpaper/xlsx'
Use @bilig/xlsx-formula-recalc when you only need to edit and recalculate
XLSX files. Use @bilig/exceljs-formula-recalc when you already use ExcelJS
and need recalculated formula results after changing inputs.
The npm tarball exposes the same CLI entrypoints through the canonical scoped package, so agents can install one focused package and still get the MCP stdio server:
import { createWorkPaperMcpServer } from '@bilig/workpaper/mcp'
For a runnable starter project with AGENTS.md, MCP client config, and an
agent:verify script:
npm create @bilig/workpaper@latest pricing-agent -- --agent
Bilig is not a desktop Excel clone. It is a formula workbook runtime for service-owned calculations, JSON persistence, XLSX import/export, and agent-readable readback. Unsupported Excel functions, external workbook links, macros, and volatile functions may need review.
If the starter or challenge output gives you verified: true for the service
or agent workflow you need, star or bookmark Bilig so the WorkPaper runtime is
easy to find again: https://github.com/proompteng/bilig/stargazers.
Watch releases if this is close to a production path: https://github.com/proompteng/bilig/subscription.
If the model is close but blocked by a formula, import/export, persistence, framework, MCP, or package-boundary gap, open the smallest adoption blocker: https://github.com/proompteng/bilig/discussions/new?category=general.
Full docs: https://proompteng.github.io/bilig/
FAQs
Run workbook-shaped business rules in Node services: edit inputs, recalculate formulas, read outputs, and save WorkPaper JSON.
The npm package @bilig/workpaper receives a total of 42 weekly downloads. As such, @bilig/workpaper popularity was classified as not popular.
We found that @bilig/workpaper demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.
Company News
Socket is now in the AWS Security Hub Extended plan. Adopt it through AWS, apply committed spend, and block malicious open source packages.
Research
/Security News
Popular npm packages keyv and cacheable compromised.