@hvgllc/hvgerp-mcp 3.0.3 → 3.5.0

package/README.md

@@ -5,8 +5,8 @@
 [![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 — **125 tools**
-across **14 categories**, with **7 interactive UI viewers**.
+MCP server for [ERPNext](https://erpnext.com) / Frappe ERP: **135 tools** across
+**16 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
@@ -223,33 +223,58 @@ npm install
 node build-all.mjs
 ```
 
-## Tools (125)
+## Tools (135)
 
-125 tools across 14 categories. Each `_list` tool returns interactive results
+135 tools across 16 categories. Most `_list` tools return interactive results
 via the doclist-viewer with row click, inline detail, and cross-viewer
-navigation.
-
+navigation. The read-only `erpnext_stock_ledger_list` instead returns bounded
+ledger rows for the stock viewer's Recent Movements panel.
+
+- **Identity** (2) — `erpnext_whoami` (who the server believes the caller is:
+  User id, roles, linked Employee, and whether the connection is per-caller or a
+  shared service account) and `erpnext_my_work` (everything currently open for
+  that person). Call `erpnext_whoami` before answering any first-person request:
+  every other tool needs a concrete user or employee id, and this is the only
+  one that produces it.
 - **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
-  Entries, and Expense Claims.
+- **Inventory** (10): Items, Stock Balance, Warehouses, Stock Entries, and
+  recent Stock Ledger Entries filtered by the required item and warehouse.
+- **Accounting** (8) — Chart of Accounts (filterable by `disabled`), Journal
+  Entries, and Payment Entries, plus `erpnext_gl_entry_list` (the posted general
+  ledger, cancelled entries excluded by default) and `erpnext_financial_report`,
+  which runs a standard financial report (Profit and Loss Statement, Balance
+  Sheet, General Ledger, Trial Balance…) from a closed allowlist and never
+  queues a Prepared Report.
+- **HR** (15) — Employees, Attendance, Leave Applications, Salary Slips, Payroll
+  Entries, and Expense Claims, plus attendance repair:
+  `erpnext_employee_checkin_list` (the raw punch log, where a day that never
+  closed shows up), `erpnext_attendance_day_get` and
+  `erpnext_attendance_day_fix`, which add the missing punches and rebuild that
+  day's Attendance even when the existing record is already submitted. The last
+  two need the `hvg_workspace` app on the site, because the day is recomputed by
+  the site's own rule rather than by a copy of it living here.
 - **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** (11) — Generic CRUD, native assignment, and file upload for any
+- **Operations** (12) — Generic CRUD, native assignment, and file upload for any
   DocType (`erpnext_doc_*`, `erpnext_file_upload`), plus `erpnext_method_call`
-  for allowlisted whitelisted-method calls.
+  for allowlisted whitelisted-method calls and `erpnext_calendar_events`, which
+  reads a date range the way the ERPNext calendar does so a repeating event
+  appears once per occurrence instead of once in total.
 - **Kanban** (2) — 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.
+- **Discovery** (1) — `erpnext_doctype_fields`: the field schema of any DocType
+  (name, label, type, link target, mandatory, permlevel), gated on the caller's
+  own read permission. Use it instead of inferring a schema from one sample
+  document, which only shows the fields that happen to be filled in.
 
 Full per-tool reference with parameters: [`docs/tools.md`](docs/tools.md).
 
@@ -258,12 +283,33 @@ Full per-tool reference with parameters: [`docs/tools.md`](docs/tools.md).
 | 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_API_KEY`          | stdio    | API Key from User Settings. Over HTTP, leave it unset and let each caller's own token decide who the server acts as (see _Caller identity_)                              |
+| `ERPNEXT_API_SECRET`       | stdio    | API Secret from User Settings                                                                                                                                            |
+| `MCP_CALLER_IDENTITY`      | No       | `required` \| `optional` \| `off`. HTTP only. Defaults to `required` when no API key/secret is set, `off` when they are                                                  |
 | `ERPNEXT_MAX_UPLOAD_BYTES` | No       | Maximum decoded file-upload size in bytes (positive integer; default: 10 MiB)                                                                                            |
 | `ERPNEXT_METHOD_ALLOWLIST` | No       | Comma-separated dotted paths or `prefix.*` patterns that `erpnext_method_call` may invoke. Unset means no extra restriction beyond the API key's own ERPNext permissions |
 | `MCP_MRTR_SIGNING_KEY`     | No       | Exactly 64 lowercase hex characters; enables signed ambiguous-link elicitation. **Single-instance deployments only** — see below                                         |
 
+### Caller identity (HTTP)
+
+Over HTTP the server can act **as the user who made the call** instead of under
+one shared ERPNext account. Each tool call forwards that user's own verified
+access token to Frappe as `Authorization: HVGKeycloak <token>`; Frappe resolves
+it to a `User` and applies that user's roles and row-level permissions. Two
+people calling the same tool therefore get different rows, and every write is
+attributed to the person who asked for it.
+
+This needs an OAuth/OIDC auth provider (`MCP_OAUTH_JWKS_URL`) whose tokens carry
+an `email` claim, and an ERPNext side that accepts the scheme. `sub` is not
+accepted as a fallback identity: it maps to no ERPNext user, so a deployment
+with the wrong claims fails loudly instead of quietly serving the wrong data.
+
+`MCP_CALLER_IDENTITY=required` refuses any call that carries no usable identity.
+`optional` binds the identity when present and otherwise falls back to the
+static API key. `off` is the pre-3.1 behaviour. Under `required` the read cache
+is per caller and the startup cache warm is skipped — there is no user to warm
+it as.
+
 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.