@bilig/workpaper 0.131.1 → 0.131.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/README.md +56 -34
- package/SKILL.md +27 -20
- package/package.json +10 -13
- package/server.json +2 -2
package/AGENTS.md
CHANGED
|
@@ -6,7 +6,7 @@ Use this file when an AI coding agent, MCP client, or tool host needs workbook f
|
|
|
6
6
|
|
|
7
7
|
1. Read `https://proompteng.github.io/bilig/llms.txt` for the compact map.
|
|
8
8
|
2. Read `https://proompteng.github.io/bilig/llms-full.txt` when you need enough context to implement a workflow without searching the whole site.
|
|
9
|
-
3. Use `https://proompteng.github.io/bilig/agent-adoption-kit.html` when you need the shortest no-key install, MCP proof, and
|
|
9
|
+
3. Use `https://proompteng.github.io/bilig/agent-adoption-kit.html` when you need the shortest no-key install, MCP proof, and workbook task.
|
|
10
10
|
4. If your host can install skills from a well-known endpoint, run
|
|
11
11
|
`npx --yes skills@latest add https://bilig.proompteng.ai --list`.
|
|
12
12
|
5. Read `https://bilig.proompteng.ai/.well-known/agent-skills/bilig-workpaper/SKILL.txt` when your agent supports skill manifests.
|
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# @bilig/workpaper
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas
|
|
4
|
+
in Node.js services and agents.
|
|
4
5
|
|
|
5
6
|
Use this when business logic is easiest to review as workbook cells and
|
|
6
7
|
formulas, but the calculation needs to run in a backend service, queue worker,
|
|
@@ -17,31 +18,52 @@ npm install @bilig/workpaper
|
|
|
17
18
|
|
|
18
19
|
## Start Here
|
|
19
20
|
|
|
20
|
-
Pick the
|
|
21
|
-
|
|
22
|
-
|
|
|
23
|
-
|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
21
|
+
Pick the door that matches the state you own:
|
|
22
|
+
|
|
23
|
+
| Door | Run first | What it proves |
|
|
24
|
+
| -------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
25
|
+
| 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`. |
|
|
26
|
+
| 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`. |
|
|
27
|
+
| 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. |
|
|
28
|
+
|
|
29
|
+
If one of those matches your workflow, keep Bilig nearby:
|
|
30
|
+
<https://github.com/proompteng/bilig>. Watch releases if this is close to a
|
|
31
|
+
production dependency: <https://github.com/proompteng/bilig/subscription>.
|
|
32
|
+
|
|
33
|
+
Framework examples live in the repo instead of this first screen. Start with
|
|
34
|
+
the closest runtime:
|
|
35
|
+
|
|
36
|
+
- Agent tools: Vercel AI SDK, LangGraph, LangChain MCP adapters, Open WebUI,
|
|
37
|
+
FastMCP, smolagents.
|
|
38
|
+
- Workflow engines: Trigger.dev, Inngest, Temporal, Airflow, Dagster, Kestra,
|
|
39
|
+
Prefect, Windmill.
|
|
40
|
+
- Low-code and data tools: n8n, Pipedream, Directus, Airbyte, Meltano.
|
|
41
|
+
- Existing `.xlsx` files: use `@bilig/xlsx-formula-recalc` for stale formula
|
|
42
|
+
caches and exported workbook readback.
|
|
43
|
+
|
|
44
|
+
## Searchable Example Guides
|
|
45
|
+
|
|
46
|
+
These are integration guide names that users search for on npm. They are links,
|
|
47
|
+
not the first-run path:
|
|
48
|
+
|
|
49
|
+
| Guide need | Start here |
|
|
50
|
+
| ------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
51
|
+
| Windmill TypeScript workflow fields | <https://proompteng.github.io/bilig/windmill-workpaper-script.html> |
|
|
52
|
+
| Trigger.dev durable task fields | <https://proompteng.github.io/bilig/triggerdev-workpaper-task.html> |
|
|
53
|
+
| Inngest durable step fields | <https://proompteng.github.io/bilig/inngest-workpaper-step.html> |
|
|
54
|
+
| Temporal TypeScript Activity decisions | <https://proompteng.github.io/bilig/temporal-workpaper-activity.html> |
|
|
55
|
+
| Apache Airflow DAG task outputs | <https://proompteng.github.io/bilig/airflow-workpaper-dag.html> |
|
|
56
|
+
| Dagster asset materialization metadata | <https://proompteng.github.io/bilig/dagster-workpaper-asset.html> |
|
|
57
|
+
| Kestra Node Commands flow fields | <https://proompteng.github.io/bilig/kestra-workpaper-flow.html> |
|
|
58
|
+
| Prefect flow fields | <https://proompteng.github.io/bilig/prefect-workpaper-flow.html> |
|
|
59
|
+
| Directus Flow operation for persisted calculated fields | <https://proompteng.github.io/bilig/directus-workpaper-flow-operation.html> |
|
|
60
|
+
| n8n formula readback for self-hosted workflows | <https://proompteng.github.io/bilig/n8n-workpaper-formula-readback.html> |
|
|
61
|
+
| Dify formula readback | <https://proompteng.github.io/bilig/dify-workpaper-formula-readback.html> |
|
|
62
|
+
| Flowise formula readback | <https://proompteng.github.io/bilig/flowise-workpaper-formula-readback.html> |
|
|
63
|
+
| Pipedream formula readback | <https://proompteng.github.io/bilig/pipedream-workpaper-formula-readback.html> |
|
|
64
|
+
| FastMCP Python client for hosted and local stdio checks | <https://proompteng.github.io/bilig/fastmcp-workpaper-client.html> |
|
|
65
|
+
| Hugging Face smolagents tool | <https://proompteng.github.io/bilig/smolagents-workpaper-tool.html> |
|
|
66
|
+
| Hugging Face Gradio MCP Space | <https://proompteng.github.io/bilig/huggingface-workpaper-space.html> |
|
|
45
67
|
|
|
46
68
|
## Use A WorkPaper In Node
|
|
47
69
|
|
|
@@ -148,10 +170,9 @@ The mutating tool returns `editedCell`, `before`, `after`, `restored`, and
|
|
|
148
170
|
`checks`. Keep `writableSheets` narrow so the model can edit inputs without
|
|
149
171
|
rewriting formula sheets.
|
|
150
172
|
|
|
151
|
-
##
|
|
173
|
+
## Verify Without Cloning
|
|
152
174
|
|
|
153
|
-
The package ships
|
|
154
|
-
coding agents and service evaluators:
|
|
175
|
+
The package ships evaluator and direct proof commands:
|
|
155
176
|
|
|
156
177
|
```sh
|
|
157
178
|
npm exec --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json
|
|
@@ -163,7 +184,7 @@ npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./
|
|
|
163
184
|
```
|
|
164
185
|
|
|
165
186
|
`bilig-evaluate` prints a `bilig-evaluator.v1` object with `door`, `evidence`,
|
|
166
|
-
`verified`, `limitations`, and the
|
|
187
|
+
`verified`, `limitations`, and the source command output.
|
|
167
188
|
|
|
168
189
|
The challenge commands edit one input, recalculate dependent formulas, export
|
|
169
190
|
WorkPaper JSON, restore it, and print a `verified: true` proof object.
|
|
@@ -177,12 +198,13 @@ instead:
|
|
|
177
198
|
```sh
|
|
178
199
|
npx --yes skills@latest add https://bilig.proompteng.ai --list
|
|
179
200
|
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
|
|
180
|
-
npm exec --package @bilig/workpaper@latest -- bilig-mcp
|
|
201
|
+
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
|
|
181
202
|
```
|
|
182
203
|
|
|
183
|
-
The kit gives the agent one path: install the instructions, run the no-key
|
|
184
|
-
|
|
185
|
-
state before reporting success.
|
|
204
|
+
The kit gives the agent one path: install the instructions, run the no-key
|
|
205
|
+
agent evaluator, paste a workbook edit task, and require computed readback plus
|
|
206
|
+
persisted state before reporting success. Use `bilig-mcp-challenge --json` only
|
|
207
|
+
when debugging the lower-level MCP transcript.
|
|
186
208
|
|
|
187
209
|
Docs: <https://proompteng.github.io/bilig/agent-adoption-kit.html>
|
|
188
210
|
|
package/SKILL.md
CHANGED
|
@@ -24,7 +24,7 @@ Trigger this skill for tasks involving:
|
|
|
24
24
|
- quote, budget, payout, pricing, import-validation, or forecast models;
|
|
25
25
|
- agent spreadsheet tools that need deterministic cell addresses;
|
|
26
26
|
- MCP clients that can run a stdio server or call a Streamable HTTP endpoint;
|
|
27
|
-
- reduced XLSX formula bugs that need a
|
|
27
|
+
- reduced XLSX formula bugs that need a local report.
|
|
28
28
|
|
|
29
29
|
Do not trigger it for manual spreadsheet editing, Office macros, VBA, pivots, charts, COM automation, or exact Excel desktop behavior unless the user explicitly asks to compare Bilig against an Excel oracle.
|
|
30
30
|
|
|
@@ -32,6 +32,28 @@ Do not trigger it for manual spreadsheet editing, Office macros, VBA, pivots, ch
|
|
|
32
32
|
|
|
33
33
|
Do not build shell commands by concatenating user text. Treat the commands below as literal templates, validate workbook paths before use, and reject values containing newlines, backticks, `$(`, `;`, `&`, `|`, `<`, or `>`. Prefer MCP client `command` plus `args` arrays or direct TypeScript calls when inserting user-provided paths or cell references.
|
|
34
34
|
|
|
35
|
+
## First Check: Agent Evaluator
|
|
36
|
+
|
|
37
|
+
Before wiring a client, prove the published agent door with the package-owned evaluator.
|
|
38
|
+
It exercises MCP discovery, cell mutation, formula readback, JSON export, restart restore, and returns `verified: true`:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"command": "npm",
|
|
43
|
+
"args": ["exec", "--yes", "--package", "@bilig/workpaper@latest", "--", "bilig-evaluate", "--door", "agent-mcp", "--json"]
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
For service-owned WorkPaper logic without MCP, run `bilig-evaluate --door workpaper-service --json`.
|
|
48
|
+
Use the lower-level challenge commands only when debugging the direct API loop or file-backed MCP JSON-RPC transcript:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
[
|
|
52
|
+
{ "command": "npm", "args": ["exec", "--package", "@bilig/workpaper@latest", "--", "bilig-agent-challenge", "--json"] },
|
|
53
|
+
{ "command": "npm", "args": ["exec", "--package", "@bilig/workpaper@latest", "--", "bilig-mcp-challenge", "--json"] }
|
|
54
|
+
]
|
|
55
|
+
```
|
|
56
|
+
|
|
35
57
|
## First Choice: MCP
|
|
36
58
|
|
|
37
59
|
Use MCP when the host can run a stdio server or call a Streamable HTTP server.
|
|
@@ -45,24 +67,6 @@ npx --yes skills@latest add https://bilig.proompteng.ai --list
|
|
|
45
67
|
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
|
|
46
68
|
```
|
|
47
69
|
|
|
48
|
-
Before wiring a client, an agent can check the direct WorkPaper loop with:
|
|
49
|
-
|
|
50
|
-
```json
|
|
51
|
-
{
|
|
52
|
-
"command": "npm",
|
|
53
|
-
"args": ["exec", "--package", "@bilig/workpaper@latest", "--", "bilig-agent-challenge", "--json"]
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
For the actual file-backed MCP path, run the package-owned challenge first:
|
|
58
|
-
|
|
59
|
-
```json
|
|
60
|
-
{
|
|
61
|
-
"command": "npm",
|
|
62
|
-
"args": ["exec", "--package", "@bilig/workpaper@latest", "--", "bilig-mcp-challenge", "--json"]
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
70
|
```json
|
|
67
71
|
{
|
|
68
72
|
"command": "npm",
|
|
@@ -80,13 +84,15 @@ For the actual file-backed MCP path, run the package-owned challenge first:
|
|
|
80
84
|
}
|
|
81
85
|
```
|
|
82
86
|
|
|
83
|
-
Run `bilig-
|
|
87
|
+
Run `bilig-evaluate --door agent-mcp --json` first. If the evaluator fails,
|
|
88
|
+
run `bilig-mcp-challenge` and treat its returned `tools` array as the source
|
|
84
89
|
of truth for the currently published package. The core file-backed tools are:
|
|
85
90
|
|
|
86
91
|
- `list_sheets`
|
|
87
92
|
- `read_range`
|
|
88
93
|
- `read_cell`
|
|
89
94
|
- `set_cell_contents`
|
|
95
|
+
- `set_cell_contents_and_readback`
|
|
90
96
|
- `get_cell_display_value`
|
|
91
97
|
- `export_workpaper_document`
|
|
92
98
|
- `validate_formula`
|
|
@@ -189,6 +195,7 @@ If any readback step fails, report the blocker instead of claiming the workbook
|
|
|
189
195
|
- Sim MCP setup: https://proompteng.github.io/bilig/sim-workpaper-mcp.html
|
|
190
196
|
- FastMCP Python client: https://proompteng.github.io/bilig/fastmcp-workpaper-client.html
|
|
191
197
|
- smolagents WorkPaper tool: https://proompteng.github.io/bilig/smolagents-workpaper-tool.html
|
|
198
|
+
- Hugging Face WorkPaper Space template: https://proompteng.github.io/bilig/huggingface-workpaper-space.html
|
|
192
199
|
- Windmill TypeScript script: https://proompteng.github.io/bilig/windmill-workpaper-script.html
|
|
193
200
|
- Trigger.dev task: https://proompteng.github.io/bilig/triggerdev-workpaper-task.html
|
|
194
201
|
- Inngest step: https://proompteng.github.io/bilig/inngest-workpaper-step.html
|
package/package.json
CHANGED
|
@@ -1,35 +1,32 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bilig/workpaper",
|
|
3
|
-
"version": "0.131.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.131.3",
|
|
4
|
+
"description": "WorkPaper API, CLI evaluator, and MCP server for headless spreadsheet formulas in Node.js services and agents.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent-tools",
|
|
7
7
|
"ai-agents",
|
|
8
8
|
"bilig",
|
|
9
|
-
"bilig-workpaper",
|
|
10
|
-
"excel",
|
|
11
9
|
"excel-formulas",
|
|
12
|
-
"exceljs",
|
|
13
10
|
"formula-engine",
|
|
14
|
-
"formula-recalculation",
|
|
15
11
|
"headless-spreadsheet",
|
|
16
12
|
"mcp",
|
|
17
13
|
"mcp-server",
|
|
18
14
|
"model-context-protocol",
|
|
19
15
|
"node",
|
|
16
|
+
"node-spreadsheet",
|
|
17
|
+
"node-spreadsheet-formulas",
|
|
18
|
+
"server-side-formula-engine",
|
|
20
19
|
"server-side-spreadsheet",
|
|
21
|
-
"sheetjs",
|
|
22
20
|
"spreadsheet",
|
|
23
21
|
"spreadsheet-agent",
|
|
24
22
|
"spreadsheet-automation",
|
|
25
23
|
"spreadsheet-engine",
|
|
24
|
+
"spreadsheet-formula-engine",
|
|
26
25
|
"spreadsheet-formulas",
|
|
27
26
|
"workbook",
|
|
28
27
|
"workbook-agent",
|
|
29
|
-
"workbook-api",
|
|
30
28
|
"workpaper",
|
|
31
|
-
"xlsx"
|
|
32
|
-
"xlsx-calc"
|
|
29
|
+
"xlsx"
|
|
33
30
|
],
|
|
34
31
|
"homepage": "https://proompteng.github.io/bilig/",
|
|
35
32
|
"bugs": {
|
|
@@ -91,9 +88,9 @@
|
|
|
91
88
|
"build": "pnpm --dir ../.. --filter bilig-workpaper build && rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
|
|
92
89
|
},
|
|
93
90
|
"dependencies": {
|
|
94
|
-
"@bilig/headless": "0.131.
|
|
95
|
-
"@bilig/xlsx-formula-recalc": "0.131.
|
|
96
|
-
"bilig-workpaper": "0.131.
|
|
91
|
+
"@bilig/headless": "0.131.3",
|
|
92
|
+
"@bilig/xlsx-formula-recalc": "0.131.3",
|
|
93
|
+
"bilig-workpaper": "0.131.3"
|
|
97
94
|
},
|
|
98
95
|
"devDependencies": {
|
|
99
96
|
"ai": "6.0.182",
|
package/server.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"name": "io.github.proompteng/bilig-workpaper",
|
|
4
4
|
"title": "Bilig WorkPaper",
|
|
5
5
|
"description": "WorkPaper MCP tools, resources, and prompts for readback, edits, and JSON persistence.",
|
|
6
|
-
"version": "0.131.
|
|
6
|
+
"version": "0.131.3",
|
|
7
7
|
"repository": {
|
|
8
8
|
"url": "https://github.com/proompteng/bilig",
|
|
9
9
|
"source": "github"
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
{
|
|
19
19
|
"registryType": "npm",
|
|
20
20
|
"identifier": "@bilig/workpaper",
|
|
21
|
-
"version": "0.131.
|
|
21
|
+
"version": "0.131.3",
|
|
22
22
|
"transport": {
|
|
23
23
|
"type": "stdio"
|
|
24
24
|
}
|