@casys/mcp-erpnext 3.2.0-beta.1 → 3.2.0

package/README.md

@@ -4,20 +4,19 @@ English | [繁體中文](README.zh-TW.md)
 
 [![JSR](https://jsr.io/badges/@casys/mcp-erpnext)](https://jsr.io/@casys/mcp-erpnext)
 [![npm](https://img.shields.io/npm/v/@casys/mcp-erpnext?logo=npm&color=cb3837)](https://www.npmjs.com/package/@casys/mcp-erpnext)
-[![CI](https://github.com/superWorldSavior/mcp-erpnext/actions/workflows/test.yml/badge.svg)](https://github.com/superWorldSavior/mcp-erpnext/actions/workflows/test.yml)
+[![CI](https://github.com/Casys-AI/mcp-erpnext/actions/workflows/test.yml/badge.svg)](https://github.com/Casys-AI/mcp-erpnext/actions/workflows/test.yml)
 [![MCP](https://img.shields.io/badge/MCP-server-1f6feb?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
 [![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.2 beta:** for npm/Node use
-> `npx -y @casys/mcp-erpnext@next`; for Deno use
-> `deno run -A jsr:@casys/mcp-erpnext@3.2.0-beta.1/server`. npm's `next` tag
-> follows the current prerelease; the JSR command pins this exact beta because
-> JSR has no dist-tags. Stable **3.1.0** is available through npm's `latest`
-> tag. The beta retains the generic document viewer and attachment workflows, so
-> test it with the MCP host your users actually run before replacing a stable
-> deployment. See the [CHANGELOG](CHANGELOG.md) for release history.
+> **Installing 3.2:** for npm/Node use `npx -y @casys/mcp-erpnext@latest`; for
+> Deno use `deno run -A jsr:@casys/mcp-erpnext@3.2.0/server`. 3.2.0 is the
+> stable release and carries npm's `latest` tag; prereleases, when published,
+> use the `next` tag. 3.2 adds the generic document viewer and attachment
+> workflows, so test it with the MCP host your users actually run before
+> replacing an existing deployment. See the [CHANGELOG](CHANGELOG.md) for
+> release history.
 
 Let any MCP-compatible AI agent operate your [ERPNext](https://erpnext.com) /
 Frappe instance — documents, workflows, and interactive viewers inside the host
@@ -80,28 +79,44 @@ results.
 
 ## What's New
 
+**3.2.0 is the stable release.** All nine viewers navigate inside the view with
+back and breadcrumb navigation, and a confirmed document change marks the
+derived levels stale until they are read again. Active-context selection covers
+the interactive viewers, and chart, KPI and nested-chart details open from a
+visible button on touch screens. The generic document viewer, child tables and
+attachment workflows follow ERPNext's own DocType metadata. Tool-selection
+filters (`ERPNEXT_CATEGORIES`, `ERPNEXT_EXCLUDE_CATEGORIES`,
+`ERPNEXT_EXCLUDE_TOOLS`) limit what a deployment exposes, attachment downloads
+are refused to clients that do not announce MCP Apps, and errors are structured.
+Viewer enrichment (refresh requests, navigation jumps, tool manifests) travels
+in `_meta`, out of the model's context, instead of the result text.
+
+3.2.0 also carries the creation-error guidance, ERPNext 16 Opportunity
+compatibility, calendar-date, KPI percentage and funnel currency fixes of the
+stable 3.0.5 and 3.1.0 releases. Features remain capability-gated by the MCP
+host; Buy evidence does not purchase or qualify a live ERP.
+
+For stable npm installations use `@casys/mcp-erpnext@latest`; for Deno use
+`jsr:@casys/mcp-erpnext@3.2.0/server`.
+
 See the [CHANGELOG](CHANGELOG.md) for the full release history, or the
-[latest release](https://github.com/superWorldSavior/mcp-erpnext/releases/latest)
-for the current version's highlights.
+[latest release](https://github.com/Casys-AI/mcp-erpnext/releases/latest) for
+the current version's highlights.
 
-> **3.2.0-beta.1 preview:** the beta includes the creation-error guidance,
-> ERPNext 16 Opportunity compatibility and calendar-date fixes carried into
-> stable 3.1.0, alongside its generic document viewer, child tables,
-> attachments, in-view navigation and recorded Buy evidence. KPI percentage
-> changes, funnel currencies and context clearing on unsupported hosts are also
-> corrected. Features remain capability-gated by the MCP host; Buy evidence does
-> not purchase or qualify a live ERP.
+See the [3.0 to 3.1 migration guide](docs/migration-3.0-to-3.1.md) for the
+source contracts, host requirements, and deployment limits carried into 3.2; it
+applies when upgrading from 3.0 or from stable 3.1.0.
 
 ## Documentation
 
 Organised by what you are doing, following [Diátaxis](https://diataxis.fr):
 
-|                                       |                                                                                                                                                                                                                       |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Learning** — never used this before | [Your first tool call](docs/tutorial-first-tool-call.md) — from nothing to a working response in four steps                                                                                                           |
-| **Doing** — you have a specific goal  | [Seed a blank ERPNext instance](docs/fresh-instance-setup.md) · [Run the HTTP server](docs/http-deployment.md) · [Set up OAuth](docs/oauth-setup.md) · [Migrate to 2026-07-28](docs/migration-mcp-spec-2026-07-28.md) |
-| **Looking something up**              | [Tools](docs/tools.md) · [Environment variables](docs/environment-variables.md) · [DocType coverage](docs/coverage.md)                                                                                                |
-| **Understanding why**                 | [Concepts](docs/concepts.md) — link resolution, transports, MRTR, and which cache does what · [ERPNext quirks](docs/erpnext-quirks.md)                                                                                |
+|                                       |                                                                                                                                                                                                                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Learning** — never used this before | [Your first tool call](docs/tutorial-first-tool-call.md) — from nothing to a working response in four steps                                                                                                                                                                     |
+| **Doing** — you have a specific goal  | [Seed a blank ERPNext instance](docs/fresh-instance-setup.md) · [Run the HTTP server](docs/http-deployment.md) · [Set up OAuth](docs/oauth-setup.md) · [Migrate from 3.0 to 3.1](docs/migration-3.0-to-3.1.md) · [Migrate to 2026-07-28](docs/migration-mcp-spec-2026-07-28.md) |
+| **Looking something up**              | [Tools](docs/tools.md) · [Environment variables](docs/environment-variables.md) · [DocType coverage](docs/coverage.md)                                                                                                                                                          |
+| **Understanding why**                 | [Concepts](docs/concepts.md) — link resolution, transports, MRTR, and which cache does what · [ERPNext quirks](docs/erpnext-quirks.md)                                                                                                                                          |
 
 ## Quick Start
 
@@ -188,6 +203,19 @@ Load only the categories you need:
 npx -y @casys/mcp-erpnext --categories=sales,inventory
 ```
 
+Category and individual-tool exclusions are also supported, with
+environment-variable equivalents:
+
+```bash
+deno run -A server.ts --categories=sales,inventory,operations --exclude-tools=erpnext_file_upload,erpnext_doc_delete
+```
+
+CLI values override `ERPNEXT_CATEGORIES`, `ERPNEXT_EXCLUDE_CATEGORIES`, and
+`ERPNEXT_EXCLUDE_TOOLS` individually. Excluded tools disappear from calls,
+viewer actions, and cache warm-up. Use `--flag=value`; invalid exclusions or an
+empty server selection fail startup. Full rules:
+[tool selection](docs/environment-variables.md#tool-selection).
+
 ## Fresh Instance Setup
 
 A blank ERPNext instance has no master data, so business tools fail validation
@@ -211,6 +239,15 @@ viewers, registered as `ui://mcp-erpnext/{name}`:
 | `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.  |
 
+Viewers and Buy result fields use the host locale: English, French, Simplified
+Chinese, Traditional Chinese, Hindi, Bengali, Tamil and Urdu. Chinese script
+tags take precedence over region tags; `zh-TW`, `zh-HK` and `zh-MO` select
+Traditional Chinese when no script is specified. Urdu uses right-to-left
+document direction, and a later host locale change updates the language and
+direction without reloading the viewer. App-level waiting and rejection screens
+retain English labels in 3.2; host-context support for those shared surface
+screens remains an upstream MCP View follow-up.
+
 ### Navigation and active context
 
 Viewers progressively select the best interaction supported by the host:
@@ -219,8 +256,9 @@ Viewers progressively select the best interaction supported by the host:
   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.
+  bounded embedded resource. The server also requires the MCP client to announce
+  the MCP Apps extension and HTML MIME type before serving file bytes. 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
@@ -244,7 +282,7 @@ 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.2 beta.
+again. Separate MCP Apps are not synchronized automatically in 3.2.
 
 ### Building UI viewers
 
@@ -254,6 +292,14 @@ npm ci
 node build-all.mjs
 ```
 
+For local iteration, run `deno task ui:dev-host` from the repository root. The
+[local test host](src/ui/dev-host/README.md) uses the actual local MCP server
+and its built viewers, rebuilding and reloading them without restarting the
+desktop client. Open `http://127.0.0.1:5177/?viewer=doclist` for the real
+Company list. The host records viewer context updates but has no connected model
+or conversation; model consumption and conversational actions require a desktop
+host check.
+
 ## Buy evidence capture
 
 **One** read-only tool and **one** recorded App. They do not purchase, create a
@@ -267,8 +313,9 @@ live ERPNext instance.
   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.2.0-beta.1`, resource
-  `ui://mcp-erpnext/buy-evidence-viewer` (`text/html;profile=mcp-app`), manifest
+- App: `io.casys.mcp-erpnext.buy-evidence`, App version `3.1.0` (independent of
+  the package version), 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
@@ -375,12 +422,3 @@ started, and [AGENTS.md](AGENTS.md) for the full architecture and conventions.
 ## License
 
 MIT
-
-Viewers and Buy result fields use the host locale: English, French, Simplified
-Chinese, Traditional Chinese, Hindi, Bengali, Tamil and Urdu. Chinese script
-tags take precedence over region tags; `zh-TW`, `zh-HK` and `zh-MO` select
-Traditional Chinese when no script is specified. Urdu uses right-to-left
-document direction, and a later host locale change updates the language and
-direction without reloading the viewer. App-level waiting and rejection screens
-retain English labels in this beta; host-context support for those shared
-surface screens remains an upstream MCP View follow-up.