docs(examples): add Bilig WorkPaper MCP example

[gregkonush]

Summary

• Add examples/with-bilig-workpaper-mcp, a VoltAgent MCP example for formula-backed WorkPaper automation.
• Start @bilig/workpaper@0.90.8 through MCPConfiguration using stdio and a pinned npm exec --package command.
• Include a no-key pnpm proof script that calls the MCP tools directly, edits Inputs!B3, verifies recalculated Summary!B3, exports the WorkPaper document, and confirms restart readback.
• Add the example to examples/README.md.

Validation

• pnpm --filter voltagent-example-with-bilig-workpaper-mcp install --lockfile-only --ignore-scripts
• pnpm --dir examples/with-bilig-workpaper-mcp build
• pnpm --dir examples/with-bilig-workpaper-mcp proof
• pnpm exec biome check examples/with-bilig-workpaper-mcp/src/mcp.ts examples/with-bilig-workpaper-mcp/src/proof.ts examples/with-bilig-workpaper-mcp/src/index.ts examples/with-bilig-workpaper-mcp/tsconfig.json examples/with-bilig-workpaper-mcp/README.md examples/README.md
• git diff --check

The proof run discovers all seven Bilig MCP tools, changes the demo win rate input, reads Summary!B3 as 96000, and verifies persisted readback after reconnecting.

Notes

The example intentionally does not add @bilig/workpaper as a package dependency. The MCP command pins @bilig/workpaper@0.90.8 with npm exec, which matches the existing MCP example pattern and keeps the lockfile change limited to the new example importer.

---

Summary by cubic

Adds examples/with-bilig-workpaper-mcp, a VoltAgent example that connects to the Bilig WorkPaper MCP to edit inputs, recalc formulas, and verify persisted WorkPaper JSON. Includes a no-key pnpm proof that exercises MCP tools and confirms restart readback.

• New Features
  • Starts @bilig/workpaper@0.93.0 via MCPConfiguration (stdio) using pinned npm exec --package.
  • Proof: discovers 7 tools (incl. validate_formula), sets Inputs!B3 to 0.4, verifies Summary!B3 is 96000, validates a sample formula, exports the document, and prints discovered tools.
  • Adds .env.example, .gitignore, a runnable agent (pnpm dev), and links the example in examples/README.md.

^{Written for commit a4267af. Summary will update on new commits. Review in cubic}

Summary by CodeRabbit

• New Example

  • Added a complete Bilig WorkPaper MCP example demonstrating editing inputs, recalculating formulas, and verifying persisted JSON.

• Documentation

  • Included a step-by-step README with run/proof/agent instructions and expected outputs.

• Configuration

  • Added an environment placeholder for an OpenAI API key and common ignore patterns.

• Scripts & Proof

  • Added a proof script that exercises list/read/write/recalculate/export flows and validates results.

• Packaging & Tooling

  • Added package manifest and TypeScript config; updated the Bilig WorkPaper runtime to a newer patch.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a4267af

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7543bd8e-5160-4064-8718-b1bacc00476c

📥 Commits

Reviewing files that changed from the base of the PR and between 21f1c2f and a4267af.

📒 Files selected for processing (3)

• examples/with-bilig-workpaper-mcp/README.md
• examples/with-bilig-workpaper-mcp/src/mcp.ts
• examples/with-bilig-workpaper-mcp/src/proof.ts

✅ Files skipped from review due to trivial changes (1)

• examples/with-bilig-workpaper-mcp/src/mcp.ts

---

📝 Walkthrough

Walkthrough

Adds a new example demonstrating VoltAgent control of a Bilig WorkPaper via MCP: project scaffolding, MCP config (pinned @bilig/workpaper@0.93.0), an agent entrypoint that loads MCP tools, and a proof script that validates read/write/recalculate/persist workflows.

Changes

Bilig WorkPaper MCP Example

Layer / File(s)	Summary
Example registration and project scaffolding examples/README.md, examples/with-bilig-workpaper-mcp/package.json, examples/with-bilig-workpaper-mcp/tsconfig.json, examples/with-bilig-workpaper-mcp/.env.example, examples/with-bilig-workpaper-mcp/.gitignore, examples/with-bilig-workpaper-mcp/README.md	Adds the example to the main README and creates the example project with package manifest, TypeScript config, env template (OPENAI_API_KEY=your-openai-api-key), gitignore entries, and a full README describing run/proof/agent workflows.
MCP server configuration and initialization examples/with-bilig-workpaper-mcp/src/mcp.ts	Exports biligWorkPaperPackage = "@bilig/workpaper@0.93.0" and createBiligWorkPaperMcpConfig(workpaperPath?) which resolves pricing.workpaper.json and returns an MCPConfiguration launching bilig-workpaper-mcp via npm exec with --init-demo-workpaper and --writable.
Agent entrypoint and tool initialization examples/with-bilig-workpaper-mcp/src/index.ts	New entrypoint loads MCP tools, builds a Volt Agent with model openai/gpt-4o-mini, the toolset, and detailed instructions for reading/writing WorkPaper cells, then registers it in a VoltAgent.
Integration proof and validation examples/with-bilig-workpaper-mcp/src/proof.ts	Adds typed helpers for parsing tool outputs and runProof() which connects to MCP, ensures required tools exist, performs list/read/validate/write/read-display/export steps, verifies persistence and exported bytes, restarts the MCP connection, re-reads the cell to confirm persisted value, and emits a JSON success summary or sets process.exitCode = 1 on failure.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• omeraplak

Poem

🐰 I hopped through cells both old and new,
Wrote an input, watched the formulas stew,
Recalculated, then checked the file,
Exported proof with a happy smile—
Tiny hops, example ready for you.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(examples): add Bilig WorkPaper MCP example' clearly and concisely summarizes the main change—adding a new documentation example for Bilig WorkPaper MCP integration.
Description check	✅ Passed	The PR description is comprehensive and well-structured, covering what was added, validation steps performed, and important implementation details about the MCP configuration and proof script.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

examples/with-bilig-workpaper-mcp/src/proof.ts (1)

101-113: 💤 Low value

Redundant validation after findTool already checks.

The findTool call at line 106 already validates that tool.execute is a function (line 63). The check at lines 108-109 is redundant.

♻️ Proposed simplification

 async function callTool(
   tools: readonly ExecutableTool[],
   suffix: string,
   args: JsonRecord,
 ): Promise<JsonRecord> {
   const tool = findTool(tools, suffix);
-  const execute = tool.execute;
-  if (typeof execute !== "function") {
-    throw new Error(`Missing executable Bilig MCP tool: ${suffix}`);
-  }
-
-  return structuredContent(await execute(args), suffix);
+  return structuredContent(await tool.execute(args), suffix);
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/with-bilig-workpaper-mcp/src/proof.ts` around lines 101 - 113, The
check for execute being a function in callTool is redundant because findTool
already ensures tool.execute is callable; remove the typeof execute !==
"function" guard and its error throw, and simply invoke tool.execute(args) (or
await tool.execute(args)) and pass the result to structuredContent; reference
functions/classes: callTool, findTool, ExecutableTool, execute, and
structuredContent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@examples/with-bilig-workpaper-mcp/src/proof.ts`:
- Around line 101-113: The check for execute being a function in callTool is
redundant because findTool already ensures tool.execute is callable; remove the
typeof execute !== "function" guard and its error throw, and simply invoke
tool.execute(args) (or await tool.execute(args)) and pass the result to
structuredContent; reference functions/classes: callTool, findTool,
ExecutableTool, execute, and structuredContent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d069f606-18d1-4164-9153-22e3afa3d535

📥 Commits

Reviewing files that changed from the base of the PR and between 586fa6a and 089808f.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (9)

• examples/README.md
• examples/with-bilig-workpaper-mcp/.env.example
• examples/with-bilig-workpaper-mcp/.gitignore
• examples/with-bilig-workpaper-mcp/README.md
• examples/with-bilig-workpaper-mcp/package.json
• examples/with-bilig-workpaper-mcp/src/index.ts
• examples/with-bilig-workpaper-mcp/src/mcp.ts
• examples/with-bilig-workpaper-mcp/src/proof.ts
• examples/with-bilig-workpaper-mcp/tsconfig.json

[cubic-dev-ai]

No issues found across 10 files

_{Re-trigger cubic}