@casys/mcp-erpnext 2.2.1 → 2.3.0

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.
Files changed (10) hide show
  1. package/README.md +97 -55
  2. package/mcp-erpnext.mjs +2351 -3363
  3. package/package.json +1 -1
  4. package/ui-dist/chart-viewer/index.html +91 -65
  5. package/ui-dist/doclist-viewer/index.html +61 -35
  6. package/ui-dist/funnel-viewer/index.html +64 -38
  7. package/ui-dist/invoice-viewer/index.html +65 -39
  8. package/ui-dist/kanban-viewer/index.html +65 -39
  9. package/ui-dist/kpi-viewer/index.html +64 -38
  10. package/ui-dist/stock-viewer/index.html +65 -39
package/README.md CHANGED
@@ -1,26 +1,37 @@
1
1
  # @casys/mcp-erpnext
2
2
 
3
- MCP server for [ERPNext](https://erpnext.com) / Frappe ERP — **120 tools** across **14 categories**, with **7 interactive UI viewers**.
3
+ MCP server for [ERPNext](https://erpnext.com) / Frappe ERP — **120 tools**
4
+ across **14 categories**, with **7 interactive UI viewers**.
4
5
 
5
- Connect any MCP-compatible AI agent (Claude Desktop, Claude Code, VS Code Copilot, custom) to your ERPNext instance via the [Model Context Protocol](https://modelcontextprotocol.io).
6
+ Connect any MCP-compatible AI agent (Claude Desktop, Claude Code, VS Code
7
+ Copilot, custom) to your ERPNext instance via the
8
+ [Model Context Protocol](https://modelcontextprotocol.io).
6
9
 
7
10
  Works with **self-hosted** and **ERPNext Cloud** (frappe.cloud) instances.
8
11
 
9
12
  ## What's New in v2.1
10
13
 
11
- - **Cross-viewer navigation** — click a row in any list to drill down, click a button to open related documents in another viewer via `sendMessage`
12
- - **Inline detail panels** — expand any row in doclist/stock viewers to see full document details + action buttons (Submit, Cancel, Payments)
13
- - **Interactive charts** — click bar/pie/line data points to drill into underlying documents
14
- - **KPI drill-down** — click the big number or sparkline to explore exceptions or trends
15
- - **Funnel redesign** — trapezoid stages with gradient fills, conversion badges, click-through navigation
16
- - **Better error messages** — Frappe API errors are now surfaced with full detail instead of generic "Tool execution failed"
17
- - **VS Code Copilot fix** — schema validation issue with `erpnext_doc_list` filters resolved (#2)
14
+ - **Cross-viewer navigation** — click a row in any list to drill down, click a
15
+ button to open related documents in another viewer via `sendMessage`
16
+ - **Inline detail panels** — expand any row in doclist/stock viewers to see full
17
+ document details + action buttons (Submit, Cancel, Payments)
18
+ - **Interactive charts** — click bar/pie/line data points to drill into
19
+ underlying documents
20
+ - **KPI drill-down** — click the big number or sparkline to explore exceptions
21
+ or trends
22
+ - **Funnel redesign** — trapezoid stages with gradient fills, conversion badges,
23
+ click-through navigation
24
+ - **Better error messages** — Frappe API errors are now surfaced with full
25
+ detail instead of generic "Tool execution failed"
26
+ - **VS Code Copilot fix** — schema validation issue with `erpnext_doc_list`
27
+ filters resolved (#2)
18
28
 
19
29
  ## Quick Start
20
30
 
21
31
  ### Prerequisites
22
32
 
23
33
  Generate API credentials in ERPNext:
34
+
24
35
  1. Login to ERPNext → top-right menu → **My Settings**
25
36
  2. Section **API Access** → **Generate Keys**
26
37
  3. Copy `API Key` and `API Secret`
@@ -43,7 +54,9 @@ Generate API credentials in ERPNext:
43
54
  }
44
55
  ```
45
56
 
46
- > **Works with ERPNext Cloud** — set `ERPNEXT_URL` to your Frappe Cloud URL (e.g. `https://mycompany.erpnext.com` or `https://mysite.frappe.cloud`). API key authentication works the same way on self-hosted and cloud instances.
57
+ > **Works with ERPNext Cloud** — set `ERPNEXT_URL` to your Frappe Cloud URL
58
+ > (e.g. `https://mycompany.erpnext.com` or `https://mysite.frappe.cloud`). API
59
+ > key authentication works the same way on self-hosted and cloud instances.
47
60
 
48
61
  > Zero dependencies — single self-contained bundle. Requires Node >= 20.
49
62
 
@@ -105,7 +118,8 @@ npx -y @casys/mcp-erpnext --categories=sales,inventory
105
118
 
106
119
  ## Fresh Instance Setup
107
120
 
108
- On a fresh ERPNext instance (no setup wizard), you need to create master data before using business tools. Use `erpnext_doc_create` for prerequisites:
121
+ On a fresh ERPNext instance (no setup wizard), you need to create master data
122
+ before using business tools. Use `erpnext_doc_create` for prerequisites:
109
123
 
110
124
  ```
111
125
  1. Warehouse Types: Transit, Default
@@ -119,30 +133,39 @@ On a fresh ERPNext instance (no setup wizard), you need to create master data be
119
133
 
120
134
  ## UI Viewers
121
135
 
122
- Seven interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) viewers, registered as `ui://mcp-erpnext/{name}`:
136
+ Seven interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
137
+ viewers, registered as `ui://mcp-erpnext/{name}`:
123
138
 
124
- | Viewer | Description | Interactive Features |
125
- |--------|-------------|---------------------|
139
+ | Viewer | Description | Interactive Features |
140
+ | ---------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
126
141
  | `doclist-viewer` | Generic document table with sort, filter, pagination, CSV export | Row click → inline detail panel with Submit/Cancel + sendMessage navigation. Chip filters for status columns. Max 6 columns, rest in detail panel. |
127
- | `invoice-viewer` | Sales/Purchase Invoice with parties, items, totals | Item click → stock balance + item info panel. Submit/Cancel/Payment actions. sendMessage to payment entries and customer invoices. |
128
- | `stock-viewer` | Stock balance table with color-coded qty badges | Row click → item info + recent movements. sendMessage to stock chart, item details, stock entries. |
129
- | `chart-viewer` | Universal chart renderer (12 types via Recharts) | Click bar/pie/line data points → sendMessage drill-down into underlying documents. |
130
- | `kanban-viewer` | Read-write kanban for Task, Opportunity, Issue | Drag-and-drop moves, inline edit (priority, progress, dates), sendMessage to Timesheets/Quotations/Related docs. |
131
- | `kpi-viewer` | Big number card with delta, sparkline, trend | Click number → sendMessage to exception list. Click sparkline → trend chart. |
132
- | `funnel-viewer` | Trapezoid sales funnel with conversion rates | Click stage → sendMessage to document list at that stage. Stage action buttons. |
142
+ | `invoice-viewer` | Sales/Purchase Invoice with parties, items, totals | Item click → stock balance + item info panel. Submit/Cancel/Payment actions. sendMessage to payment entries and customer invoices. |
143
+ | `stock-viewer` | Stock balance table with color-coded qty badges | Row click → item info + recent movements. sendMessage to stock chart, item details, stock entries. |
144
+ | `chart-viewer` | Universal chart renderer (12 types via Recharts) | Click bar/pie/line data points → sendMessage drill-down into underlying documents. |
145
+ | `kanban-viewer` | Read-write kanban for Task, Opportunity, Issue | Drag-and-drop moves, inline edit (priority, progress, dates), sendMessage to Timesheets/Quotations/Related docs. |
146
+ | `kpi-viewer` | Big number card with delta, sparkline, trend | Click number → sendMessage to exception list. Click sparkline → trend chart. |
147
+ | `funnel-viewer` | Trapezoid sales funnel with conversion rates | Click stage → sendMessage to document list at that stage. Stage action buttons. |
133
148
 
134
149
  ### Cross-viewer navigation
135
150
 
136
- Viewers communicate via `app.sendMessage()` — clicking a button in one viewer injects a message into the conversation, which triggers the AI to call the right tool and open the appropriate viewer. This creates a seamless drill-down experience without leaving the chat.
151
+ Viewers communicate via `app.sendMessage()` — clicking a button in one viewer
152
+ injects a message into the conversation, which triggers the AI to call the right
153
+ tool and open the appropriate viewer. This creates a seamless drill-down
154
+ experience without leaving the chat.
137
155
 
138
156
  The server auto-injects navigation metadata into tool results:
157
+
139
158
  - `_rowAction` — which tool to call when a row is clicked
140
- - `_sendMessageHints` — navigation buttons shown in detail panels (e.g. "Orders", "Invoices")
141
- - `_drillDown` / `_trendDrillDown` — sendMessage templates for KPI and chart click-through
159
+ - `_sendMessageHints` — navigation buttons shown in detail panels (e.g.
160
+ "Orders", "Invoices")
161
+ - `_drillDown` / `_trendDrillDown` — sendMessage templates for KPI and chart
162
+ click-through
142
163
 
143
164
  ### Refresh model
144
165
 
145
- All viewers carry a `refreshRequest` payload for safe revalidation via `app.callServerTool()`:
166
+ All viewers carry a `refreshRequest` payload for safe revalidation via
167
+ `app.callServerTool()`:
168
+
146
169
  - `kanban-viewer` revalidates after mutations and on focus
147
170
  - All other viewers support focus refresh + manual refresh button
148
171
 
@@ -156,34 +179,36 @@ node build-all.mjs
156
179
 
157
180
  ## Tools (120)
158
181
 
159
- **14 categories** covering the full ERPNext surface. Each `_list` tool returns interactive results in the doclist-viewer with row click, inline detail, and cross-viewer navigation.
160
-
161
- | Category | Tools | Viewer | Key capabilities |
162
- |----------|-------|--------|-----------------|
163
- | **Sales** | 17 | doclist / invoice | Customers, Sales Orders, Invoices, Quotations — CRUD + Submit/Cancel |
164
- | **Purchasing** | 11 | doclist / invoice | Suppliers, Purchase Orders, Invoices, Receipts |
165
- | **Inventory** | 9 | doclist / stock | Items, Stock Balance, Warehouses, Stock Entries |
166
- | **Accounting** | 6 | doclist | Accounts, Journal Entries, Payment Entries |
167
- | **HR** | 12 | doclist | Employees, Attendance, Leave, Salary, Expenses |
168
- | **Project** | 9 | doclist | Projects, Tasks, Timesheets |
169
- | **Delivery** | 5 | doclist | Delivery Notes, Shipments |
170
- | **Manufacturing** | 7 | doclist | BOMs, Work Orders, Job Cards |
171
- | **CRM** | 8 | doclist | Leads, Opportunities, Contacts, Campaigns |
172
- | **Assets** | 8 | doclist | Assets, Movements, Maintenance, Categories |
173
- | **Operations** | 7 | doclist | Generic CRUD for **any** DocType (`erpnext_doc_*`) |
174
- | **Kanban** | 2 | kanban | Task/Opportunity/Issue boards with drag-and-drop |
175
- | **Analytics** | 17 | chart / kpi / funnel | 12 chart types, 5 KPIs, sales funnel |
176
- | **Setup** | 2 | — | Company creation |
182
+ **14 categories** covering the full ERPNext surface. Each `_list` tool returns
183
+ interactive results in the doclist-viewer with row click, inline detail, and
184
+ cross-viewer navigation.
185
+
186
+ | Category | Tools | Viewer | Key capabilities |
187
+ | ----------------- | ----- | -------------------- | -------------------------------------------------------------------- |
188
+ | **Sales** | 17 | doclist / invoice | Customers, Sales Orders, Invoices, Quotations — CRUD + Submit/Cancel |
189
+ | **Purchasing** | 11 | doclist / invoice | Suppliers, Purchase Orders, Invoices, Receipts |
190
+ | **Inventory** | 9 | doclist / stock | Items, Stock Balance, Warehouses, Stock Entries |
191
+ | **Accounting** | 6 | doclist | Accounts, Journal Entries, Payment Entries |
192
+ | **HR** | 12 | doclist | Employees, Attendance, Leave, Salary, Expenses |
193
+ | **Project** | 9 | doclist | Projects, Tasks, Timesheets |
194
+ | **Delivery** | 5 | doclist | Delivery Notes, Shipments |
195
+ | **Manufacturing** | 7 | doclist | BOMs, Work Orders, Job Cards |
196
+ | **CRM** | 8 | doclist | Leads, Opportunities, Contacts, Campaigns |
197
+ | **Assets** | 8 | doclist | Assets, Movements, Maintenance, Categories |
198
+ | **Operations** | 7 | doclist | Generic CRUD for **any** DocType (`erpnext_doc_*`) |
199
+ | **Kanban** | 2 | kanban | Task/Opportunity/Issue boards with drag-and-drop |
200
+ | **Analytics** | 17 | chart / kpi / funnel | 12 chart types, 5 KPIs, sales funnel |
201
+ | **Setup** | 2 | — | Company creation |
177
202
 
178
203
  > Full tool reference with all parameters: [`docs/tools.md`](docs/tools.md)
179
204
 
180
205
  ## Environment Variables
181
206
 
182
- | Variable | Required | Description |
183
- |----------|----------|-------------|
184
- | `ERPNEXT_URL` | Yes | ERPNext base URL — self-hosted (e.g. `http://localhost:8000`) or cloud (e.g. `https://mycompany.erpnext.com`) |
185
- | `ERPNEXT_API_KEY` | Yes | API Key from User Settings |
186
- | `ERPNEXT_API_SECRET` | Yes | API Secret from User Settings |
207
+ | Variable | Required | Description |
208
+ | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
209
+ | `ERPNEXT_URL` | Yes | ERPNext base URL — self-hosted (e.g. `http://localhost:8000`) or cloud (e.g. `https://mycompany.erpnext.com`) |
210
+ | `ERPNEXT_API_KEY` | Yes | API Key from User Settings |
211
+ | `ERPNEXT_API_SECRET` | Yes | API Secret from User Settings |
187
212
 
188
213
  ## Architecture
189
214
 
@@ -220,6 +245,7 @@ src/
220
245
  client.ts # ErpNextToolsClient
221
246
  runtime.ts # Deno runtime adapter
222
247
  runtime.node.ts # Node.js runtime adapter
248
+ *_test.ts # Tests are colocated with source files
223
249
  ui/
224
250
  shared/ # ActionButton, InfoField, theme, branding, refresh
225
251
  doclist-viewer/ # Generic document list (inline detail, chip filters)
@@ -230,10 +256,6 @@ src/
230
256
  kpi-viewer/ # KPI card (clickable number + sparkline)
231
257
  funnel-viewer/ # Sales funnel (trapezoid stages, click-through)
232
258
  viewers.ts # Viewer registry
233
- tests/
234
- tools/ # Tool + ui-refresh + client tests
235
- kanban/ # Kanban adapter tests
236
- ui/ # UI state + refresh tests
237
259
  docs/
238
260
  ROADMAP.md # Feature roadmap
239
261
  coverage.md # Test coverage matrix
@@ -241,16 +263,17 @@ docs/
241
263
 
242
264
  ## npm Package
243
265
 
244
- The npm package (`@casys/mcp-erpnext`) is a single self-contained bundle with zero runtime dependencies. UI viewers are embedded.
266
+ The npm package (`@casys/mcp-erpnext`) is a single self-contained bundle with
267
+ zero runtime dependencies. UI viewers are embedded.
245
268
 
246
269
  ## Development
247
270
 
248
271
  ```bash
249
- # Run tests (147 tests)
250
- deno test --allow-all tests/
272
+ # Run tests
273
+ deno test --allow-all src/
251
274
 
252
275
  # Type check
253
- deno check mod.ts server.ts
276
+ deno task check
254
277
 
255
278
  # Start HTTP server (dev)
256
279
  deno task serve
@@ -261,10 +284,29 @@ deno task inspect
261
284
  # Build UI viewers
262
285
  deno task ui:build
263
286
 
287
+ # Full local release preflight (no publish)
288
+ deno task release:check
289
+
264
290
  # Dev a specific viewer with HMR
265
291
  cd src/ui && npm run dev:kanban
266
292
  ```
267
293
 
294
+ ## Release Flow
295
+
296
+ Release is intentionally GitHub-driven:
297
+
298
+ 1. Run `deno task release:check` locally before publishing work.
299
+ 2. Push or merge to `main`.
300
+ 3. Release Please opens or updates the release PR with the semver bump,
301
+ `CHANGELOG.md`, `deno.json`, and `server.ts`.
302
+ 4. Merge the Release Please PR.
303
+ 5. `.github/workflows/release-please.yml` creates the GitHub release, then calls
304
+ `.github/workflows/publish.yml` to publish the released version to JSR and
305
+ npm.
306
+
307
+ Do not bump versions manually unless bypassing Release Please for an emergency
308
+ release.
309
+
268
310
  ## License
269
311
 
270
312
  MIT