bilig

![CI](https://github.com/proompteng/bilig/actions/workflows/ci.yml) ![npm: @bilig/workpaper](https://www.npmjs.com/package/@bilig/workpaper) ![CodeQL](https://github.com/proompteng/bilig/actions/workflows/codeql.yml) ![OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig) ![License: MIT](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

If a tool host owns the workflow, run 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. Tool-host and framework evaluators are ranked in the tool-host proof matrix. The tool-host proof transcripts show the successful prompt, tool call, workbook state change, formula readback, JSON export, and restart verification shape. Use the host rule chooser only when you need the exact instruction, rule, prompt, or MCP config file for Codex, Claude Code, GitHub Copilot, VS Code, Cursor, Kiro, Roo Code, Trae, Qodo IDE, Zed, Junie, OpenHands, OpenCode, Aider, Goose, Windsurf/Cascade, Cline, Continue, or Gemini CLI. Existing workbook file diagnostics live under Which Path Should I Install? and Choose An Evaluation Path; keep them separate from the default WorkPaper service path.

Project site: <https://proompteng.github.io/bilig/>

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 | input edit, recalculated output, serialized JSON, restore check, and verified: true. | | A tool host or MCP client needs workbook commands | MCP tool evaluator | tool discovery, cell edit, formula readback, export, restart check, and verified: true. | | You need the smallest proof for a specific tool host | Tool-host proof matrix | the shortest command or example for AI SDK, OpenAI, LangGraph, Semantic Kernel, MCP, or direct TypeScript. | | You need to see a successful tool-host run before adopting | Tool-host proof transcripts | prompt, tool call, workbook state change, formula readback, JSON export, and restart verification. | | A tool host needs the right repo rule or MCP config file | Host rule chooser | the exact Bilig file for Codex, Claude Code, Copilot, VS Code, Cursor, Kiro, Roo Code, Trae, Qodo IDE, Zed, Junie, OpenHands, OpenCode, Aider, Goose, Windsurf, Cline, Continue, or Gemini. | | A saved workbook file must remain the source of truth | Workbook Compatibility Report | unsupported functions, external links, macros, pivots, volatile formulas, and concrete 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 a saved workbook file is still the source of truth.

The default no-project check is:

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

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

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

Expected shape:

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

If a tool host or MCP client 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 before using it for irreversible workflows.

File import/export diagnostics are available when a saved workbook 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 | | A tool host or MCP client needs workbook tools with computed readback | npm install @bilig/workpaper | MCP tool evaluator | | A saved workbook file must remain the integration boundary | @bilig/xlsx-formula-recalc | Workbook Compatibility Report |

Advanced adapters are still available when the boundary is already specific: SheetJS, ExcelJS, external workbooks, tool integrations, @bilig/workbook when a runtime needs transport-neutral plan data and command receipts, and runtime provenance.

Tool Host And WorkPaper Proof

For tool-host handoff, use the WorkPaper host handoff: install the skill, run the no-key MCP evaluator, paste one workbook task into the host, and require verified: true before trusting the result. For tool hosts that want one install file, use llms-install.md.

Tool host? Do not start by driving Excel, LibreOffice, Google Sheets, or a browser grid. Use the WorkPaper proof instead: npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json. Then follow the MCP evaluator.

The published package also carries AGENTS.md and SKILL.md so tool hosts inspecting node_modules/@bilig/workpaper can find the write/read/persist loop locally. Cloned checkouts expose the same workflow through .mcp.json, .claude/skills/bilig-workpaper/SKILL.md, .claude/commands/bilig-workpaper-proof.md, .cursor/mcp.json, .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, .opencode/agents/bilig-workpaper.md, .vscode/mcp.json, and mcp/bilig-workpaper.mcp.json. The public docs expose the same host path through 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
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

Integration Recipes After The Proof

Run one core proof above before wiring a platform-specific integration. These recipes are for teams that already know where the workbook tool needs to live.

| Host or workflow runner | Use Bilig when... | Guide | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Open WebUI | A local or hosted tool server should expose workbook reads, writes, and formula readback. | Open WebUI WorkPaper tool setup | | LobeHub | A LobeHub agent needs a Custom MCP server for workbook tools. | LobeHub WorkPaper MCP setup | | AnythingLLM | Agent Skills should call hosted MCP or a private file-backed stdio server. | AnythingLLM WorkPaper MCP setup | | Sim | An Agent block or MCP Tool block should read, write, recalculate, and export proof. | Sim WorkPaper MCP setup | | FastMCP Python | A Python client should smoke-test hosted MCP or launch a private file-backed stdio WorkPaper. | FastMCP WorkPaper client | | Agno | MCPTools should import workbook tools and return verified formula readback before the workflow trusts the result. | Agno WorkPaper MCP tools | | Pydantic AI | MCPToolset should validate typed workbook proof before the workflow trusts spreadsheet-style calculations. | Pydantic AI WorkPaper MCP tools | | Google ADK | McpToolset should import workbook MCP tools and return verified formula readback before the ADK workflow trusts the result. | Google ADK WorkPaper MCP tools | | OpenHands | openhands mcp add should launch the file-backed WorkPaper server while .agents/skills teaches readback-first workbook edits. | OpenHands WorkPaper MCP setup | | Trae | .trae/mcp.json should register the Project MCP server while .trae/rules/bilig-workpaper.md keeps workbook proof work readback-first. | Trae WorkPaper MCP setup | | Qodo IDE | Qodo Agentic Tools should launch the local bilig-workpaper MCP server from pasted mcpServers JSON and keep proof tied to root AGENTS.md. | Qodo WorkPaper MCP setup | | OpenCode | opencode.jsonc should register the local WorkPaper MCP server while .opencode/agents keeps workbook proof work readback-first. | OpenCode WorkPaper MCP setup | | Zed | .zed/settings.json should register the project-local context_servers.bilig-workpaper server while AGENTS.md and the project skill keep workbook edits readback-first. | MCP client setup | | Microsoft Agent Framework | MCPStdioTool or MCPStreamableHTTPTool should import workbook MCP tools and verify dependent formula readback before the workflow trusts the result. | Microsoft Agent Framework WorkPaper MCP tools | | Goose | A Goose recipe should launch the file-backed WorkPaper MCP server and require formula readback, export, restore, and verified: true. | Goose WorkPaper MCP recipe | | Microsoft Semantic Kernel | MCPStdioPlugin should import workbook tools and verify dependent formula readback before the workflow trusts plugin calls. | Semantic Kernel WorkPaper MCP plugin | | OpenAI Agents SDK | tool(), MCPServerStdio, or MCPServerStreamableHttp should return computed WorkPaper readback before the workflow trusts workbook math. | OpenAI Agents SDK WorkPaper tools | | ChatGPT Apps / Developer Mode | A ChatGPT conversation should add Bilig as a no-auth remote MCP app before trying spreadsheet UI automation. | ChatGPT Apps WorkPaper MCP | | Proof chooser | A host integration or reviewer needs the smallest proof for WorkPaper service, MCP, AI SDK, OpenAI, LangGraph, Semantic Kernel, Mastra, ExcelJS, or XLSX. | Tool-host proof matrix | | Hugging Face smolagents | A Tool should return structured formula readback proof to a CodeAgent. | smolagents WorkPaper tool | | Hugging Face Gradio MCP Space | A Space template should expose one no-key WorkPaper readback tool before a team wires private workbook state. | Hugging Face Gradio MCP Space | | n8n, Dify, Flowise, Pipedream | Workflow builders need formula readback without spreadsheet UI automation; use @bilig/n8n-nodes-workpaper, the upstream merged Dify plugin, or the reviewed Pipedream action. | n8n, Dify, Flowise, Pipedream | | Vercel AI SDK | generateText() or streamText() tools need before/after/restore proof. | Vercel AI SDK WorkPaper tools | | LangGraph.js / LangChain MCP | ToolNode state should carry WorkPaper proof, or MCP adapters should discover workbook tools. | LangGraph, LangChain MCP example | | Windmill, Trigger.dev Durable Formula Tasks, Inngest | Durable workflow code should calculate fields from reviewable formulas. | Windmill, Trigger.dev, Inngest | | Airbyte, Meltano | Post-sync or post-ELT validation should return formula-backed record/state proof. | Airbyte, Meltano | | Temporal, Airflow, Dagster Formula Assets, Kestra, Prefect | Orchestrators should own retries/history while a Node step owns workbook proof. | Temporal, Airflow, Dagster, Kestra, Prefect | | Directus Persisted Calculated Fields | A custom operation should persist calculated fields with formula proof. | Directus WorkPaper Flow operation |

Choose An Evaluation Path

| If you are evaluating... | Start here | What should be true before you adopt | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Node service formulas | Node service WorkPaper evaluator | A starter writes one input, recalculates, persists JSON, restores, and prints verified: true. | | MCP tool contract | MCP workbook evaluator | MCP tool discovery, input edit, formula readback, persistence, and restart proof all pass. | | Tool-host proof chooser | Tool-host proof matrix, tool-host proof transcripts, MCP spreadsheet formula server, and Vercel AI SDK formula readback | The tool-host path starts with the smallest verified proof and avoids write-only or UI-only claims. | | Runtime intent adapters | Workbook runtime intent API and workbook-agent-model example | A model prepares transport-neutral plan data, strict runtime proof, command receipts, and check evidence. | | Basic fit | Why use Bilig? | The problem is workbook-shaped business logic that needs API readback and persistence. | | Published npm package | 90-second Node quickstart | @bilig/workpaper edits one input, recalculates, persists JSON, restores, and prints verified: true. | | Backend service shape | Quote approval WorkPaper API | A realistic route-style workflow returns formula readback and restoredMatchesAfter: true. | | Tool hosts or MCP clients | WorkPaper host handbook, MCP spreadsheet tool server, Gemini CLI extension, and Claude Desktop MCPB bundle | The host installs a tool path, uses the handoff prompt, then proves write/readback/persist. | | Technical WorkPaper review | WorkPaper maintainer proof note | One compact page has the npm check, benchmark caveat, known limits, and open questions. | | Trust and performance | npm provenance and benchmark evidence | npm shows SLSA provenance, and benchmark claims match the checked artifact. | | Saved workbook files | Workbook Compatibility Report, XLSX formula recalculation, and ExcelJS formula recalculation | 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 and submit a workbook fixture | 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 a tool host? Start with the host handoff prompt before opening Excel, LibreOffice, Google Sheets, or a screenshot UI. To prove the package-owned MCP loop without cloning the repo or downloading a TypeScript file:

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

Tool hosts that support skill manifests can start from skill.md or the well-known index at docs/.well-known/agent-skills/index.json. Claude Code reads the project skill from .claude/skills/bilig-workpaper/SKILL.md when the repo is cloned locally, and can invoke the explicit proof prompt from .claude/commands/bilig-workpaper-proof.md. Cursor and Windsurf/Cascade read the same proof loop from .cursor/rules/bilig-workpaper.mdc and the Cascade rule mirrors at .devin/rules/bilig-workpaper.md and .windsurf/rules/bilig-workpaper.md. Kiro reads the project steering file from .kiro/steering/bilig-workpaper.md and the project MCP server from .kiro/settings/mcp.json. Roo Code reads the project rule from .roo/rules/bilig-workpaper.md and the project MCP server from .roo/mcp.json. Trae reads the project rule from .trae/rules/bilig-workpaper.md and the Project MCP server from .trae/mcp.json. Zed reads the project context server from .zed/settings.json, then uses root AGENTS.md and .agents/skills/bilig-workpaper/SKILL.md for the same WorkPaper proof loop. Cline reads the workspace rule from .clinerules/bilig-workpaper.md. Continue reads the workspace rule from .continue/rules/bilig-workpaper.md and can launch direct WorkPaper tools from .continue/mcpServers/bilig-workpaper.yaml. Aider loads CONVENTIONS.md through .aider.conf.yml for the same WorkPaper proof loop. GitHub Copilot and VS Code agent mode read the repository instructions, prompt, and MCP servers from .github/copilot-instructions.md, .github/prompts/bilig-workpaper-proof.prompt.md, and .vscode/mcp.json. Gemini CLI users can install Bilig as an extension:

gemini extensions install https://github.com/proompteng/bilig --ref main

Claude Desktop users can also install the released MCPB bundle directly: <https://github.com/proompteng/bilig/releases/latest/download/bilig-workpaper.mcpb>. For another tool host, use the agent workbook challenge: one input edit, one dependent formula readback, one serialized restore, and a verified: true object.

Try It In 90 Seconds

This uses the published npm package. It builds a workbook, changes one input, reads the calculated value, saves JSON, restores the workbook, and prints the same value again.

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

Expected output includes these fields:

{
  "before": {
    "summary": {
      "decision": "review"
    },
    "inputCells": {
      "units": "Inputs!B2",
      "listPrice": "Inputs!B3"
    }
  },
  "edit": {
    "before": {
      "decision": "review"
    },
    "after": {
      "decision": "approved"
    },
    "restored": {
      "decision": "approved"
    },
    "checks": {
      "decisionChanged": true,
      "formulasPersisted": true,
      "restoredMatchesAfter": true,
      "serializedBytes": 1242
    }
  },
  "verified": true
}

The generated starter uses the same WorkPaper fields as the public mirror at <https://proompteng.github.io/bilig/npm-eval.ts> and examples/headless-workpaper/npm-eval.ts. The exact byte count can change between package versions; verified: true, decisionChanged, formulasPersisted, and restoredMatchesAfter are the checks.

For a route-shaped quote approval API today, run the maintained example:

git clone --depth 1 https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke

For a generated project from a blank directory, run npm create @bilig/workpaper@latest pricing-workpaper through the @bilig/create-workpaper package. The package source lives in packages/create-workpaper, and the publish gate is documented in create a Bilig WorkPaper starter. For an agent-ready project with AGENTS.md, CONVENTIONS.md, .aider.conf.yml, CLAUDE.md, GEMINI.md, Copilot / Cursor / Kiro / Roo Code / Trae / Zed / Junie / OpenHands / OpenCode / Aider / Cline / Continue / Windsurf rules, MCP client configs, and an agent:verify script, run npm create @bilig/workpaper@latest pricing-agent -- --agent. For an existing repo, run npm create @bilig/workpaper@latest . -- --add-agent; it adds Bilig agent and MCP instructions without replacing your app template or editing package.json. If an agent policy already exists, it writes BILIG_WORKPAPER_INSTALL.md with the skipped paths and a short handoff block.

If that proof almost matches a service or agent workflow you maintain, the useful next step is a concrete gap report in Discussions: formula coverage, service persistence, MCP setup, agent writeback, import/export boundary, or benchmark coverage.

TypeScript API Shape

Most integrations are just this: build a workbook, write an input, read the calculated value, and save the workbook state. When a workflow writes more than one input, use editManyAndReadback() so the edits are applied atomically and the proof compares typed readback values, persisted restore output, and formula diagnostics.

import { buildA1WorkPaper } from '@bilig/workpaper'

const book = buildA1WorkPaper({
  Inputs: [
    ['Metric', 'Value'],
    ['Customers', 20],
    ['Average revenue', 1200],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Revenue', '=Inputs!B2*Inputs!B3'],
  ],
})

const proof = book.editAndReadback('Inputs!B2', 32, {
  readbackRange: 'Summary!B2',
})

console.log({
  editedCell: proof.editedCell,
  revenue: proof.afterReadback.displayValues[0]?.[0],
  persistedDocumentBytes: proof.persistedDocumentBytes,
  verified: proof.verified,
})

book.dispose()

The lower-level WorkPaper runtime is still exported for engine integrations, but the A1 facade is the default service and agent path. Use book.set(), book.setMany(), book.readMany(), book.display(), and book.saveJson() when a full readback proof is not needed. Use book.editManyAndReadback() when several inputs should be committed and proven as one atomic workbook edit.

When To Reach For It

Use @bilig/workpaper when:

a Node service owns a workbook-shaped calculation;
an agent needs tools such as readRange and setInputCell, with computed

before/after values instead of screenshots;

tests need deterministic spreadsheet state and formula readback;
a workflow needs to save the edited workbook as JSON and restore it later.

Use something else when you need a visual spreadsheet grid, Office macros, desktop Excel automation, or a one-off arithmetic helper. Do not treat embedded XLSX stored formula results as truth; use the Excel oracle workflow when accuracy matters.

Package Boundary

Current checked npm metadata for @bilig/workpaper@latest:

Published package: 57.7 kB unpacked, 49 package entries.
Boundary: the public package owns WorkPaper starters, evaluators, MCP command

wrappers, formula clinic reports, JSON persistence, and restored readback.

Runtime: Node >=22.0.0; Node 22 compatibility is covered by the runtime

package workflow.

Published Package Trust

@bilig/workpaper is published with npm registry signatures and SLSA provenance attestations. Verify the package version you are about to adopt:

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

After installing, npm can verify the current dependency tree:

npm audit signatures

The current package trust path is documented in npm provenance and package trust. Repository security posture is tracked by OpenSSF Scorecard and uploaded to GitHub code scanning on every main update.

Deeper Evaluation Paths

After the first proof in Start Here, use the deeper guide that matches the next job.

Run the 90-second npm eval in a blank project.
Run the flagship

serverless WorkPaper API example: npm run quote-approval-api.

If the workflow starts with a saved workbook file, run the

XLSX formula recalculation in Node: npm start.

If a tool host needs workbook tools, start with the

headless WorkPaper host handbook, then use the MCP server guide when the caller is an MCP client.

If a real workbook almost works, start with the

formula bug clinic. Include the exact cell, expected value, actual value, and command output. If the fixture is already reduced, submit the structured fixture form so the blocker can become a test, example, or corpus case instead of private feedback. <https://github.com/proompteng/bilig/issues/new?template=workbook_fixture.yml>. If you are still reducing the case, discuss the shape first: <https://github.com/proompteng/bilig/discussions/414>.

The rest of the docs are an index, not a prerequisite.

For comparison and integration details, use the plain-language fit guide, screenshot automation boundary, Google Sheets API boundary, Google Sheets QUERY/SORTN in Node, workbook automation examples, the formula workbooks proof page, the Node spreadsheet formula engine guide, server-side spreadsheet automation, framework adapters, formula bug clinic, workbook fixture submissions, OpenAI Agents SDK tools, Browser Use formula tool, Google ADK MCP tools, OpenHands MCP setup, OpenCode MCP setup, Microsoft Agent Framework MCP tools, Goose MCP recipe, tool-host proof matrix, MCP spreadsheet formula server for tool hosts, Vercel AI SDK formula readback, AI SDK and LangChain tools, CrewAI adapter, the WorkPaper host handbook, the MCP server guide, spreadsheet MCP server comparison, MCP directory status, MCP client setup, Gemini CLI extension, FastMCP Python client, Claude Desktop MCPB bundle, npm provenance and package trust, JavaScript library comparison, Node spreadsheet formula engine guide, server-side spreadsheet automation, saved-workbook formula recalculation, XLSX formula support answers, SheetJS/ExcelJS boundary, ExcelJS formula result boundary, Microsoft Graph Excel boundary, and engine comparison.

Useful deeper examples: invoice totals, budget variance alerts, fulfillment capacity plan, quote approval threshold, subscription MRR forecast, agent framework adapters, MCP tool server shape, XLSX formula recalculation in Node, and serverless quote approval. Run npm run quote-approval-api, npm run agent:openai-agents-sdk, npm run agent:framework-adapters, npm run agent:mcp-tools, npm run agent:mcp-transcript, npm run agent:mcp-file-transcript, npm run agent:mcp-stdio, or npm exec --package @bilig/workpaper -- bilig-workpaper-mcp when that is the path you are evaluating.

Saved workbook diagnostics stay available when a file is the integration boundary:

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 --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc --demo --json
npm exec --package @bilig/sheetjs-formula-recalc@latest -- sheetjs-recalc --demo --json

The serverless example also includes npm run next-route-handler, npm run next-server-action, npm run next-server-action-formdata, npm run framework-adapters, and npm run persistence-adapters for framework-specific boundary checks.

The MCP server is also listed in the official registry: <https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper>. Clients that support Streamable HTTP MCP can also smoke-test the stateless hosted endpoint at https://bilig.proompteng.ai/mcp; use the local stdio server when the agent needs to persist a project WorkPaper JSON file.

Examples You Can Run

The runnable examples are TypeScript files. Some source imports end in .js because Node ESM resolves compiled package output that way; the files you edit and run are still .ts.

From a cloned checkout:

pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run start
pnpm --dir examples/headless-workpaper run json-records
pnpm --dir examples/headless-workpaper run csv-shaped
pnpm --dir examples/headless-workpaper run invoice-totals
pnpm --dir examples/headless-workpaper run budget-variance
pnpm --dir examples/headless-workpaper run fulfillment-capacity
pnpm --dir examples/headless-workpaper run quote-approval
pnpm --dir examples/headless-workpaper run subscription-mrr
pnpm --dir examples/headless-workpaper run persistence

The most useful entry points:

For tool integrations:

pnpm --dir examples/headless-workpaper run agent:verify
pnpm --dir examples/headless-workpaper run agent:tool-call
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk-mcp
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk-hosted-mcp
pnpm --dir examples/headless-workpaper run agent:openai-responses
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:framework-adapters
pnpm --dir examples/mastra-workpaper-tool run smoke
pnpm --dir examples/langgraph-workpaper-tool-state run smoke
pnpm --dir examples/langchain-mcp-workpaper-toolnode run smoke
pnpm --dir examples/headless-workpaper run agent:mcp-tools
pnpm --dir examples/headless-workpaper run agent:mcp-file-transcript
pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
pnpm --dir examples/headless-workpaper run agent:mcp-stdio

The AI SDK example uses ai-sdk-generate-text-tool-smoke.ts. The OpenAI Agents SDK guide is docs/openai-agents-sdk-workpaper-tool.md. It includes direct tool() wrapping, private MCPServerStdio discovery, and hosted stateless MCPServerStreamableHttp discovery through the WorkPaper MCP tool loop. The ChatGPT Apps Developer Mode setup is docs/chatgpt-apps-workpaper-mcp.md. It shows the public /mcp endpoint as a data/tool-only remote MCP app and keeps custom Apps SDK component UI as future scope. The OpenAI Responses guide is docs/openai-responses-workpaper-tool-call.md. The agent framework guide is docs/vercel-ai-sdk-langchain-spreadsheet-tool.md. The Mastra guide includes a real @mastra/core createTool() smoke: docs/mastra-workpaper-spreadsheet-tool.md. The LangGraph.js ToolNode proof is docs/langgraph-workpaper-toolnode-spreadsheet.md. It includes a no-key @langchain/mcp-adapters smoke that discovers the published WorkPaper MCP stdio tools and executes them through ToolNode.

The package also ships the MCP stdio binary:

npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells "Summary!B7,Inputs!B2"
npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp
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
pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
docker build --target bilig-workpaper-mcp -t bilig-workpaper-mcp:local .

bilig-agent-challenge prints the same edit, formula readback, WorkPaper JSON export, restore, and verified: true proof object used by the agent workbook challenge page.

bilig-mcp-challenge proves the file-backed MCP path end to end: initialize JSON-RPC, list tools/resources/prompts, edit Inputs!B3, read recalculated Summary!B3, export the WorkPaper JSON, restart from disk, and return verified: true.

bilig-formula-clinic imports a reduced XLSX locally, samples formulas, reads requested cells through WorkPaper, and prints a Markdown issue body. It does not upload workbook contents.

Without --workpaper, the binary starts the built-in demo workbook. With --workpaper, it loads your persisted WorkPaper JSON and 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; --writable persists set_cell_contents or set_cell_contents_and_readback edits back to the same file. If you already have an XLSX, --from-xlsx ./pricing.xlsx imports it into an in-memory WorkPaper server for readback, throwaway edits, and analyze_workbook_risk without writing a sidecar. Add `--workpaper ... --writab

bilig

bilig

Start Here

If You Only Try One Thing

Which Path Should I Install?

Tool Host And WorkPaper Proof

Integration Recipes After The Proof

Choose An Evaluation Path

Try It In 90 Seconds

TypeScript API Shape

When To Reach For It

Package Boundary

Published Package Trust

Deeper Evaluation Paths

Examples You Can Run

Related MCP servers

MCP servers by category