@casys/mcp-erpnext 2.2.2 → 2.3.1
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/README.md +140 -57
- package/mcp-erpnext.mjs +2403 -3380
- package/package.json +1 -1
- package/ui-dist/chart-viewer/index.html +91 -65
- package/ui-dist/doclist-viewer/index.html +61 -35
- package/ui-dist/funnel-viewer/index.html +64 -38
- package/ui-dist/invoice-viewer/index.html +65 -39
- package/ui-dist/kanban-viewer/index.html +65 -39
- package/ui-dist/kpi-viewer/index.html +64 -38
- package/ui-dist/stock-viewer/index.html +65 -39
package/README.md
CHANGED
|
@@ -1,26 +1,80 @@
|
|
|
1
1
|
# @casys/mcp-erpnext
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://jsr.io/@casys/mcp-erpnext)
|
|
4
|
+
[](https://www.npmjs.com/package/@casys/mcp-erpnext)
|
|
5
|
+
[](https://github.com/Casys-AI/mcp-erpnext/actions/workflows/test.yml)
|
|
6
|
+
[](https://modelcontextprotocol.io)
|
|
7
|
+
[](LICENSE)
|
|
4
8
|
|
|
5
|
-
|
|
9
|
+
MCP server for [ERPNext](https://erpnext.com) / Frappe ERP — **120 tools**
|
|
10
|
+
across **14 categories**, with **7 interactive UI viewers**.
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
Connect any MCP-compatible AI agent (Claude Desktop, Claude Code, VS Code
|
|
13
|
+
Copilot, custom) to your ERPNext instance via the
|
|
14
|
+
[Model Context Protocol](https://modelcontextprotocol.io).
|
|
8
15
|
|
|
9
|
-
|
|
16
|
+
Works with **self-hosted** and **ERPNext Cloud** (frappe.cloud) instances.
|
|
10
17
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
+
## Screenshots
|
|
19
|
+
|
|
20
|
+
Interactive viewers rendered inside an MCP host, driven entirely by tool
|
|
21
|
+
results.
|
|
22
|
+
|
|
23
|
+
<table>
|
|
24
|
+
<tr>
|
|
25
|
+
<td width="50%" align="center">
|
|
26
|
+
<img src="docs/assets/doclist-viewer.png" alt="Document list viewer with chip filters and inline detail" width="100%"><br>
|
|
27
|
+
<sub><b>doclist-viewer</b> — any DocType as a sortable table with chip filters and an inline detail panel</sub>
|
|
28
|
+
</td>
|
|
29
|
+
<td width="50%" align="center">
|
|
30
|
+
<img src="docs/assets/invoice-viewer.png" alt="Invoice viewer with line items and actions" width="100%"><br>
|
|
31
|
+
<sub><b>invoice-viewer</b> — invoice with parties, line items, item drill-down and Submit/Cancel/Payments</sub>
|
|
32
|
+
</td>
|
|
33
|
+
</tr>
|
|
34
|
+
<tr>
|
|
35
|
+
<td width="50%" align="center">
|
|
36
|
+
<img src="docs/assets/funnel-viewer.png" alt="Sales funnel viewer" width="100%"><br>
|
|
37
|
+
<sub><b>funnel-viewer</b> — Lead → Opportunity → Quotation → Order with conversion rates</sub>
|
|
38
|
+
</td>
|
|
39
|
+
<td width="50%" align="center">
|
|
40
|
+
<img src="docs/assets/kpi-viewer.png" alt="KPI viewer with sparkline" width="100%"><br>
|
|
41
|
+
<sub><b>kpi-viewer</b> — big-number KPI with delta vs last period and a sparkline</sub>
|
|
42
|
+
</td>
|
|
43
|
+
</tr>
|
|
44
|
+
<tr>
|
|
45
|
+
<td width="50%" align="center">
|
|
46
|
+
<img src="docs/assets/chart-viewer.png" alt="Chart viewer" width="100%"><br>
|
|
47
|
+
<sub><b>chart-viewer</b> — universal Recharts renderer (here: stock levels)</sub>
|
|
48
|
+
</td>
|
|
49
|
+
<td width="50%" align="center">
|
|
50
|
+
<img src="docs/assets/stock-viewer.png" alt="Stock balance viewer" width="100%"><br>
|
|
51
|
+
<sub><b>stock-viewer</b> — stock balance with color-coded quantity badges</sub>
|
|
52
|
+
</td>
|
|
53
|
+
</tr>
|
|
54
|
+
<tr>
|
|
55
|
+
<td width="50%" align="center">
|
|
56
|
+
<img src="docs/assets/kanban-viewer.png" alt="Read-write kanban board" width="100%"><br>
|
|
57
|
+
<sub><b>kanban-viewer</b> — read-write board (Task / Opportunity / Issue) with inline edit</sub>
|
|
58
|
+
</td>
|
|
59
|
+
<td width="50%" align="center">
|
|
60
|
+
<img src="docs/assets/profit-loss.png" alt="Profit and loss composed chart" width="100%"><br>
|
|
61
|
+
<sub><b>chart-viewer</b> — composed dual-axis chart (here: profit & loss)</sub>
|
|
62
|
+
</td>
|
|
63
|
+
</tr>
|
|
64
|
+
</table>
|
|
65
|
+
|
|
66
|
+
## What's New
|
|
67
|
+
|
|
68
|
+
See the [CHANGELOG](CHANGELOG.md) for the full release history, or the
|
|
69
|
+
[latest release](https://github.com/Casys-AI/mcp-erpnext/releases/latest) for
|
|
70
|
+
the current version's highlights.
|
|
18
71
|
|
|
19
72
|
## Quick Start
|
|
20
73
|
|
|
21
74
|
### Prerequisites
|
|
22
75
|
|
|
23
76
|
Generate API credentials in ERPNext:
|
|
77
|
+
|
|
24
78
|
1. Login to ERPNext → top-right menu → **My Settings**
|
|
25
79
|
2. Section **API Access** → **Generate Keys**
|
|
26
80
|
3. Copy `API Key` and `API Secret`
|
|
@@ -43,7 +97,9 @@ Generate API credentials in ERPNext:
|
|
|
43
97
|
}
|
|
44
98
|
```
|
|
45
99
|
|
|
46
|
-
> **Works with ERPNext Cloud** — set `ERPNEXT_URL` to your Frappe Cloud URL
|
|
100
|
+
> **Works with ERPNext Cloud** — set `ERPNEXT_URL` to your Frappe Cloud URL
|
|
101
|
+
> (e.g. `https://mycompany.erpnext.com` or `https://mysite.frappe.cloud`). API
|
|
102
|
+
> key authentication works the same way on self-hosted and cloud instances.
|
|
47
103
|
|
|
48
104
|
> Zero dependencies — single self-contained bundle. Requires Node >= 20.
|
|
49
105
|
|
|
@@ -105,7 +161,8 @@ npx -y @casys/mcp-erpnext --categories=sales,inventory
|
|
|
105
161
|
|
|
106
162
|
## Fresh Instance Setup
|
|
107
163
|
|
|
108
|
-
On a fresh ERPNext instance (no setup wizard), you need to create master data
|
|
164
|
+
On a fresh ERPNext instance (no setup wizard), you need to create master data
|
|
165
|
+
before using business tools. Use `erpnext_doc_create` for prerequisites:
|
|
109
166
|
|
|
110
167
|
```
|
|
111
168
|
1. Warehouse Types: Transit, Default
|
|
@@ -119,30 +176,39 @@ On a fresh ERPNext instance (no setup wizard), you need to create master data be
|
|
|
119
176
|
|
|
120
177
|
## UI Viewers
|
|
121
178
|
|
|
122
|
-
Seven interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
|
|
179
|
+
Seven interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
|
|
180
|
+
viewers, registered as `ui://mcp-erpnext/{name}`:
|
|
123
181
|
|
|
124
|
-
| Viewer
|
|
125
|
-
|
|
182
|
+
| Viewer | Description | Interactive Features |
|
|
183
|
+
| ---------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
126
184
|
| `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
|
|
128
|
-
| `stock-viewer`
|
|
129
|
-
| `chart-viewer`
|
|
130
|
-
| `kanban-viewer`
|
|
131
|
-
| `kpi-viewer`
|
|
132
|
-
| `funnel-viewer`
|
|
185
|
+
| `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. |
|
|
186
|
+
| `stock-viewer` | Stock balance table with color-coded qty badges | Row click → item info + recent movements. sendMessage to stock chart, item details, stock entries. |
|
|
187
|
+
| `chart-viewer` | Universal chart renderer (12 types via Recharts) | Click bar/pie/line data points → sendMessage drill-down into underlying documents. |
|
|
188
|
+
| `kanban-viewer` | Read-write kanban for Task, Opportunity, Issue | Drag-and-drop moves, inline edit (priority, progress, dates), sendMessage to Timesheets/Quotations/Related docs. |
|
|
189
|
+
| `kpi-viewer` | Big number card with delta, sparkline, trend | Click number → sendMessage to exception list. Click sparkline → trend chart. |
|
|
190
|
+
| `funnel-viewer` | Trapezoid sales funnel with conversion rates | Click stage → sendMessage to document list at that stage. Stage action buttons. |
|
|
133
191
|
|
|
134
192
|
### Cross-viewer navigation
|
|
135
193
|
|
|
136
|
-
Viewers communicate via `app.sendMessage()` — clicking a button in one viewer
|
|
194
|
+
Viewers communicate via `app.sendMessage()` — clicking a button in one viewer
|
|
195
|
+
injects a message into the conversation, which triggers the AI to call the right
|
|
196
|
+
tool and open the appropriate viewer. This creates a seamless drill-down
|
|
197
|
+
experience without leaving the chat.
|
|
137
198
|
|
|
138
199
|
The server auto-injects navigation metadata into tool results:
|
|
200
|
+
|
|
139
201
|
- `_rowAction` — which tool to call when a row is clicked
|
|
140
|
-
- `_sendMessageHints` — navigation buttons shown in detail panels (e.g.
|
|
141
|
-
|
|
202
|
+
- `_sendMessageHints` — navigation buttons shown in detail panels (e.g.
|
|
203
|
+
"Orders", "Invoices")
|
|
204
|
+
- `_drillDown` / `_trendDrillDown` — sendMessage templates for KPI and chart
|
|
205
|
+
click-through
|
|
142
206
|
|
|
143
207
|
### Refresh model
|
|
144
208
|
|
|
145
|
-
All viewers carry a `refreshRequest` payload for safe revalidation via
|
|
209
|
+
All viewers carry a `refreshRequest` payload for safe revalidation via
|
|
210
|
+
`app.callServerTool()`:
|
|
211
|
+
|
|
146
212
|
- `kanban-viewer` revalidates after mutations and on focus
|
|
147
213
|
- All other viewers support focus refresh + manual refresh button
|
|
148
214
|
|
|
@@ -156,34 +222,36 @@ node build-all.mjs
|
|
|
156
222
|
|
|
157
223
|
## Tools (120)
|
|
158
224
|
|
|
159
|
-
**14 categories** covering the full ERPNext surface. Each `_list` tool returns
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
|
164
|
-
|
|
|
165
|
-
| **
|
|
166
|
-
| **
|
|
167
|
-
| **
|
|
168
|
-
| **
|
|
169
|
-
| **
|
|
170
|
-
| **
|
|
171
|
-
| **
|
|
172
|
-
| **
|
|
173
|
-
| **
|
|
174
|
-
| **
|
|
175
|
-
| **
|
|
176
|
-
| **
|
|
225
|
+
**14 categories** covering the full ERPNext surface. Each `_list` tool returns
|
|
226
|
+
interactive results in the doclist-viewer with row click, inline detail, and
|
|
227
|
+
cross-viewer navigation.
|
|
228
|
+
|
|
229
|
+
| Category | Tools | Viewer | Key capabilities |
|
|
230
|
+
| ----------------- | ----- | -------------------- | -------------------------------------------------------------------- |
|
|
231
|
+
| **Sales** | 17 | doclist / invoice | Customers, Sales Orders, Invoices, Quotations — CRUD + Submit/Cancel |
|
|
232
|
+
| **Purchasing** | 11 | doclist / invoice | Suppliers, Purchase Orders, Invoices, Receipts |
|
|
233
|
+
| **Inventory** | 9 | doclist / stock | Items, Stock Balance, Warehouses, Stock Entries |
|
|
234
|
+
| **Accounting** | 6 | doclist | Accounts, Journal Entries, Payment Entries |
|
|
235
|
+
| **HR** | 12 | doclist | Employees, Attendance, Leave, Salary, Expenses |
|
|
236
|
+
| **Project** | 9 | doclist | Projects, Tasks, Timesheets |
|
|
237
|
+
| **Delivery** | 5 | doclist | Delivery Notes, Shipments |
|
|
238
|
+
| **Manufacturing** | 7 | doclist | BOMs, Work Orders, Job Cards |
|
|
239
|
+
| **CRM** | 8 | doclist | Leads, Opportunities, Contacts, Campaigns |
|
|
240
|
+
| **Assets** | 8 | doclist | Assets, Movements, Maintenance, Categories |
|
|
241
|
+
| **Operations** | 7 | doclist | Generic CRUD for **any** DocType (`erpnext_doc_*`) |
|
|
242
|
+
| **Kanban** | 2 | kanban | Task/Opportunity/Issue boards with drag-and-drop |
|
|
243
|
+
| **Analytics** | 17 | chart / kpi / funnel | 12 chart types, 5 KPIs, sales funnel |
|
|
244
|
+
| **Setup** | 2 | — | Company creation |
|
|
177
245
|
|
|
178
246
|
> Full tool reference with all parameters: [`docs/tools.md`](docs/tools.md)
|
|
179
247
|
|
|
180
248
|
## Environment Variables
|
|
181
249
|
|
|
182
|
-
| Variable
|
|
183
|
-
|
|
184
|
-
| `ERPNEXT_URL`
|
|
185
|
-
| `ERPNEXT_API_KEY`
|
|
186
|
-
| `ERPNEXT_API_SECRET` | Yes
|
|
250
|
+
| Variable | Required | Description |
|
|
251
|
+
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
|
|
252
|
+
| `ERPNEXT_URL` | Yes | ERPNext base URL — self-hosted (e.g. `http://localhost:8000`) or cloud (e.g. `https://mycompany.erpnext.com`) |
|
|
253
|
+
| `ERPNEXT_API_KEY` | Yes | API Key from User Settings |
|
|
254
|
+
| `ERPNEXT_API_SECRET` | Yes | API Secret from User Settings |
|
|
187
255
|
|
|
188
256
|
## Architecture
|
|
189
257
|
|
|
@@ -220,6 +288,7 @@ src/
|
|
|
220
288
|
client.ts # ErpNextToolsClient
|
|
221
289
|
runtime.ts # Deno runtime adapter
|
|
222
290
|
runtime.node.ts # Node.js runtime adapter
|
|
291
|
+
*_test.ts # Tests are colocated with source files
|
|
223
292
|
ui/
|
|
224
293
|
shared/ # ActionButton, InfoField, theme, branding, refresh
|
|
225
294
|
doclist-viewer/ # Generic document list (inline detail, chip filters)
|
|
@@ -230,10 +299,6 @@ src/
|
|
|
230
299
|
kpi-viewer/ # KPI card (clickable number + sparkline)
|
|
231
300
|
funnel-viewer/ # Sales funnel (trapezoid stages, click-through)
|
|
232
301
|
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
302
|
docs/
|
|
238
303
|
ROADMAP.md # Feature roadmap
|
|
239
304
|
coverage.md # Test coverage matrix
|
|
@@ -241,16 +306,17 @@ docs/
|
|
|
241
306
|
|
|
242
307
|
## npm Package
|
|
243
308
|
|
|
244
|
-
The npm package (`@casys/mcp-erpnext`) is a single self-contained bundle with
|
|
309
|
+
The npm package (`@casys/mcp-erpnext`) is a single self-contained bundle with
|
|
310
|
+
zero runtime dependencies. UI viewers are embedded.
|
|
245
311
|
|
|
246
312
|
## Development
|
|
247
313
|
|
|
248
314
|
```bash
|
|
249
|
-
# Run tests
|
|
250
|
-
deno test --allow-all
|
|
315
|
+
# Run tests
|
|
316
|
+
deno test --allow-all src/
|
|
251
317
|
|
|
252
318
|
# Type check
|
|
253
|
-
deno check
|
|
319
|
+
deno task check
|
|
254
320
|
|
|
255
321
|
# Start HTTP server (dev)
|
|
256
322
|
deno task serve
|
|
@@ -261,10 +327,27 @@ deno task inspect
|
|
|
261
327
|
# Build UI viewers
|
|
262
328
|
deno task ui:build
|
|
263
329
|
|
|
330
|
+
# Full local release preflight (no publish)
|
|
331
|
+
deno task release:check
|
|
332
|
+
|
|
264
333
|
# Dev a specific viewer with HMR
|
|
265
334
|
cd src/ui && npm run dev:kanban
|
|
266
335
|
```
|
|
267
336
|
|
|
337
|
+
## Release Flow
|
|
338
|
+
|
|
339
|
+
Releases are manual and explicit:
|
|
340
|
+
|
|
341
|
+
1. Update `deno.json`, `server.ts`, and `CHANGELOG.md`.
|
|
342
|
+
2. Run `deno task release:check` locally.
|
|
343
|
+
3. Commit and push the release commit to `main`.
|
|
344
|
+
4. Create the GitHub release/tag, for example `v2.3.0`.
|
|
345
|
+
5. Run the `Publish` workflow manually to publish the same version to JSR and
|
|
346
|
+
npm.
|
|
347
|
+
|
|
348
|
+
The package name stays `@casys/mcp-erpnext`; releases only bump the package
|
|
349
|
+
version.
|
|
350
|
+
|
|
268
351
|
## License
|
|
269
352
|
|
|
270
353
|
MIT
|