@casys/mcp-erpnext 3.1.0-beta.9 → 3.1.0

package/README.md

@@ -9,15 +9,6 @@ English | [繁體中文](README.zh-TW.md)
 [![M8ven Score](https://m8ven.ai/badge/mcp/casys-ai-mcp-erpnext-1kev4k)](https://m8ven.ai/mcp/casys-ai-mcp-erpnext-1kev4k)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-> [!IMPORTANT]
-> **Installing the 3.1 beta:** for npm/Node use
-> `npx -y @casys/mcp-erpnext@next`; for Deno use
-> `deno run -A jsr:@casys/mcp-erpnext@^3.1.0-beta/server`. Both follow the
-> current prerelease — JSR has no dist-tags, hence the range there. Exact
-> versions are in the [CHANGELOG](CHANGELOG.md). The beta adds the generic
-> document viewer and attachment workflows, so test it with the MCP host your
-> users actually run before replacing a stable deployment.
-
 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).
@@ -78,18 +69,20 @@ results.
 
 ## What's New
 
+**3.1.0 is the stable release.** KPI and funnel viewers now use the refreshed
+interface and support selecting context for the next conversation turn.
+Recognized creation errors include recovery guidance in the existing tools. The
+other five viewers keep their existing interactions.
+
+For stable npm installations use `@casys/mcp-erpnext@latest`; for Deno use
+`jsr:@casys/mcp-erpnext@3.1.0/server`. The separate 3.2 beta remains on npm
+`@next` and includes the generic document viewer, attachment workflows and Buy
+evidence features.
+
 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:** the beta keeps the 3.0 tool surface and adds a generic
-> document viewer, child tables, document attachments, in-view navigation, and
-> active context. **3.1.0-beta.9** adds read-only Buy evidence capture and an
-> immutable recorded-session viewer. Features remain capability-gated by the MCP
-> host. In particular, downloads require both proxied server tools and the MCP
-> Apps `downloadFile` capability. Buy evidence does not purchase or qualify a
-> live ERP.
-
 ## Documentation
 
 Organised by what you are doing, following [Diátaxis](https://diataxis.fr):
@@ -194,55 +187,52 @@ until it exists. See
 
 ## UI Viewers
 
-Nine interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
+Seven interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
 viewers, registered as `ui://mcp-erpnext/{name}`:
 
-| Viewer                | Description                                                      | Interactive Features                                                                          |
-| --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `doc-viewer`          | Generic ERPNext document with fields and child tables            | Capability-gated attachments, typed navigation, guarded Submit/Cancel, and raw JSON fallback. |
-| `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 Orders, Sales Invoices, and Quotations with line 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.                           |
-| `buy-evidence-viewer` | Immutable sealed Buy evidence (recorded session only)            | Complete, partial, unresolved, and unavailable projections; no live ERP refresh or mutation.  |
-
-### 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.
-- `downloadFile` lets the host confirm and save an attachment returned as a
-  bounded embedded resource. The viewer never opens an ERPNext file URL
-  directly.
-- `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 Buy evidence viewer is recorded-session only. It does not call server
-  tools, refresh live documents, or mutate ERP state.
-
-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.
+| 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`     | Responsive KPI card with delta and monthly trend                        | Select trend data/months as context; double-click or Enter requests details in the conversation. Scalar-only KPIs have no selection control.       |
+| `funnel-viewer`  | Responsive sales funnel with stage counts, amounts and conversion rates | Click/Space selects or removes a stage from context; double-click, Enter or the explicit Ask button requests details in the conversation.          |
+
+### Context selection in KPI and funnel
+
+On hosts that support `app.updateModelContext()`, selecting an element prepares
+context for the next conversation turn. It does not send a chat message. Click
+again or use the Context control to remove a selection or clear the basket.
+Pending and rejected updates are shown separately from confirmed selections.
+Refreshing keeps the selections that still exist and updates their values.
+
+KPI and funnel use the new Preact/Tailwind interface. The other five viewers
+retain their existing React interface and interactions. Detail requests in these
+two viewers use the conversation; they do not open nested document editors.
+
+### Cross-viewer navigation
+
+Viewers communicate via `app.sendMessage()` — clicking a button in one viewer
+sends a request to the conversation for the assistant to open the requested
+data.
+
+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
 
 ### Refresh model
 
-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. A confirmed document
-change marks every potentially derived snapshot in the current navigation stack
-as stale; each marker is removed only when that surface has actually been read
-again. Separate MCP Apps are not synchronized automatically in the 3.1 beta.
+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
 
 ### Building UI viewers
 
@@ -252,48 +242,10 @@ npm ci
 node build-all.mjs
 ```
 
-## Buy evidence capture
-
-**One** read-only tool and **one** recorded App. They do not purchase, create a
-BOM/RFQ/PO, refresh live documents, replace generic ERP viewers, or qualify a
-live ERPNext instance.
-
-- Tool: `erpnext_buy_capture`. Closed DocTypes only (Item, BOM, Item Price,
-  Supplier Quotation, Supplier, Price List, UOM, Currency Exchange). Two
-  `skipCache` reads must agree on `modified` and the closed projection
-  fingerprint. Return is ephemeral canonical JSON + SHA-256 + byte count. The
-  caller cannot pass `sourceInstance`, URL, credentials, `capturedAt`, or a
-  digest. Digital Thread stores those bytes in its own CAS; this server does not
-  keep a second CAS.
-- App: `io.casys.mcp-erpnext.buy-evidence` `3.1.0-beta.9`, resource
-  `ui://mcp-erpnext/buy-evidence-viewer` (`text/html;profile=mcp-app`), manifest
-  `ui://mcp-erpnext/buy-evidence-manifest` (`application/json`),
-  `acceptedActions` = `viewer.session.apply` only. Complete, partial,
-  unresolved, and unavailable projections stay labelled. No live DocViewer
-  refresh, mutation, or `app.callServerTool`. Session `anchor` is the sealed
-  Digital Thread artefact (`provenance.bundleRef`), not a hash of the displayed
-  projection.
-- Schemas: `io.casys.mcp-erpnext.buy-source-capture/1.0`,
-  `io.casys.mcp-erpnext.buy-recorded-result/1.0`,
-  `io.casys.mcp-erpnext.buy-recorded-session/1.0`.
-- The viewer is built with the other MCP Apps
-  (`cd src/ui && npm ci && node
-  build-all.mjs`). Published JSR/npm artifacts
-  include `src/ui/dist/` and the Buy TypeScript module; the HTML resource and
-  generated manifest are what a published installation serves.
-
-Digital Thread owns configuration/seal (`buy-configuration/1.0`,
-`buy-cost-bundle/1.0`, `buy.capture-configuration-cost@1`,
-`buy.seal-configuration-cost@1`). A qualified
-`commerce.read-erpnext-buy-source@1` binding is required before dispatch.
-
 ## Tools
 
-Record `_list` tools return interactive results via the doclist-viewer with row
-click, inline detail, and cross-viewer navigation. The attachment-specific
-`erpnext_file_list` tool does not render doclist-viewer. Generic and dedicated
-document reads use `doc-viewer`, except Sales Order, Sales Invoice, and
-Quotation, which retain the specialized invoice surface.
+Each `_list` tool returns interactive results via the doclist-viewer with row
+click, inline detail, and cross-viewer navigation.
 
 - **Sales** — Customers, Sales Orders, Invoices, and Quotations with full CRUD,
   Submit, and Cancel.
@@ -308,31 +260,27 @@ Quotation, which retain the specialized invoice surface.
 - **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, attachment listing, upload,
-  host-mediated download, and deny-by-default Frappe method calls
-  (`erpnext_doc_*`, `erpnext_file_*`, `erpnext_method_call`).
+- **Operations** — Generic CRUD, native assignment, file upload, and
+  deny-by-default Frappe method calls (`erpnext_doc_*`, `erpnext_file_upload`,
+  `erpnext_method_call`).
 - **Kanban** — Read-write boards for Task, Opportunity, and Issue with
   drag-and-drop.
 - **Analytics** — Charts (bar, area, treemap, radar, scatter, P&L…), KPIs with
   sparklines, and a sales funnel.
-- **Buy** — Read-only sealed capture of closed commercial documents
-  (`erpnext_buy_capture`) and an immutable recorded-session evidence viewer. Not
-  a purchase, BOM/RFQ/PO, or live ERP qualification.
 - **Setup** — Company creation and assignable user listing.
 
 Full per-tool reference with parameters: [`docs/tools.md`](docs/tools.md).
 
 ## Environment Variables
 
-| Variable                     | Required | Description                                                                                                                      |
-| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `ERPNEXT_URL`                | Yes      | ERPNext base URL — self-hosted (e.g. `http://localhost:8000`) or cloud (e.g. `https://mycompany.erpnext.com`)                    |
-| `ERPNEXT_API_KEY`            | Yes      | API Key from User Settings                                                                                                       |
-| `ERPNEXT_API_SECRET`         | Yes      | API Secret from User Settings                                                                                                    |
-| `ERPNEXT_MAX_UPLOAD_BYTES`   | No       | Maximum decoded file-upload size in bytes (positive integer; default: 10 MiB)                                                    |
-| `ERPNEXT_MAX_DOWNLOAD_BYTES` | No       | Maximum attachment-download size in bytes (positive integer; default: 10 MiB)                                                    |
-| `ERPNEXT_METHOD_ALLOWLIST`   | No       | Comma-separated exact method paths or `prefix.*`; unset means `erpnext_method_call` denies every method, while `*` allows all    |
-| `MCP_MRTR_SIGNING_KEY`       | No       | Exactly 64 lowercase hex characters; enables signed ambiguous-link elicitation. **Single-instance deployments only** — see below |
+| Variable                   | Required | Description                                                                                                                      |
+| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `ERPNEXT_URL`              | Yes      | ERPNext base URL — self-hosted (e.g. `http://localhost:8000`) or cloud (e.g. `https://mycompany.erpnext.com`)                    |
+| `ERPNEXT_API_KEY`          | Yes      | API Key from User Settings                                                                                                       |
+| `ERPNEXT_API_SECRET`       | Yes      | API Secret from User Settings                                                                                                    |
+| `ERPNEXT_MAX_UPLOAD_BYTES` | No       | Maximum decoded file-upload size in bytes (positive integer; default: 10 MiB)                                                    |
+| `ERPNEXT_METHOD_ALLOWLIST` | No       | Comma-separated exact method paths or `prefix.*`; unset means `erpnext_method_call` denies every method, while `*` allows all    |
+| `MCP_MRTR_SIGNING_KEY`     | No       | Exactly 64 lowercase hex characters; enables signed ambiguous-link elicitation. **Single-instance deployments only** — see below |
 
 MRTR is opt-in. Without this key, or when the client does not advertise
 elicitation, ambiguous links keep returning the existing actionable ambiguity