@casys/mcp-erpnext 3.0.1 → 3.1.0-beta.1

package/README.md

@@ -8,12 +8,9 @@ English | [繁體中文](README.zh-TW.md)
 [![MCP](https://img.shields.io/badge/MCP-server-1f6feb?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-MCP server for [ERPNext](https://erpnext.com) / Frappe ERP — **124 tools**
-across **14 categories**, with **7 interactive UI viewers**.
-
-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).
+Let any MCP-compatible AI agent operate your [ERPNext](https://erpnext.com) /
+Frappe instance — documents, workflows, and interactive viewers inside the host
+(Claude Desktop, Claude Code, VS Code Copilot, or custom).
 
 Works with **self-hosted** and **ERPNext Cloud** (frappe.cloud) instances.
 
@@ -75,6 +72,11 @@ See the [CHANGELOG](CHANGELOG.md) for the full release history, or the
 [latest release](https://github.com/Casys-AI/mcp-erpnext/releases/latest) for
 the current version's highlights.
 
+> **3.1 beta preview:** install with `npx -y @casys/mcp-erpnext@next`. The beta
+> remains compatible with the 3.0 tool surface and progressively enables in-view
+> navigation and active context according to the capabilities advertised by the
+> MCP host.
+
 ## Documentation
 
 Organised by what you are doing, following [Diátaxis](https://diataxis.fr):
@@ -182,72 +184,77 @@ until it exists. See
 Seven interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
 viewers, registered as `ui://mcp-erpnext/{name}`:
 
-| Viewer           | Description                                                      | Interactive Features                                                                                                                               |
-| ---------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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. |
-| `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.                 |
-| `stock-viewer`   | Stock balance table with color-coded qty badges                  | Row click → item info + recent movements. sendMessage to stock chart, item details, stock entries.                                                 |
-| `chart-viewer`   | Universal chart renderer (12 types via Recharts)                 | Click bar/pie/line data points → sendMessage drill-down into underlying documents.                                                                 |
-| `kanban-viewer`  | Read-write kanban for Task, Opportunity, Issue                   | Drag-and-drop moves, inline edit (priority, progress, dates), sendMessage to Timesheets/Quotations/Related docs.                                   |
-| `kpi-viewer`     | Big number card with delta, sparkline, trend                     | Click number → sendMessage to exception list. Click sparkline → trend chart.                                                                       |
-| `funnel-viewer`  | Trapezoid sales funnel with conversion rates                     | Click stage → sendMessage to document list at that stage. Stage action buttons.                                                                    |
-
-### Cross-viewer navigation
-
-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.
-
-The server auto-injects navigation metadata into tool results:
-
-- `_rowAction` — which tool to call when a row is clicked
-- `_sendMessageHints` — navigation buttons shown in detail panels (e.g.
-  "Orders", "Invoices")
-- `_drillDown` / `_trendDrillDown` — sendMessage templates for KPI and chart
-  click-through
+| Viewer           | Description                                                      | Interactive Features                                                                          |
+| ---------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `doclist-viewer` | Generic document table with sort, filter, pagination, CSV export | Inline details, typed nested navigation, Submit/Cancel, and compact status filters.           |
+| `invoice-viewer` | Sales/Purchase documents with parties, items, totals             | Item, stock, party, and payment navigation plus guarded Submit/Cancel actions.                |
+| `stock-viewer`   | Stock balance table with color-coded qty badges                  | Item details, recent movements, stock charts, and stock-entry navigation.                     |
+| `chart-viewer`   | Universal chart renderer (12 types via Recharts)                 | Exact point/series navigation and active-context selection across simple and composed charts. |
+| `kanban-viewer`  | Read-write kanban for Task, Opportunity, Issue                   | Drag-and-drop, inline editing, serialized saves, and typed related-document navigation.       |
+| `kpi-viewer`     | Big number card with delta, sparkline, trend                     | Number and trend navigation with bounded active-context selection.                            |
+| `funnel-viewer`  | Trapezoid sales funnel with conversion rates                     | Period-aware stage navigation and bounded active-context selection.                           |
+
+### Navigation and active context
+
+Viewers progressively select the best interaction supported by the host:
+
+- `serverTools` opens typed list, record, and chart targets inside the current
+  viewer through `app.callServerTool()`. Back and breadcrumb navigation restore
+  the state of each level.
+- `updateModelContext` lets chart, KPI, and funnel selections join a bounded
+  active-context snapshot. The compact context chip keeps up to eight items and
+  lets users remove one item or clear them all. The snapshot contains selected
+  values, never hidden instructions for the model.
+- `message.text` keeps `app.sendMessage()` as a conversational fallback when
+  direct navigation or context replacement is unavailable.
+- Without these capabilities, local inspection remains available and unsupported
+  remote actions are omitted.
+
+The server supplies typed navigation metadata and the exact `_availableTools`
+allowed for each viewer, so category-filtered deployments do not expose tools
+that are not loaded.
 
 ### Refresh model
 
-All viewers carry a `refreshRequest` payload for safe revalidation via
-`app.callServerTool()`:
-
-- `kanban-viewer` revalidates after mutations and on focus
-- All other viewers support focus refresh + manual refresh button
+Read-only viewers revalidate on focus and through their refresh control.
+Mutations use an explicit read-only request to fetch committed state; a mutating
+tool is never replayed automatically. Overlapping or stale responses are ignored
+when a newer host payload or mutation has already won.
 
 ### Building UI viewers
 
 ```bash
 cd src/ui
-npm install
+npm ci
 node build-all.mjs
 ```
 
-## Tools (124)
+## Tools
 
-124 tools across 14 categories. Each `_list` tool returns interactive results
-via the doclist-viewer with row click, inline detail, and cross-viewer
-navigation.
+Each `_list` tool returns interactive results via the doclist-viewer with row
+click, inline detail, and cross-viewer navigation.
 
-- **Sales** (17) — Customers, Sales Orders, Invoices, and Quotations with full
-  CRUD, Submit, and Cancel.
-- **Purchasing** (11) — Suppliers, Purchase Orders, Purchase Invoices, Receipts,
-  and Supplier Quotations.
-- **Inventory** (9) — Items, Stock Balance, Warehouses, and Stock Entries.
-- **Accounting** (6) — Chart of Accounts, Journal Entries, and Payment Entries.
-- **HR** (12) — Employees, Attendance, Leave Applications, Salary Slips, Payroll
+- **Sales** — Customers, Sales Orders, Invoices, and Quotations with full CRUD,
+  Submit, and Cancel.
+- **Purchasing** — Suppliers, Purchase Orders, Purchase Invoices, Receipts, and
+  Supplier Quotations.
+- **Inventory** — Items, Stock Balance, Warehouses, and Stock Entries.
+- **Accounting** — Chart of Accounts, Journal Entries, and Payment Entries.
+- **HR** — Employees, Attendance, Leave Applications, Salary Slips, Payroll
   Entries, and Expense Claims.
-- **Project** (9) — Projects, Tasks (with native assignment), and Timesheets.
-- **Delivery** (5) — Delivery Notes and Shipments.
-- **Manufacturing** (7) — BOMs, Work Orders, and Job Cards.
-- **CRM** (8) — Leads, Opportunities, Contacts, and Campaigns.
-- **Assets** (8) — Assets, Movements, Maintenance records, and Categories.
-- **Operations** (10) — Generic CRUD, native assignment, and file upload for any
-  DocType (`erpnext_doc_*`, `erpnext_file_upload`).
-- **Kanban** (2) — Read-write boards for Task, Opportunity, and Issue with
+- **Project** — Projects, Tasks (with native assignment), and Timesheets.
+- **Delivery** — Delivery Notes and Shipments.
+- **Manufacturing** — BOMs, Work Orders, and Job Cards.
+- **CRM** — Leads, Opportunities, Contacts, and Campaigns.
+- **Assets** — Assets, Movements, Maintenance records, and Categories.
+- **Operations** — Generic CRUD, native assignment, and attachment listing or
+  upload for any DocType (`erpnext_doc_*`, `erpnext_file_list`,
+  `erpnext_file_upload`).
+- **Kanban** — Read-write boards for Task, Opportunity, and Issue with
   drag-and-drop.
-- **Analytics** (17) — 11 analytics charts (bar, area, treemap, radar, scatter,
-  P&L…), 5 KPIs with sparklines, and a sales funnel.
-- **Setup** (3) — Company creation and assignable user listing.
+- **Analytics** — Charts (bar, area, treemap, radar, scatter, P&L…), KPIs with
+  sparklines, and a sales funnel.
+- **Setup** — Company creation and assignable user listing.
 
 Full per-tool reference with parameters: [`docs/tools.md`](docs/tools.md).