Bilig MCP Server

bilig

Run workbook rules from Node, with formula readback you can verify.

Bilig is for workbook logic that has to run from code. If your service or agent should own the workbook model, start with @bilig/workpaper: edit cells, recalculate formulas, read outputs, and persist JSON. If an existing .xlsx file is still the contract, use the XLSX tools to find stale cached formula values and refresh readback.

Start with the boundary you actually have. Do not drive Excel, LibreOffice, Google Sheets, or a screenshot UI just to learn whether a formula value is fresh.

Run the no-clone checks:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
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 --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json

Evaluate a real workbook before integrating it:

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

The report lists unsupported functions, external links, VBA payloads, pivots, volatile formulas, stale cached formulas, and concrete risk reasons. It is not an Excel compatibility certification and does not print a compatibility score.

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

Need the full formula-cache report for a real workbook?

npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor pricing.xlsx --json
npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc pricing.xlsx --read Summary!B2 --out pricing.recalculated.xlsx --json

For pull requests with XLSX fixtures, start with the GitHub Action in report mode and let it show stale cached formulas before it blocks anything:

- uses: actions/setup-node@v6
  with:
    node-version: '22'
    package-manager-cache: false
- uses: proompteng/bilig@v1
  with:
    workbooks: '**/*.xlsx'
    changed-files-only: 'true'
    package-version: '0.164.1'
    fail-on-stale: 'false'

For TypeScript services that should own the workbook model:

npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify

For lower-level runtime imports:

npm install @bilig/headless

Direct diagnostic commands remain available:

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

Evaluator examples live in examples/bilig-evaluator-proof. Agent and framework evaluators are ranked in the Agent WorkPaper proof matrix. The agent proof transcripts show the successful prompt, tool call, workbook state change, formula readback, JSON export, and restart verification shape. The XLSX Cache Doctor proof transcript shows the stale cached formula value, recalculated value, exact cell address, and suggested read target before a service or CI job trusts a saved workbook. The Workbook Compatibility Report shows the local risk report for an actual .xlsx before a Node service or coding agent trusts Bilig with it. Use the coding agent rule chooser 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.

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

Start Here

Pick the path that matches the job:

If you are not sure which one fits, start with the thing that owns state. Use WorkPaper when your service or agent should own the workbook model. Use the XLSX path when a saved Excel file is still the source of truth.

The shortest no-project checks are:

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 --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json
npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc --demo --json

Good fits: pricing, quote approval, payout checks, import validation, forecasts, CI fixtures, formula-backed workflow steps, and coding agents 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.

The canonical XLSX guide is Fix stale XLSX formula values in Node.js. If you need to choose among XLSX, SheetJS, ExcelJS, xlsx-populate, CI, WorkPaper, and agent proof paths, use the stale formula readback chooser. If you are answering a public SheetJS, ExcelJS, xlsx-populate, template, or CI question, use the non-spam XLSX formula support answers first. For a direct before/after proof across SheetJS, xlsx-populate, and ExcelJS:

npm --prefix examples/recalc-bridge-workflows install
npm --prefix examples/recalc-bridge-workflows run smoke

For the GitHub Action listing and a live reviewer path:

• https://github.com/marketplace/actions/xlsx-cache-doctor
• https://github.com/proompteng/xlsx-cache-doctor-demo/pull/1

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 an agent or MCP client owns the workflow, run the agent door:

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

If an existing XLSX file is still the contract, run the XLSX cache door:

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --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.
• The XLSX cache doctor is diagnostic by default. It only blocks pull requests when you opt into fail-on-stale.

For linked workbooks, use the external workbook recalculation proof. For stale cached XLSX values, use Evaluate stale XLSX formula caches. For a copyable terminal transcript, use the XLSX Cache Doctor proof transcript. For a narrower recalculation evaluator, use Evaluate XLSX formula recalculation.

If you already have the real workbook but do not know which formulas to read yet, inspect it first without writing an output file:

npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor pricing.xlsx --json

That checks every formula by default, reports any skipped formulas as uninspectedFormulaCellCount, returns stale cached values, and suggests --read targets so the next command can prove the cells your service actually depends on.

If your service or test runner needs the same report without a subprocess, use the Node API:

import { readFile } from 'node:fs/promises'
import { inspectXlsxCache } from '@bilig/xlsx-formula-recalc'

const report = inspectXlsxCache(await readFile('pricing.xlsx'), {
  fileName: 'pricing.xlsx',
})

if (report.staleCachedFormulaCount > 0) {
  throw new Error(
    report.formulas
      .filter((formula) => formula.cacheStatus === 'stale')
      .map((formula) => formula.target)
      .join(', '),
  )
}

To run that check in CI, install XLSX Cache Doctor from GitHub Marketplace, read the GitHub Action guide, or copy the runnable example at examples/xlsx-cache-doctor-ci. The proof transcript shows the same cached-vs-recalculated value shape in one page. For a live reviewer path, inspect the demo pull request: it runs proompteng/bilig@v1, proves 60 formula cells were inspected, finds 1 stale cached formula value, and uploads the JSON report.

To generate the pull-request workflow instead of hand-writing YAML:

mkdir -p .github/workflows
npm exec --package @bilig/xlsx-formula-recalc@latest -- \
  xlsx-cache-doctor --print-github-action "**/*.xlsx" \
  > .github/workflows/xlsx-cache-doctor.yml

The generated workflow is read-only and report-only by default. Add --fail-on-stale true when you want stale cached values to block pull requests, or pass --inspect-limit, --json-output, or --markdown-output to match your CI artifact policy. The Action uploads machine-readable JSON and a human-readable Markdown report path, so reviewers can inspect the stale cells without giving the detector write permissions.

If your pipeline is specifically SheetJS / xlsx, run the sibling proof with the same shape:

npm exec --package @bilig/sheetjs-formula-recalc@latest -- sheetjs-recalc --demo --json

If the workbook is already in ExcelJS, keep that boundary and add @bilig/exceljs-formula-recalc:

npm install exceljs @bilig/exceljs-formula-recalc
npm exec --package @bilig/exceljs-formula-recalc@latest -- exceljs-recalc --demo --json

For one checkout proof across SheetJS/xlsx, xlsx-populate, and ExcelJS:

npm --prefix examples/recalc-bridge-workflows install
npm --prefix examples/recalc-bridge-workflows run smoke

That bridge proof is the fastest way to check whether Bilig solves the stale formula-value problem without asking you to adopt WorkPaper state first.

Which Path Should I Install?

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

Agent And WorkPaper Proof

For agent adoption, use the Agent Adoption Kit: install the skill, run the no-key agent MCP evaluator, paste one workbook task into the agent, and require verified: true before trusting the result. For marketplace reviewers and agent hosts that want one copyable install file, use llms-install.md.

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

The published package also carries AGENTS.md and SKILL.md so coding agents 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 agent 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.

Documentation truncated — see the full README on GitHub.