docs(examples): add Bilig WorkPaper MCP example

examples/README.md

@@ -116,6 +116,7 @@ Create a multi-agent research workflow where different AI agents collaborate to
 - [Langfuse](./with-langfuse) — Send traces and metrics to Langfuse for observability.
 - [Feedback Templates](./with-feedback) — Configure per-agent feedback templates for thumbs, numeric, and categorical feedback.
 - [Live Evals](./with-live-evals) — Run online evaluations against prompts/agents during development.
+- [Bilig WorkPaper (MCP)](./with-bilig-workpaper-mcp) — Edit formula-backed WorkPaper inputs, recalculate outputs, and verify persisted JSON through MCP tools.
 - [MCP Basics](./with-mcp) — Connect to MCP servers and call tools from an agent.
 - [MCP Elicitation](./with-mcp-elicitation) — Handle `elicitation/create` requests from MCP tools with per-request handlers.
 - [MCP Server](./with-mcp-server) — Implement and run a local MCP server that exposes custom tools.

examples/with-bilig-workpaper-mcp/.env.example

@@ -0,0 +1,2 @@
+OPENAI_API_KEY=your-openai-api-key
+

examples/with-bilig-workpaper-mcp/.gitignore

@@ -0,0 +1,6 @@
+.env
+.voltagent/
+dist/
+node_modules/
+pricing.workpaper.json
+

examples/with-bilig-workpaper-mcp/README.md

@@ -0,0 +1,40 @@
+# Bilig WorkPaper MCP
+
+Use VoltAgent with a local Bilig WorkPaper MCP server for formula-backed workbook automation. The example starts `@bilig/workpaper`, edits an input cell, recalculates dependent formulas, reads the computed result, and verifies persisted WorkPaper JSON.
+
+## Try Example
+
+```bash
+npm create voltagent-app@latest -- --example with-bilig-workpaper-mcp
+```
+
+## Run The Proof
+
+The proof script does not require an LLM key. It uses VoltAgent's `MCPConfiguration` to call the Bilig MCP tools directly.
+
+```bash
+pnpm install
+pnpm proof
+```
+
+Expected result:
+
+```json
+{
+  "ok": true,
+  "package": "@bilig/workpaper@0.154.0",
+  "recalculated": {
+    "summaryB3": 96000
+  },
+  "persisted": true
+}
+```
+
+## Run The Agent
+
+```bash
+cp .env.example .env
+pnpm dev
+```
+
+Open the VoltAgent console and ask the agent to inspect the workbook, set `Inputs!B3` to `0.4`, and verify `Summary!B3`. The important pattern is read, edit, recalculate, read back, and export the persisted WorkPaper document.

examples/with-bilig-workpaper-mcp/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "voltagent-example-with-bilig-workpaper-mcp",
+  "description": "VoltAgent example using Bilig WorkPaper MCP tools for formula-backed workbook readback.",
+  "version": "0.1.0",
+  "dependencies": {
+    "@voltagent/cli": "^0.1.21",
+    "@voltagent/core": "^2.7.5",
+    "@voltagent/internal": "^1.0.3",
+    "ai": "^6.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.2"
+  },
+  "main": "dist/index.js",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VoltAgent/voltagent.git",
+    "directory": "examples/with-bilig-workpaper-mcp"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch --env-file=.env ./src",
+    "proof": "tsx ./src/proof.ts",
+    "start": "node dist/index.js",
+    "volt": "volt"
+  },
+  "type": "module"
+}

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

@@ -0,0 +1,25 @@
+import VoltAgent, { Agent } from "@voltagent/core";
+import { biligWorkPaperPackage, createBiligWorkPaperMcpConfig } from "./mcp.js";
+
+const mcpConfig = createBiligWorkPaperMcpConfig();
+const tools = await mcpConfig.getTools();
+
+const agent = new Agent({
+  name: "Bilig WorkPaper Agent",
+  instructions: [
+    "You help users inspect and edit formula-backed WorkPaper files through MCP tools.",
+    `The configured server runs ${biligWorkPaperPackage}.`,
+    "Before changing a cell, list sheets and read the relevant input and output cells.",
+    "After set_cell_contents, verify the dependent result with read_cell or get_cell_display_value.",
+    "Do not claim success from a write alone; use recalculated readback and persisted JSON proof.",
+  ].join(" "),
+  model: "openai/gpt-4o-mini",
+  tools,
+  markdown: true,
+});
+
+new VoltAgent({
+  agents: {
+    agent,
+  },
+});

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

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { MCPConfiguration } from "@voltagent/core";
+
+export const biligWorkPaperPackage = "@bilig/workpaper@0.154.0";
+
+export function createBiligWorkPaperMcpConfig(
+  workpaperPath = path.resolve("pricing.workpaper.json"),
+) {
+  return new MCPConfiguration({
+    servers: {
+      bilig: {
+        type: "stdio",
+        command: "npm",
+        args: [
+          "exec",
+          "--yes",
+          "--package",
+          biligWorkPaperPackage,
+          "--",
+          "bilig-workpaper-mcp",
+          "--workpaper",
+          workpaperPath,
+          "--init-demo-workpaper",
+          "--writable",
+        ],
+      },
+    },
+  });
+}