@casys/mcp-erpnext 2.5.0 → 3.0.0

package/README.md

@@ -1,3 +1,5 @@
+English | [繁體中文](README.zh-TW.md)
+
 # @casys/mcp-erpnext
 
 [![JSR](https://jsr.io/badges/@casys/mcp-erpnext)](https://jsr.io/@casys/mcp-erpnext)
@@ -6,7 +8,7 @@
 [![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 — **123 tools**
+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
@@ -73,6 +75,17 @@ 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.
 
+## 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)                                                                                |
+
 ## Quick Start
 
 ### Prerequisites
@@ -146,30 +159,9 @@ Add to `.vscode/mcp.json`:
 
 ### HTTP mode
 
-```bash
-ERPNEXT_URL=http://localhost:8000 \
-ERPNEXT_API_KEY=xxx \
-ERPNEXT_API_SECRET=xxx \
-npx -y @casys/mcp-erpnext --http --port=3012
-```
-
-> **Note:** HTTP mode binds to `127.0.0.1` (loopback) by default as of v2.4.2.
-> For Docker or multi-host setups, add `--hostname=0.0.0.0`.
-
-### Deno (HTTP mode)
-
-```bash
-ERPNEXT_URL=http://localhost:8000 \
-ERPNEXT_API_KEY=xxx \
-ERPNEXT_API_SECRET=xxx \
-deno run -A npm:@casys/mcp-erpnext --http --port=3012
-```
-
-> **Note:** Versions ≤ 2.3.1 of the npm bundle crashed with
-> `ReferenceError: Deno is not defined` in HTTP mode — fixed in 2.4.0
-> (`@casys/mcp-server` ≥ 0.21.1). If you hit this error, upgrade with
-> `npx -y @casys/mcp-erpnext@latest`, or use the Deno runner above. See
-> [`docs/known-issues.md`](docs/known-issues.md).
+For a shared, always-on server rather than one process per client:
+[how to run the HTTP server](docs/http-deployment.md). Note it is breaking for
+pre-2026 HTTP clients in 3.0.0.
 
 ### Category filtering
 
@@ -181,18 +173,9 @@ npx -y @casys/mcp-erpnext --categories=sales,inventory
 
 ## Fresh Instance Setup
 
-On a fresh ERPNext instance (no setup wizard), you need to create master data
-before using business tools. Use `erpnext_doc_create` for prerequisites:
-
-```
-1. Warehouse Types: Transit, Default
-2. UOMs: Nos, Kg, Unit, Set, Meter
-3. Item Groups: All Item Groups (is_group=1), then Products, Raw Material (parent=All Item Groups)
-4. Territories: All Territories (is_group=1), then France, etc.
-5. Customer Groups: All Customer Groups (is_group=1), then Commercial, etc.
-6. Supplier Groups: All Supplier Groups (is_group=1), then Hardware, etc.
-7. Company: requires Warehouse Types to exist first
-```
+A blank ERPNext instance has no master data, so business tools fail validation
+until it exists. See
+[Seed a blank ERPNext instance](docs/fresh-instance-setup.md).
 
 ## UI Viewers
 
@@ -239,9 +222,9 @@ npm install
 node build-all.mjs
 ```
 
-## Tools (123)
+## Tools (124)
 
-123 tools across 14 categories. Each `_list` tool returns interactive results
+124 tools across 14 categories. Each `_list` tool returns interactive results
 via the doclist-viewer with row click, inline detail, and cross-viewer
 navigation.
 
@@ -258,8 +241,8 @@ navigation.
 - **Manufacturing** (7) — BOMs, Work Orders, and Job Cards.
 - **CRM** (8) — Leads, Opportunities, Contacts, and Campaigns.
 - **Assets** (8) — Assets, Movements, Maintenance records, and Categories.
-- **Operations** (9) — Generic CRUD and native assignment for any DocType
-  (`erpnext_doc_*`).
+- **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
   drag-and-drop.
 - **Analytics** (17) — 11 analytics charts (bar, area, treemap, radar, scatter,
@@ -270,112 +253,46 @@ 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                                                                                 |
+| 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)                                                    |
+| `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
+error instead of prompting for a selection.
+
+> **Do not run MRTR behind a load balancer with this configuration.** The
+> signing key proves a retry token is authentic; it does not make it single-use.
+> That is the job of a replay store, and the default one is process-local. Share
+> the key across two instances and the same signed retry validates on both —
+> creating the purchase order, leave application or expense claim **twice**,
+> irreversibly once submitted.
+>
+> A multi-instance deployment must pass a shared atomic `mrtr.replayStore` to
+> `McpApp` (Redis satisfies the contract with `SET key 1 NX EXAT`). The
+> framework logs a warning at startup whenever MRTR is enabled without one —
+> that warning is not noise, it is this paragraph.
 
 ## Architecture
 
-```
-server.ts           # MCP server (stdio + HTTP + inspector)
-mod.ts              # Public API
-deno.json           # Package config
-src/
-  api/
-    frappe-client.ts  # Frappe REST HTTP client (zero-dependency)
-    types.ts          # Frappe type definitions
-  kanban/
-    adapters/         # Per-DocType kanban adapters (task, opportunity, issue)
-    definitions.ts    # Board registry
-    types.ts          # Shared kanban contracts
-  tools/
-    sales.ts          # 17 sales tools
-    inventory.ts      # 9 inventory tools
-    purchasing.ts     # 11 purchasing tools
-    accounting.ts     # 6 accounting tools
-    hr.ts             # 12 HR tools
-    project.ts        # 9 project tools
-    delivery.ts       # 5 delivery tools
-    manufacturing.ts  # 7 manufacturing tools
-    crm.ts            # 8 CRM tools
-    assets.ts         # 8 asset tools
-    operations.ts     # 9 generic CRUD tools
-    setup.ts          # 3 company/setup tools
-    kanban.ts         # 2 read-write kanban tools
-    analytics.ts      # 17 analytics tools (charts, KPIs, funnel)
-    ui-refresh.ts     # Auto-inject _rowAction, _sendMessageHints, _drillDown
-    mod.ts            # Tool registry
-    types.ts          # Tool interface
-  client.ts           # ErpNextToolsClient
-  runtime.ts          # Deno runtime adapter
-  runtime.node.ts     # Node.js runtime adapter
-  *_test.ts           # Tests are colocated with source files
-  ui/
-    shared/           # ActionButton, InfoField, theme, branding, refresh
-    doclist-viewer/   # Generic document list (inline detail, chip filters)
-    invoice-viewer/   # Invoice display (item drill-down, actions)
-    stock-viewer/     # Stock balance (detail panel, sendMessage)
-    chart-viewer/     # Universal chart renderer (12 types, click drill-down)
-    kanban-viewer/    # Read-write kanban (drag, edit, sendMessage)
-    kpi-viewer/       # KPI card (clickable number + sparkline)
-    funnel-viewer/    # Sales funnel (trapezoid stages, click-through)
-    viewers.ts        # Viewer registry
-docs/
-  ROADMAP.md          # Feature roadmap
-  coverage.md         # Test coverage matrix
-```
+Tools are grouped by business domain under `src/tools/`, the Frappe REST client
+is dependency-free, and each UI viewer is a separate build under `src/ui/`. Full
+layout: [repository layout](docs/architecture.md).
 
 ## npm Package
 
 The npm package (`@casys/mcp-erpnext`) is a single self-contained bundle with
 zero runtime dependencies. UI viewers are embedded. Requires Node >= 20.
 
-## Development
-
-```bash
-# Run tests
-deno test --allow-all src/
-
-# Type check
-deno task check
-
-# Start HTTP server (dev)
-deno task serve
-
-# Launch MCP Inspector
-deno task inspect
-
-# Build UI viewers
-deno task ui:build
-
-# Full local release preflight (no publish)
-deno task release:check
-
-# Dev a specific viewer with HMR
-cd src/ui && npm run dev:kanban
-```
-
 ## Contributing
 
 Contributions are welcome — see **[CONTRIBUTING.md](CONTRIBUTING.md)** to get
 started, and [AGENTS.md](AGENTS.md) for the full architecture and conventions.
 
-## Release Flow
-
-Releases are manual and explicit:
-
-1. Update `deno.json`, `server.ts`, and `CHANGELOG.md`.
-2. Run `deno task release:check` locally.
-3. Commit and push the release commit to `main`.
-4. Create the GitHub release/tag, for example `v2.3.0`.
-5. Run the `Publish` workflow manually to publish the same version to JSR and
-   npm.
-
-The package name stays `@casys/mcp-erpnext`; releases only bump the package
-version.
-
 ## License
 
 MIT