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

package/mcp-erpnext.mjs

@@ -18727,8 +18727,8 @@ function isRecursive(inst, stack, resolve) {
       result = answer;
   };
   const def = inst._zod.def;
-  const kind = def.type;
-  switch (kind) {
+  const kind2 = def.type;
+  switch (kind2) {
     case "object": {
       const raw2 = rawShape(def);
       merge2(raw2 ? shape(raw2, true) : ASSUMED);
@@ -18808,7 +18808,7 @@ function isRecursive(inst, stack, resolve) {
     case "custom":
       break;
     default: {
-      kind;
+      kind2;
       for (const key in def) {
         const desc = Object.getOwnPropertyDescriptor(def, key);
         if (!desc || desc.get)
@@ -26730,7 +26730,7 @@ var RESERVED_ENVELOPE_META_KEYS = [
   LOG_LEVEL_META_KEY
 ];
 var RETRY_PARAMS_KEYS = ["inputResponses", "requestState"];
-function liftWireOnlyMaterial(message2, kind) {
+function liftWireOnlyMaterial(message2, kind2) {
   const params = message2.params;
   if (!isPlainObject$1(params)) return {
     message: message2,
@@ -26738,7 +26738,7 @@ function liftWireOnlyMaterial(message2, kind) {
   };
   const meta2 = params._meta;
   const envelopeKeys = isPlainObject$1(meta2) ? RESERVED_ENVELOPE_META_KEYS.filter((key) => key in meta2) : [];
-  const retryKeys = kind === "request" ? RETRY_PARAMS_KEYS.filter((key) => key in params) : [];
+  const retryKeys = kind2 === "request" ? RETRY_PARAMS_KEYS.filter((key) => key in params) : [];
   if (envelopeKeys.length === 0 && retryKeys.length === 0) return {
     message: message2,
     lifted: {}
@@ -48617,6 +48617,9 @@ var FrappeClient = class {
     if (options.order_by) {
       params.set("order_by", options.order_by);
     }
+    if (options.group_by) {
+      params.set("group_by", options.group_by);
+    }
     if (options.limit !== void 0) {
       params.set("limit", String(options.limit));
     }
@@ -48837,6 +48840,20 @@ var FrappeClient = class {
    * the same way the list/resource GET endpoints already do in this client.
    */
   async callMethod(method, args = {}, httpMethod = "POST") {
+    const res = await this.callMethodRaw(
+      method,
+      args,
+      httpMethod
+    );
+    return res.message;
+  }
+  /**
+   * Same call as `callMethod`, but returns the whole response body instead of
+   * its `message`. Needed for methods that fill `frappe.response` rather than
+   * returning a value, such as `frappe.desk.form.load.getdoctype` (`docs` at
+   * the top level, no `message`).
+   */
+  async callMethodRaw(method, args = {}, httpMethod = "POST") {
     if (httpMethod === "GET") {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(args)) {
@@ -48847,18 +48864,9 @@ var FrappeClient = class {
         );
       }
       const query = params.toString() ? `?${params.toString()}` : "";
-      const res2 = await this.request(
-        "GET",
-        `/api/method/${method}${query}`
-      );
-      return res2.message;
+      return await this.request("GET", `/api/method/${method}${query}`);
     }
-    const res = await this.request(
-      "POST",
-      `/api/method/${method}`,
-      args
-    );
-    return res.message;
+    return await this.request("POST", `/api/method/${method}`, args);
   }
 };
 var _client = null;
@@ -50095,6 +50103,215 @@ var salesTools = [
   }
 ];
 
+// src/tools/errors.ts
+var ToolInputError = class extends Error {
+  tool;
+  code;
+  /** What was wrong, without the `[tool] CODE:` prefix or the recovery hint. */
+  detail;
+  recovery;
+  /** Always false for input errors unless stated: resending the same call fails again. */
+  retryable;
+  context;
+  constructor(tool, code, detail, options) {
+    super(formatToolInputError(tool, code, detail, options.recovery));
+    this.name = "ToolInputError";
+    this.tool = tool;
+    this.code = code;
+    this.detail = detail;
+    this.recovery = options.recovery;
+    this.retryable = options.retryable === true;
+    this.context = Object.freeze({ ...options.context ?? {} });
+  }
+};
+function sentence(text) {
+  const trimmed = text.trim();
+  return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+function formatToolError(subject, code, detail, recovery, closeRecoverySentence = false) {
+  return `[${subject}] ${code}: ${detail.trim().replace(/[.!?]$/, "")}. Recovery: ${closeRecoverySentence ? sentence(recovery) : recovery}`;
+}
+function formatToolInputError(tool, code, detail, recovery) {
+  return formatToolError(tool, code, detail, recovery, true);
+}
+
+// src/tools/doc-list-query.ts
+var DOC_LIST_DEFAULT_LIMIT = 20;
+var DEFAULT_ORDER_BY = "modified desc";
+var FILTER_FORMS = "[fieldname, operator, value] or [child doctype, fieldname, operator, value]";
+var FRAPPE_FILTERS_INPUT_SCHEMA = {
+  type: "array",
+  description: "Frappe filters: an array of " + FILTER_FORMS + '. The 4-element form filters on a child table (e.g. ["Sales Invoice Item","item_code","=","SKU-1"]). Values may be strings, numbers, booleans or null, or an array of strings/numbers for "in" / "not in". Example: [["status","=","Open"],["company","=","Acme"]]. Fewer than 3 elements are rejected with INVALID_FILTER. Longer tuples stay accepted for compatibility; Frappe reads only the first 4 elements.',
+  items: {
+    type: "array",
+    items: {
+      anyOf: [
+        { type: "string" },
+        { type: "number" },
+        { type: "boolean" },
+        { type: "null" },
+        {
+          type: "array",
+          items: { anyOf: [{ type: "string" }, { type: "number" }] }
+        }
+      ]
+    }
+  }
+  // `anyOf` nodes carry no `type` on purpose (Gemini rejects both together),
+  // which the shared `JSONSchema` type cannot express.
+};
+function preview(value) {
+  let text;
+  try {
+    text = JSON.stringify(value) ?? String(value);
+  } catch {
+    text = String(value);
+  }
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}
+function kind(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function isFilterValue(value) {
+  if (value === null || typeof value === "string") return true;
+  if (typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  return Array.isArray(value) && value.every(
+    (item) => typeof item === "string" || typeof item === "number" && Number.isFinite(item)
+  );
+}
+function parseFrappeFilters(tool, raw2) {
+  if (raw2 === void 0) return [];
+  const recovery = `Send filters as an array of ${FILTER_FORMS}, for example [["status","=","Open"]].`;
+  if (!Array.isArray(raw2)) {
+    throw new ToolInputError(
+      tool,
+      "INVALID_FILTER",
+      `'filters' must be an array of filter tuples, got ${kind(raw2)}`,
+      { recovery, context: { received: kind(raw2) } }
+    );
+  }
+  raw2.forEach((entry, index) => {
+    const at = `filters[${index}]`;
+    const fail = (detail, extra = {}) => {
+      throw new ToolInputError(
+        tool,
+        "INVALID_FILTER",
+        `${at} ${detail} (got ${preview(entry)})`,
+        { recovery, context: { index, ...extra } }
+      );
+    };
+    if (!Array.isArray(entry)) {
+      fail(`must be an array, got ${kind(entry)}`);
+      return;
+    }
+    if (entry.length < 3) {
+      fail(`has ${entry.length} element(s); expected 3 or 4`, {
+        arity: entry.length
+      });
+      return;
+    }
+    const child = entry.length >= 4;
+    const names = child ? ["child doctype", "fieldname", "operator"] : ["fieldname", "operator"];
+    names.forEach((label, position) => {
+      const value = entry[position];
+      const ok = label === "operator" ? typeof value === "string" : isNonEmptyString(value);
+      if (!ok) {
+        fail(
+          `has an invalid ${label} at position ${position}: expected a ${label === "operator" ? "string" : "non-empty string"}, got ${value === "" || typeof value === "string" && !value.trim() ? "empty string" : kind(value)}`,
+          { position }
+        );
+      }
+    });
+    const valuePosition = child ? 3 : 2;
+    if (!isFilterValue(entry[valuePosition])) {
+      fail(
+        `has an invalid value at position ${valuePosition}: expected a string, number, boolean, null, or an array of strings/numbers`,
+        { position: valuePosition }
+      );
+    }
+  });
+  return raw2;
+}
+function parsePagination(tool, input) {
+  const invalid2 = (field, value) => {
+    throw new ToolInputError(
+      tool,
+      "INVALID_PAGINATION",
+      `'${field}' must be a non-negative integer, got ${preview(value)}`,
+      {
+        recovery: field === "limit" ? "Send an integer >= 1 (default 20), or 0 for every row." : "Send an integer >= 0, or omit 'offset'.",
+        context: { field, value }
+      }
+    );
+  };
+  const limit = input.limit === void 0 ? DOC_LIST_DEFAULT_LIMIT : input.limit;
+  if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 0) {
+    return invalid2("limit", input.limit);
+  }
+  const offset = input.offset;
+  if (offset !== void 0) {
+    if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0) {
+      return invalid2("offset", offset);
+    }
+    if (limit === 0 && offset > 0) {
+      throw new ToolInputError(
+        tool,
+        "INVALID_PAGINATION",
+        `'limit' 0 means "every row" in Frappe, which then ignores 'offset' (${offset}) and would return the wrong rows`,
+        {
+          recovery: "Use a positive 'limit' together with 'offset', or drop 'offset' when 'limit' is 0.",
+          context: { limit, offset }
+        }
+      );
+    }
+    return { limit, offset };
+  }
+  return { limit };
+}
+var QUOTABLE_DOCTYPE = /^[A-Za-z0-9_ -]+$/;
+var PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var BARE_ORDER_CLAUSE = /^`?([A-Za-z_][A-Za-z0-9_]*)`?(?:\s+(asc|desc))?$/i;
+function tableOf(doctype) {
+  return `\`tab${doctype}\``;
+}
+function hasChildTableFilter(doctype, filters) {
+  return filters.some(
+    (filter) => Array.isArray(filter) && filter.length >= 4 && filter[0] !== doctype
+  );
+}
+function qualifyOrderBy(doctype, orderBy) {
+  if (orderBy.includes("(")) return orderBy;
+  return orderBy.split(",").map((clause) => {
+    const trimmed = clause.trim();
+    const bare = BARE_ORDER_CLAUSE.exec(trimmed);
+    return bare ? `${tableOf(doctype)}.${bare[1]}${bare[2] ? ` ${bare[2]}` : ""}` : trimmed;
+  }).join(", ");
+}
+function planListQuery(doctype, input) {
+  const requested = input.order_by;
+  if (!hasChildTableFilter(doctype, input.filters)) {
+    return { order_by: requested ?? DEFAULT_ORDER_BY };
+  }
+  if (!QUOTABLE_DOCTYPE.test(doctype)) {
+    return requested === void 0 ? {} : { order_by: requested };
+  }
+  const order_by = qualifyOrderBy(doctype, requested ?? DEFAULT_ORDER_BY);
+  if (order_by === "") return {};
+  const parentColumn = `${tableOf(doctype)}.`;
+  const parentOnly = input.fields.every(
+    (field) => field === "*" || PLAIN_IDENTIFIER.test(field)
+  ) && order_by.split(",").every(
+    (clause) => clause.trim().startsWith(parentColumn)
+  );
+  return parentOnly ? { order_by, group_by: `${parentColumn}name` } : { order_by };
+}
+
 // src/tools/inventory.ts
 var inventoryTools = [
   // ── Items ─────────────────────────────────────────────────────────────────
@@ -50398,7 +50615,9 @@ var inventoryTools = [
       }
     },
     handler: async (input, ctx) => {
-      const limit = input.limit ?? 20;
+      const { limit } = parsePagination("erpnext_stock_entry_list", {
+        limit: input.limit ?? void 0
+      });
       const filters = [];
       if (input.item_code) {
         filters.push([
@@ -50421,18 +50640,24 @@ var inventoryTools = [
       if (input.date_to) {
         filters.push(["posting_date", "<=", input.date_to]);
       }
+      const fields = [
+        "name",
+        "stock_entry_type",
+        "posting_date",
+        "from_warehouse",
+        "to_warehouse",
+        "total_amount"
+      ];
+      const { order_by, group_by } = planListQuery("Stock Entry", {
+        filters,
+        fields
+      });
       const docs = await ctx.client.list("Stock Entry", {
-        fields: [
-          "name",
-          "stock_entry_type",
-          "posting_date",
-          "from_warehouse",
-          "to_warehouse",
-          "total_amount"
-        ],
+        fields,
         filters,
         limit,
-        order_by: "modified desc"
+        ...order_by !== void 0 ? { order_by } : {},
+        ...group_by !== void 0 ? { group_by } : {}
       });
       return {
         doctype: "Stock Entry",
@@ -50684,7 +50909,7 @@ var accountingTools = [
     name: "erpnext_payment_entry_list",
     annotations: { readOnlyHint: true },
     _meta: DOCLIST_META,
-    description: "List Payment Entries. Filterable by payment_type, party_type, date range. Fields: name, payment_type, party_type, party, posting_date, paid_amount, currency. payment_type values: Receive, Pay, Internal Transfer.",
+    description: "List Payment Entries. Filterable by payment_type, party_type, date range. Fields: name, payment_type, party_type, party, posting_date, paid_amount, currency, received_amount, paid_from_account_currency, paid_to_account_currency. currency is an alias of paid_from_account_currency and applies to paid_amount. received_amount uses paid_to_account_currency. The party is the source for Receive and destination for Pay. payment_type values: Receive, Pay, Internal Transfer.",
     category: "accounting",
     inputSchema: {
       type: "object",
@@ -50747,7 +50972,9 @@ var accountingTools = [
           "party",
           "posting_date",
           "paid_amount",
-          "currency"
+          "received_amount",
+          "paid_from_account_currency",
+          "paid_to_account_currency"
         ],
         filters,
         limit,
@@ -50756,7 +50983,10 @@ var accountingTools = [
       return {
         doctype: "Payment Entry",
         count: docs.length,
-        data: docs,
+        data: docs.map((doc) => ({
+          ...doc,
+          currency: doc.paid_from_account_currency
+        })),
         _meta: DOCLIST_META
       };
     }
@@ -52930,7 +53160,7 @@ var deliveryTools = [
     name: "erpnext_shipment_list",
     annotations: { readOnlyHint: true },
     _meta: DOCLIST_META,
-    description: "List Shipments. Filterable by status, pickup_from date range. Fields: name, status, pickup_date, delivery_date, carrier, shipment_amount.",
+    description: "List Shipments. Filterable by status, pickup_date range, and carrier. Fields: name, status, pickup_date, carrier, shipment_amount.",
     category: "delivery",
     inputSchema: {
       type: "object",
@@ -52938,7 +53168,7 @@ var deliveryTools = [
         limit: { type: "number", description: "Max results (default 20)" },
         status: {
           type: "string",
-          description: "Filter by status (Draft, Submitted, Booked, Delivered, Cancelled, etc.)"
+          description: "Filter by status (Draft, Submitted, Booked, Completed, Cancelled)"
         },
         carrier: { type: "string", description: "Filter by carrier name" },
         date_from: {
@@ -52971,7 +53201,6 @@ var deliveryTools = [
           "name",
           "status",
           "pickup_date",
-          "delivery_date",
           "carrier",
           "shipment_amount"
         ],
@@ -53688,7 +53917,7 @@ var assetsTools = [
     name: "erpnext_asset_list",
     annotations: { readOnlyHint: true },
     _meta: DOCLIST_META,
-    description: "List Fixed Assets. Filterable by status, asset_category, location, custodian. Fields: name, asset_name, asset_category, status, purchase_date, gross_purchase_amount, current_value, location, custodian.",
+    description: "List Fixed Assets. Filterable by status, asset_category, location, custodian. Fields: name, asset_name, asset_category, status, purchase_date, gross_purchase_amount, net_purchase_amount, current_value, value_after_depreciation, location, custodian. gross_purchase_amount is an alias of net_purchase_amount (the ERPNext v15 field was renamed in v16). current_value is an alias of value_after_depreciation, the book value rather than market value.",
     category: "assets",
     inputSchema: {
       type: "object",
@@ -53745,17 +53974,8 @@ var assetsTools = [
         filters.push(["purchase_date", "<=", input.date_to]);
       }
       const docs = await ctx.client.list("Asset", {
-        fields: [
-          "name",
-          "asset_name",
-          "asset_category",
-          "status",
-          "purchase_date",
-          "gross_purchase_amount",
-          "current_value",
-          "location",
-          "custodian"
-        ],
+        // The purchase amount was renamed in v16. Project only the list columns below.
+        fields: ["*"],
         filters,
         limit,
         order_by: "modified desc"
@@ -53763,7 +53983,27 @@ var assetsTools = [
       return {
         doctype: "Asset",
         count: docs.length,
-        data: docs,
+        data: docs.map((doc) => {
+          if (!("net_purchase_amount" in doc) && !("gross_purchase_amount" in doc)) {
+            throw new Error(
+              "[erpnext_asset_list] Asset has no supported net purchase amount field"
+            );
+          }
+          const purchaseAmount = "net_purchase_amount" in doc ? doc.net_purchase_amount : doc.gross_purchase_amount;
+          return {
+            name: doc.name,
+            asset_name: doc.asset_name,
+            asset_category: doc.asset_category,
+            status: doc.status,
+            purchase_date: doc.purchase_date,
+            gross_purchase_amount: purchaseAmount,
+            net_purchase_amount: purchaseAmount,
+            current_value: doc.value_after_depreciation,
+            value_after_depreciation: doc.value_after_depreciation,
+            location: doc.location,
+            custodian: doc.custodian
+          };
+        }),
         _meta: DOCLIST_META
       };
     }
@@ -53791,7 +54031,7 @@ var assetsTools = [
   },
   {
     name: "erpnext_asset_create",
-    description: "Create a new Asset record. Requires asset_name, asset_category, company, purchase_date, gross_purchase_amount. Optionally set location, custodian, item_code.",
+    description: "Create a new Asset record. Requires asset_name, asset_category, company, purchase_date, gross_purchase_amount (net purchase amount before depreciation, using the legacy field name). Supports ERPNext v15 and v16. Set a fixed asset item_code and location as required by ERPNext.",
     category: "assets",
     inputSchema: {
       type: "object",
@@ -53811,11 +54051,11 @@ var assetsTools = [
         },
         gross_purchase_amount: {
           type: "number",
-          description: "Purchase cost (before depreciation)"
+          description: "Net purchase amount before depreciation (legacy parameter name)"
         },
         item_code: {
           type: "string",
-          description: "Linked item code (optional)"
+          description: "Fixed asset item code (required by ERPNext)"
         },
         location: {
           type: "string",
@@ -53857,7 +54097,9 @@ var assetsTools = [
         asset_category: input.asset_category,
         company: input.company,
         purchase_date: input.purchase_date,
+        // Frappe persists only DocType fields; v15/v16 use different names for this amount.
         gross_purchase_amount: input.gross_purchase_amount,
+        net_purchase_amount: input.gross_purchase_amount,
         item_code: input.item_code ?? void 0,
         location: input.location ?? void 0,
         custodian: input.custodian ?? void 0
@@ -54046,6 +54288,27 @@ var assetsTools = [
   }
 ];
 
+// src/tools/file-download-error.ts
+var FILE_DOWNLOAD_TOOL_NAME = "erpnext_file_download";
+var FileDownloadError = class extends Error {
+  code;
+  detail;
+  retryable;
+  context;
+  recovery;
+  constructor(code, detail, options) {
+    super(
+      formatToolError(FILE_DOWNLOAD_TOOL_NAME, code, detail, options.recovery)
+    );
+    this.name = "FileDownloadError";
+    this.code = code;
+    this.detail = detail;
+    this.retryable = options.retryable === true;
+    this.context = Object.freeze({ ...options.context ?? {} });
+    this.recovery = options.recovery;
+  }
+};
+
 // src/tools/method-allowlist.ts
 var METHOD_PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
 function isValidMethodPath(method) {
@@ -54129,8 +54392,6 @@ function isEmptyPartyAccountCurrencyNone(text) {
 }
 
 // src/tools/operations.ts
-var DOC_LIST_MAX_LIMIT = 5e3;
-var DOC_LIST_MAX_OFFSET = 1e5;
 function bytesToBase64(bytes) {
   const chunkSize = 32 * 1024;
   let binary = "";
@@ -54141,6 +54402,23 @@ function bytesToBase64(bytes) {
   }
   return btoa(binary);
 }
+function assertMcpAppsClient(ctx) {
+  const capability = getMcpAppsCapability(ctx.clientCapabilities);
+  if (capability?.mimeTypes?.includes(MCP_APP_MIME_TYPE) === true) return;
+  throw new FileDownloadError(
+    "APP_CONTEXT_REQUIRED",
+    "attachment content is only served to MCP Apps hosts, never to the model",
+    {
+      context: {
+        tool: FILE_DOWNLOAD_TOOL_NAME,
+        requiredExtension: MCP_APPS_EXTENSION_ID,
+        requiredMimeType: MCP_APP_MIME_TYPE,
+        clientAnnouncedExtension: capability !== void 0
+      },
+      recovery: "open the document in an MCP Apps viewer to download the attachment; use erpnext_file_list to read attachment metadata (name, size, file_url)"
+    }
+  );
+}
 async function withPiAccountHintsIfNeeded(doctype, fn) {
   return isPurchaseInvoiceDoctype(doctype) ? await withPurchaseInvoiceAccountHints(fn) : await fn();
 }
@@ -54230,7 +54508,7 @@ var operationsTools = [
         visibility: ["app"]
       }
     },
-    description: "Download one ERPNext attachment for the document viewer. The tool accepts a File ID, verifies its document attachment, and returns one embedded binary resource.",
+    description: "Download one ERPNext attachment for the document viewer. The tool accepts a File ID, verifies its document attachment, and returns one embedded binary resource. Refused with APP_CONTEXT_REQUIRED unless the MCP client announces the MCP Apps extension.",
     category: "operations",
     inputSchema: {
       type: "object",
@@ -54266,6 +54544,7 @@ var operationsTools = [
           );
         }
       }
+      assertMcpAppsClient(ctx);
       const file = await ctx.client.downloadFile({
         fileId: input.file_id.trim(),
         attachedToDoctype: input.attached_to_doctype.trim(),
@@ -54639,7 +54918,7 @@ var operationsTools = [
     name: "erpnext_doc_list",
     annotations: { readOnlyHint: true },
     _meta: DOCLIST_META,
-    description: "List any ERPNext documents by DocType. Useful for DocTypes not covered by dedicated tools. Supports field selection, filters (as JSON array), bounded pagination, and an optional fresh read.",
+    description: "List any ERPNext documents by DocType. Useful for DocTypes not covered by dedicated tools. Supports field selection, filters (as JSON array, including child-table filters), limit/offset pagination, and an optional fresh read. Errors read '[erpnext_doc_list] CODE: message. Recovery: ...'.",
     category: "operations",
     inputSchema: {
       type: "object",
@@ -54653,67 +54932,16 @@ var operationsTools = [
           description: "Fields to fetch (default: ['name', 'modified']). Use ['*'] for all fields.",
           items: { type: "string" }
         },
-        filters: {
-          type: "array",
-          description: 'Frappe filters as array of [fieldname, operator, value] tuples, or [child doctype, fieldname, operator, value] to filter on a child table. Values may be strings, numbers, booleans, null, or string/number arrays for in/not in. Example: [["status","=","Open"],["company","=","Acme"]]',
-          items: {
-            type: "array",
-            anyOf: [
-              {
-                prefixItems: [
-                  { type: "string", minLength: 1 },
-                  { type: "string", minLength: 1 },
-                  {
-                    oneOf: [
-                      { type: ["string", "number", "boolean", "null"] },
-                      {
-                        type: "array",
-                        items: { type: ["string", "number"] }
-                      }
-                    ]
-                  }
-                ],
-                minItems: 3,
-                maxItems: 3
-              },
-              {
-                prefixItems: [
-                  { type: "string", minLength: 1 },
-                  { type: "string", minLength: 1 },
-                  { type: "string", minLength: 1 },
-                  {
-                    oneOf: [
-                      { type: ["string", "number", "boolean", "null"] },
-                      {
-                        type: "array",
-                        items: { type: ["string", "number"] }
-                      }
-                    ]
-                  }
-                ],
-                minItems: 4,
-                maxItems: 4
-              },
-              {
-                // 3.0.x advertised arbitrary string arrays. Keep accepting
-                // that legacy surface while describing real 3/4-part Frappe
-                // tuples precisely for modern clients.
-                items: { type: "string" }
-              }
-            ]
-          }
-        },
+        filters: FRAPPE_FILTERS_INPUT_SCHEMA,
         limit: {
           type: "integer",
-          minimum: 1,
-          maximum: DOC_LIST_MAX_LIMIT,
-          description: "Max results (default 20, maximum 5000)"
+          minimum: 0,
+          description: `Max rows (default ${DOC_LIST_DEFAULT_LIMIT}). No server-side cap. 0 = every row (Frappe semantics), potentially very large: prefer limit + offset. limit 0 cannot be combined with offset > 0 (INVALID_PAGINATION).`
         },
         offset: {
           type: "integer",
           minimum: 0,
-          maximum: DOC_LIST_MAX_OFFSET,
-          description: "Pagination offset (default 0, maximum 100000)"
+          description: "Rows to skip (default 0), for pagination with a positive limit."
         },
         skip_cache: {
           type: "boolean",
@@ -54727,33 +54955,66 @@ var operationsTools = [
       required: ["doctype"]
     },
     handler: async (input, ctx) => {
-      if (!input.doctype) {
-        throw new Error("[erpnext_doc_list] 'doctype' is required");
+      const tool = "erpnext_doc_list";
+      if (typeof input.doctype !== "string" || !input.doctype.trim()) {
+        throw new ToolInputError(
+          tool,
+          "INVALID_INPUT",
+          "'doctype' is required and must be a non-empty string",
+          {
+            recovery: "Pass the DocType name, e.g. doctype: 'Lead'.",
+            context: { field: "doctype" }
+          }
+        );
       }
-      if (input.limit !== void 0 && (typeof input.limit !== "number" || !Number.isInteger(input.limit) || input.limit < 1 || input.limit > DOC_LIST_MAX_LIMIT)) {
-        throw new Error(
-          `[erpnext_doc_list] 'limit' must be an integer between 1 and ${DOC_LIST_MAX_LIMIT}`
+      if (input.skip_cache !== void 0 && typeof input.skip_cache !== "boolean") {
+        throw new ToolInputError(
+          tool,
+          "INVALID_INPUT",
+          "'skip_cache' must be a boolean",
+          {
+            recovery: "Pass true to bypass the list cache, or omit it.",
+            context: { field: "skip_cache" }
+          }
         );
       }
-      if (input.offset !== void 0 && (typeof input.offset !== "number" || !Number.isInteger(input.offset) || input.offset < 0 || input.offset > DOC_LIST_MAX_OFFSET)) {
-        throw new Error(
-          `[erpnext_doc_list] 'offset' must be an integer between 0 and ${DOC_LIST_MAX_OFFSET}`
+      if (input.fields !== void 0 && (!Array.isArray(input.fields) || input.fields.some((field) => typeof field !== "string"))) {
+        throw new ToolInputError(
+          tool,
+          "INVALID_INPUT",
+          "'fields' must be an array of strings",
+          {
+            recovery: "Pass field names, e.g. ['name', 'status'], or ['*'].",
+            context: { field: "fields" }
+          }
         );
       }
-      if (input.skip_cache !== void 0 && typeof input.skip_cache !== "boolean") {
-        throw new Error("[erpnext_doc_list] 'skip_cache' must be a boolean");
+      if (input.order_by !== void 0 && typeof input.order_by !== "string") {
+        throw new ToolInputError(
+          tool,
+          "INVALID_INPUT",
+          "'order_by' must be a string",
+          {
+            recovery: "Pass a clause such as 'modified desc', or omit it.",
+            context: { field: "order_by" }
+          }
+        );
       }
-      const limit = input.limit ?? 20;
+      const { limit, offset } = parsePagination(tool, input);
+      const filters = parseFrappeFilters(tool, input.filters);
       const fields = input.fields ?? ["name", "modified"];
-      const filters = input.filters ?? [];
-      const order_by = input.order_by ?? "modified desc";
-      const offset = input.offset;
+      const { order_by, group_by } = planListQuery(input.doctype, {
+        filters,
+        fields,
+        order_by: input.order_by
+      });
       const listOptions = {
         fields,
         filters,
         limit,
         ...offset !== void 0 ? { limit_start: offset } : {},
-        order_by
+        ...order_by !== void 0 ? { order_by } : {},
+        ...group_by !== void 0 ? { group_by } : {}
       };
       const docs = input.skip_cache === true ? await ctx.client.list(input.doctype, listOptions, {
         skipCache: true
@@ -55106,6 +55367,129 @@ var setupTools = [
   }
 ];
 
+// src/tools/analytics-money.ts
+function moneyScopeSchema(currencyDescription) {
+  return {
+    type: "object",
+    properties: {
+      company: {
+        type: "string",
+        minLength: 1,
+        description: "Filter by company name"
+      },
+      currency: {
+        type: "string",
+        minLength: 1,
+        description: currencyDescription
+      }
+    }
+  };
+}
+function normalizedCurrency(value) {
+  const trimmed = value.trim();
+  return /^[a-z]{3}$/i.test(trimmed) ? trimmed.toUpperCase() : trimmed;
+}
+function parseMoneyScope(tool, input) {
+  const scope = {};
+  for (const field of ["company", "currency"]) {
+    const value = input[field];
+    if (value === void 0) continue;
+    if (typeof value !== "string" || !value.trim()) {
+      throw new ToolInputError(
+        tool,
+        "INVALID_INPUT",
+        `'${field}' must be a non-empty string`,
+        {
+          context: { field },
+          recovery: `Pass the exact ${field} name, or omit '${field}' to include every ${field}.`
+        }
+      );
+    }
+    scope[field] = field === "currency" ? normalizedCurrency(value) : value.trim();
+  }
+  return scope;
+}
+function moneyScopeFilters(scope, currencyField = "currency") {
+  return [
+    ...scope.company ? [["company", "=", scope.company]] : [],
+    ...scope.currency ? [[currencyField, "=", scope.currency]] : []
+  ];
+}
+var AnalyticsDataError = class extends Error {
+  constructor(tool, code, detail, recovery, context2 = {}) {
+    super(formatToolError(tool, code, detail, recovery));
+    this.tool = tool;
+    this.code = code;
+    this.recovery = recovery;
+    this.name = "AnalyticsDataError";
+    this.context = Object.freeze({ ...context2 });
+  }
+  retryable = false;
+  context;
+};
+function moneyValues(tool, rows, amountField, currencyField, selectedCurrency) {
+  const currencies = /* @__PURE__ */ new Set();
+  const amounts = rows.map((row, index) => {
+    const document = typeof row.name === "string" ? `document '${row.name}'` : `document at row ${index}`;
+    const currency2 = row[currencyField];
+    if (typeof currency2 !== "string" || !currency2.trim()) {
+      throw new AnalyticsDataError(
+        tool,
+        "MISSING_CURRENCY",
+        `Cannot determine '${currencyField}' for ${document}`,
+        `Inspect and repair '${currencyField}' on the source document; no currency is guessed.`,
+        { currencyField, name: row.name, index }
+      );
+    }
+    currencies.add(normalizedCurrency(currency2));
+    const raw2 = row[amountField];
+    const amount = typeof raw2 === "number" || typeof raw2 === "string" && raw2.trim() ? Number(raw2) : Number.NaN;
+    if (!Number.isFinite(amount)) {
+      throw new AnalyticsDataError(
+        tool,
+        "INVALID_AMOUNT",
+        `${document} has no finite '${amountField}'`,
+        `Inspect and repair '${amountField}' on the source document before calculating this KPI.`,
+        { amountField, name: row.name, index }
+      );
+    }
+    return amount;
+  });
+  if (currencies.size > 1 || selectedCurrency && currencies.size === 1 && !currencies.has(selectedCurrency)) {
+    throw new AnalyticsDataError(
+      tool,
+      "MIXED_CURRENCIES",
+      `Amounts in '${currencyField}' have incompatible currencies: ${[...currencies].sort().join(", ")}`,
+      "Call this KPI with one 'currency' (and optionally 'company'); amounts in different currencies are never added or converted.",
+      { currencyField, currencies: [...currencies].sort(), selectedCurrency }
+    );
+  }
+  const currency = currencies.values().next().value ?? selectedCurrency;
+  return { ...currency ? { currency } : {}, amounts };
+}
+function sumMoney(tool, amounts) {
+  let sum = 0;
+  let correction = 0;
+  for (const amount of amounts) {
+    const corrected = amount - correction;
+    const next = sum + corrected;
+    correction = next - sum - corrected;
+    sum = next;
+  }
+  if (!Number.isFinite(sum)) {
+    throw new AnalyticsDataError(
+      tool,
+      "INVALID_AMOUNT",
+      "The total exceeds the supported numeric range",
+      "Narrow this KPI with 'company' or 'currency' and inspect unusually large source amounts."
+    );
+  }
+  return sum;
+}
+function formatMoney(amount, currency) {
+  return currency && /^[A-Z]{3}$/.test(currency) ? amount.toLocaleString("en-US", { style: "currency", currency }) : `${amount.toLocaleString("en-US")}${currency ? ` ${currency}` : ""}`;
+}
+
 // src/tools/analytics.ts
 var MAX_RADAR_ITEMS = 8;
 function monthlyLabels(now, count) {
@@ -55339,11 +55723,14 @@ var analyticsTools = [
     name: "erpnext_revenue_trend",
     annotations: { readOnlyHint: true },
     _meta: CHART_META,
-    description: "Sales revenue trend over time. Returns a line chart (or area if type='area') with monthly revenue from Sales Orders. Add group_by='customer' for multi-line per customer. Use type='stacked-area' to stack customers.",
+    description: "Sales revenue trend over time. Returns a line chart (or area if type='area') with monthly revenue from Sales Orders. Add group_by='customer' for multi-line per customer. Use type='stacked-area' to stack customers. Uses the Sales Order document currency without conversion; mixed currencies require a currency filter.",
     category: "analytics",
     inputSchema: {
       type: "object",
       properties: {
+        ...moneyScopeSchema(
+          "Filter by Sales Order document currency (e.g. USD); no conversion"
+        ).properties ?? {},
         months: {
           type: "number",
           description: "How many months back to include (default 6)"
@@ -55361,6 +55748,8 @@ var analyticsTools = [
       }
     },
     handler: async (input, ctx) => {
+      const tool = "erpnext_revenue_trend";
+      const scope = parseMoneyScope(tool, input);
       const monthsBack = input.months ?? 6;
       const chartType = input.type ?? "line";
       const groupBy = input.group_by ?? "total";
@@ -55372,28 +55761,61 @@ var analyticsTools = [
       );
       const startStr = localCalendarDate(startDate);
       const orders = await ctx.client.list("Sales Order", {
-        fields: ["customer_name", "grand_total", "transaction_date"],
-        filters: [["transaction_date", ">=", startStr], ["docstatus", "!=", 2]],
-        limit: 1e3,
+        fields: [
+          "name",
+          "customer_name",
+          "grand_total",
+          "transaction_date",
+          "company",
+          "currency"
+        ],
+        filters: [
+          ["transaction_date", ">=", startStr],
+          ["transaction_date", "<=", localCalendarDate(now)],
+          ["docstatus", "!=", 2],
+          ...moneyScopeFilters(scope)
+        ],
+        limit: 0,
         order_by: "transaction_date asc"
-      });
+      }, { skipCache: true });
+      const { currency, amounts } = moneyValues(
+        tool,
+        orders,
+        "grand_total",
+        "currency",
+        scope.currency
+      );
       const months = monthlyLabels(now, monthsBack);
       if (groupBy === "customer") {
         const byCustomerMonth = {};
-        for (const order2 of orders) {
+        for (const [index, order2] of orders.entries()) {
           const calendarMonth = frappeCalendarMonth(order2.transaction_date);
-          if (!calendarMonth) continue;
+          if (!calendarMonth) {
+            throw new AnalyticsDataError(
+              tool,
+              "INVALID_DATE",
+              "A Sales Order has no valid transaction_date",
+              "Inspect the source Sales Order before calculating the revenue trend.",
+              { name: order2.name }
+            );
+          }
           const mIdx = (calendarMonth.year - startDate.getFullYear()) * 12 + calendarMonth.month - startDate.getMonth();
           if (mIdx < 0 || mIdx >= monthsBack) continue;
           const cust = order2.customer_name ?? "Unknown";
           if (!byCustomerMonth[cust]) {
-            byCustomerMonth[cust] = new Array(monthsBack).fill(0);
+            byCustomerMonth[cust] = Array.from(
+              { length: monthsBack },
+              () => []
+            );
           }
-          byCustomerMonth[cust][mIdx] += Number(order2.grand_total) || 0;
+          byCustomerMonth[cust][mIdx].push(amounts[index]);
         }
-        const sorted = Object.entries(byCustomerMonth).sort(
-          ([, a], [, b]) => b.reduce((s, v) => s + v, 0) - a.reduce((s, v) => s + v, 0)
-        ).slice(0, 5);
+        const sorted = Object.entries(byCustomerMonth).map(
+          ([name, monthAmounts]) => [
+            name,
+            monthAmounts.map((values) => sumMoney(tool, values))
+          ]
+        ).sort(([, a], [, b]) => sumMoney(tool, b) - sumMoney(tool, a)).slice(0, 5);
         const COLORS = ["#60a5fa", "#4ade80", "#fbbf24", "#c084fc", "#f472b6"];
         return {
           title: "Revenue by Customer",
@@ -55407,20 +55829,34 @@ var analyticsTools = [
             showDots: chartType === "line",
             ...chartType === "stacked-area" ? { stack: "revenue" } : {}
           })),
-          currency: "EUR",
+          ...currency ? { currency } : {},
           yAxisLabel: "Revenue",
           _meta: CHART_META
         };
       }
-      const monthlyTotals = new Array(monthsBack).fill(0);
-      for (const order2 of orders) {
+      const monthlyAmounts = Array.from(
+        { length: monthsBack },
+        () => []
+      );
+      for (const [index, order2] of orders.entries()) {
         const calendarMonth = frappeCalendarMonth(order2.transaction_date);
-        if (!calendarMonth) continue;
+        if (!calendarMonth) {
+          throw new AnalyticsDataError(
+            tool,
+            "INVALID_DATE",
+            "A Sales Order has no valid transaction_date",
+            "Inspect the source Sales Order before calculating the revenue trend.",
+            { name: order2.name }
+          );
+        }
         const mIdx = (calendarMonth.year - startDate.getFullYear()) * 12 + calendarMonth.month - startDate.getMonth();
         if (mIdx >= 0 && mIdx < monthsBack) {
-          monthlyTotals[mIdx] += Number(order2.grand_total) || 0;
+          monthlyAmounts[mIdx].push(amounts[index]);
         }
       }
+      const monthlyTotals = monthlyAmounts.map(
+        (values) => sumMoney(tool, values)
+      );
       return {
         title: "Revenue Trend",
         subtitle: `Last ${monthsBack} months`,
@@ -55432,7 +55868,7 @@ var analyticsTools = [
           color: "#60a5fa",
           showDots: true
         }],
-        currency: "EUR",
+        ...currency ? { currency } : {},
         yAxisLabel: "Revenue",
         _meta: CHART_META
       };
@@ -55842,39 +56278,62 @@ var analyticsTools = [
     name: "erpnext_kpi_revenue",
     annotations: { readOnlyHint: true },
     _meta: KPI_META,
-    description: "KPI card: total Sales Order revenue for the current month, with delta % vs previous month and sparkline of last 6 months.",
+    description: "KPI card: total Sales Order revenue for the current month, with delta % vs previous month and sparkline of last 6 months. Uses the document currency, with complete fresh reads. Mixed currencies require a currency filter.",
     category: "analytics",
-    inputSchema: { type: "object", properties: {} },
-    handler: async (_input, ctx) => {
+    inputSchema: moneyScopeSchema(
+      "Filter by Sales Order document currency (e.g. USD); no conversion"
+    ),
+    handler: async (input, ctx) => {
+      const tool = "erpnext_kpi_revenue";
+      const scope = parseMoneyScope(tool, input);
       const now = /* @__PURE__ */ new Date();
       const sixMonthsAgo = new Date(now.getFullYear(), now.getMonth() - 5, 1);
       const sinceStr = localCalendarDate(sixMonthsAgo);
       const allOrders = await ctx.client.list("Sales Order", {
-        fields: ["grand_total", "transaction_date"],
+        fields: ["name", "grand_total", "transaction_date", "currency"],
         filters: [
           ["transaction_date", ">=", sinceStr],
-          ["docstatus", "!=", 2]
+          ["transaction_date", "<=", localCalendarDate(now)],
+          ["docstatus", "!=", 2],
+          ...moneyScopeFilters(scope)
         ],
-        limit: 5e3
-      });
-      const sparkline = [0, 0, 0, 0, 0, 0];
-      const sparklineLabels = monthlyLabels(now, sparkline.length);
-      for (const o of allOrders) {
+        // Frappe limit 0 fetches every match, without a silent total cap.
+        limit: 0
+      }, { skipCache: true });
+      const { currency, amounts } = moneyValues(
+        tool,
+        allOrders,
+        "grand_total",
+        "currency",
+        scope.currency
+      );
+      const monthlyAmounts = [[], [], [], [], [], []];
+      const sparklineLabels = monthlyLabels(now, monthlyAmounts.length);
+      for (const [index, o] of allOrders.entries()) {
         const calendarMonth = frappeCalendarMonth(o.transaction_date);
-        if (!calendarMonth) continue;
+        if (!calendarMonth) {
+          throw new AnalyticsDataError(
+            tool,
+            "INVALID_DATE",
+            "A Sales Order has no valid transaction_date",
+            "Inspect the source Sales Order before calculating the monthly revenue.",
+            { name: o.name }
+          );
+        }
         const monthDiff = (now.getFullYear() - calendarMonth.year) * 12 + (now.getMonth() - calendarMonth.month);
         const idx = 5 - monthDiff;
         if (idx >= 0 && idx < 6) {
-          sparkline[idx] += Number(o.grand_total) || 0;
+          monthlyAmounts[idx].push(amounts[index]);
         }
       }
+      const sparkline = monthlyAmounts.map((month) => sumMoney(tool, month));
       const currentTotal = sparkline[5];
       const prevTotal = sparkline[4];
       const delta = prevTotal > 0 ? (currentTotal - prevTotal) / prevTotal * 100 : 0;
       return {
         label: "Revenue MTD",
         value: currentTotal,
-        currency: "EUR",
+        ...currency ? { currency } : {},
         delta: Math.round(delta * 10) / 10,
         deltaLabel: "vs last month",
         trend: delta > 0 ? "up" : delta < 0 ? "down" : "flat",
@@ -55891,28 +56350,38 @@ var analyticsTools = [
     name: "erpnext_kpi_outstanding",
     annotations: { readOnlyHint: true },
     _meta: KPI_META,
-    description: "KPI card: total outstanding receivables from submitted Sales Invoices with outstanding_amount > 0. Shows count of open invoices.",
+    description: "KPI card: total outstanding receivables from submitted Sales Invoices with outstanding_amount > 0. Shows count of open invoices. Amounts use the receivable party account currency; mixed currencies require a currency filter. Complete fresh read.",
     category: "analytics",
-    inputSchema: { type: "object", properties: {} },
-    handler: async (_input, ctx) => {
+    inputSchema: moneyScopeSchema(
+      "Filter by receivable party account currency, not invoice currency (e.g. USD)"
+    ),
+    handler: async (input, ctx) => {
+      const tool = "erpnext_kpi_outstanding";
+      const scope = parseMoneyScope(tool, input);
       const invoices = await ctx.client.list("Sales Invoice", {
-        fields: ["outstanding_amount"],
+        fields: ["name", "outstanding_amount", "party_account_currency"],
         filters: [
           ["outstanding_amount", ">", 0],
-          ["docstatus", "=", 1]
+          ["docstatus", "=", 1],
+          ...moneyScopeFilters(scope, "party_account_currency")
         ],
-        limit: 1e3
-      });
-      const total = invoices.reduce(
-        (sum, inv) => sum + (Number(inv.outstanding_amount) || 0),
-        0
+        limit: 0
+      }, { skipCache: true });
+      const { currency, amounts } = moneyValues(
+        tool,
+        invoices,
+        "outstanding_amount",
+        "party_account_currency",
+        scope.currency
       );
+      const total = sumMoney(tool, amounts);
       const count = invoices.length;
       return {
         label: "Outstanding Receivables",
         value: total,
-        formattedValue: `${count} inv. / ${total.toLocaleString("en-US", { style: "currency", currency: "EUR" })}`,
-        currency: "EUR",
+        formattedValue: `${count} inv. / ${formatMoney(total, currency)}`,
+        ...currency ? { currency } : {},
+        secondary: { kind: "invoice_count", value: count },
         trend: total > 0 ? "up" : "flat",
         trendIsGood: false,
         color: "#fbbf24",
@@ -55925,10 +56394,13 @@ var analyticsTools = [
     name: "erpnext_kpi_orders",
     annotations: { readOnlyHint: true },
     _meta: KPI_META,
-    description: "KPI card: count and total value of Sales Orders created this month, with delta % vs last month.",
+    description: "KPI card: count of non-cancelled Sales Orders dated this month through today, with delta % vs last month. Complete fresh reads, optionally scoped by company and document currency.",
     category: "analytics",
-    inputSchema: { type: "object", properties: {} },
-    handler: async (_input, ctx) => {
+    inputSchema: moneyScopeSchema(
+      "Filter by Sales Order document currency (e.g. USD)"
+    ),
+    handler: async (input, ctx) => {
+      const scope = parseMoneyScope("erpnext_kpi_orders", input);
       const now = /* @__PURE__ */ new Date();
       const thisMonthStart = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-01`;
       const lastMonthStart = new Date(now.getFullYear(), now.getMonth() - 1, 1);
@@ -55936,23 +56408,26 @@ var analyticsTools = [
       const lastMonthStartStr = localCalendarDate(lastMonthStart);
       const lastMonthEndStr = localCalendarDate(lastMonthEnd);
       const currentOrders = await ctx.client.list("Sales Order", {
-        fields: ["grand_total"],
+        fields: ["name"],
         filters: [
           ["transaction_date", ">=", thisMonthStart],
-          ["docstatus", "!=", 2]
+          ["transaction_date", "<=", localCalendarDate(now)],
+          ["docstatus", "!=", 2],
+          ...moneyScopeFilters(scope)
         ],
-        limit: 1e3
-      });
+        limit: 0
+      }, { skipCache: true });
       const currentCount = currentOrders.length;
       const prevOrders = await ctx.client.list("Sales Order", {
-        fields: ["grand_total"],
+        fields: ["name"],
         filters: [
           ["transaction_date", ">=", lastMonthStartStr],
           ["transaction_date", "<=", lastMonthEndStr],
-          ["docstatus", "!=", 2]
+          ["docstatus", "!=", 2],
+          ...moneyScopeFilters(scope)
         ],
-        limit: 1e3
-      });
+        limit: 0
+      }, { skipCache: true });
       const prevCount = prevOrders.length;
       const delta = prevCount > 0 ? (currentCount - prevCount) / prevCount * 100 : 0;
       return {
@@ -56029,31 +56504,50 @@ var analyticsTools = [
     name: "erpnext_kpi_overdue",
     annotations: { readOnlyHint: true },
     _meta: KPI_META,
-    description: "KPI card: count and total value of overdue Sales Invoices (due_date < today, outstanding_amount > 0, submitted).",
+    description: "KPI card: count and total value of overdue Sales Invoices (due_date < today, outstanding_amount > 0, submitted). Amounts use the receivable party account currency; mixed currencies require a currency filter. Complete fresh read.",
     category: "analytics",
-    inputSchema: { type: "object", properties: {} },
-    handler: async (_input, ctx) => {
+    inputSchema: moneyScopeSchema(
+      "Filter by receivable party account currency, not invoice currency (e.g. USD)"
+    ),
+    handler: async (input, ctx) => {
+      const tool = "erpnext_kpi_overdue";
+      const scope = parseMoneyScope(tool, input);
       const now = /* @__PURE__ */ new Date();
       const pad = (n) => String(n).padStart(2, "0");
       const today = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
       const invoices = await ctx.client.list("Sales Invoice", {
-        fields: ["outstanding_amount", "due_date"],
+        fields: [
+          "name",
+          "outstanding_amount",
+          "due_date",
+          "party_account_currency"
+        ],
         filters: [
           ["due_date", "<", today],
           ["outstanding_amount", ">", 0],
-          ["docstatus", "=", 1]
+          ["docstatus", "=", 1],
+          ...moneyScopeFilters(scope, "party_account_currency")
         ],
-        limit: 1e3
-      });
+        limit: 0
+      }, { skipCache: true });
       const count = invoices.length;
-      const total = invoices.reduce(
-        (sum, inv) => sum + (Number(inv.outstanding_amount) || 0),
-        0
+      const { currency, amounts } = moneyValues(
+        tool,
+        invoices,
+        "outstanding_amount",
+        "party_account_currency",
+        scope.currency
       );
+      const total = sumMoney(tool, amounts);
       return {
         label: "Overdue Invoices",
         value: count,
-        formattedValue: `${count} inv. / ${total.toLocaleString("en-US", { style: "currency", currency: "EUR" })}`,
+        formattedValue: `${count} inv. / ${formatMoney(total, currency)}`,
+        secondary: {
+          kind: "amount",
+          value: total,
+          ...currency ? { currency } : {}
+        },
         trend: count > 0 ? "up" : "flat",
         trendIsGood: false,
         color: "#f87171",
@@ -57524,7 +58018,7 @@ var BUY_EVIDENCE_VIEWER_URI = "ui://mcp-erpnext/buy-evidence-viewer";
 var BUY_VIEW_APP_MANIFEST_URI = "ui://mcp-erpnext/buy-evidence-manifest";
 var BUY_VIEW_APP_ID = "io.casys.mcp-erpnext.buy-evidence";
 var BUY_VIEW_APP_TITLE = "ERPNext Buy Evidence";
-var BUY_VIEW_APP_VERSION = "3.2.0-beta.1";
+var BUY_VIEW_APP_VERSION = "3.1.0";
 var BUY_SOURCE_INSTANCE_KIND = "erpnext-site";
 var BUY_CAPTURE_DOCTYPE = [
   "Item",
@@ -58894,13 +59388,152 @@ var allTools = [
   ...kanbanTools,
   ...buyTools
 ];
-function getToolsByCategory(category) {
-  return toolsByCategory[category] ?? [];
-}
 function getToolByName(name) {
   return allTools.find((t) => t.name === name);
 }
 
+// src/tools/selection.ts
+var TOOL_FILTER_ERROR_CODE = "INVALID_TOOL_FILTER";
+var SUBJECT = "mcp-erpnext";
+function formatToolFilterMessage(detail, recovery, subject = SUBJECT) {
+  return formatToolError(subject, TOOL_FILTER_ERROR_CODE, detail, recovery);
+}
+var ToolFilterError = class extends Error {
+  code = TOOL_FILTER_ERROR_CODE;
+  reason;
+  retryable = false;
+  context;
+  recovery;
+  detail;
+  constructor(reason, detail, options) {
+    super(formatToolFilterMessage(detail, options.recovery));
+    this.name = "ToolFilterError";
+    this.reason = reason;
+    this.detail = detail;
+    this.recovery = options.recovery;
+    this.context = Object.freeze({ ...options.context ?? {}, reason });
+  }
+};
+function isToolFilterError(error2) {
+  return error2 instanceof ToolFilterError;
+}
+var DEFAULT_REGISTRY = { toolsByCategory, allTools };
+function unique(values) {
+  return [...new Set(values)];
+}
+function unknownCategoryDetail(unknown2, valid, ignored = false) {
+  return `Unknown categor${unknown2.length > 1 ? "ies" : "y"} ${unknown2.map((c) => `"${c}"`).join(", ")}${ignored ? " (ignored)" : ""}; valid categories: ${valid.join(", ")}`;
+}
+var CATEGORY_RECOVERY = "use only valid category names (case-sensitive, comma-separated)";
+function resolveToolSelection(options = {}, registry2 = DEFAULT_REGISTRY) {
+  const { categories, excludeCategories, excludeTools } = options;
+  if (categories === void 0 && excludeCategories === void 0 && excludeTools === void 0) {
+    return {
+      tools: registry2.allTools,
+      excludedCategories: [],
+      excludedTools: [],
+      warnings: []
+    };
+  }
+  const validCategories = Object.keys(registry2.toolsByCategory);
+  const validSet = new Set(validCategories);
+  const warnings = [];
+  const excludedCategories = unique(excludeCategories ?? []);
+  const unknownExcluded = excludedCategories.filter((c) => !validSet.has(c));
+  if (unknownExcluded.length > 0) {
+    throw new ToolFilterError(
+      "UNKNOWN_CATEGORY",
+      unknownCategoryDetail(unknownExcluded, validCategories),
+      {
+        context: {
+          option: "excludeCategories",
+          received: unknownExcluded,
+          valid: validCategories
+        },
+        recovery: CATEGORY_RECOVERY
+      }
+    );
+  }
+  const excludedTools = unique(excludeTools ?? []);
+  const validToolNames = registry2.allTools.map((t) => t.name);
+  const toolNameSet = new Set(validToolNames);
+  const unknownTools = excludedTools.filter((t) => !toolNameSet.has(t));
+  if (unknownTools.length > 0) {
+    throw new ToolFilterError(
+      "UNKNOWN_TOOL",
+      `Unknown tool${unknownTools.length > 1 ? "s" : ""} ${unknownTools.slice(0, 5).map((t) => `"${t}"`).join(", ")}${unknownTools.length > 5 ? `, and ${unknownTools.length - 5} more` : ""}`,
+      {
+        context: {
+          option: "excludeTools",
+          received: unknownTools,
+          valid: validToolNames
+        },
+        recovery: "use exact tool names such as erpnext_file_list (comma-separated); see docs/tools.md or call tools/list for the complete list"
+      }
+    );
+  }
+  let base;
+  let allowList;
+  if (categories === void 0) {
+    base = registry2.allTools;
+  } else {
+    allowList = unique(categories);
+    const unknown2 = allowList.filter((c) => !validSet.has(c));
+    if (unknown2.length > 0) {
+      warnings.push({
+        code: TOOL_FILTER_ERROR_CODE,
+        reason: "UNKNOWN_CATEGORY",
+        message: formatToolFilterMessage(
+          unknownCategoryDetail(unknown2, validCategories, true),
+          CATEGORY_RECOVERY
+        ),
+        context: Object.freeze({
+          option: "categories",
+          received: unknown2,
+          valid: validCategories,
+          reason: "UNKNOWN_CATEGORY"
+        }),
+        recovery: CATEGORY_RECOVERY
+      });
+    }
+    base = allowList.filter((c) => validSet.has(c)).flatMap((c) => registry2.toolsByCategory[c]);
+  }
+  const excludedCategorySet = new Set(excludedCategories);
+  const excludedToolSet = new Set(excludedTools);
+  const seen = /* @__PURE__ */ new Set();
+  const tools = [];
+  for (const tool of base) {
+    if (seen.has(tool.name)) continue;
+    seen.add(tool.name);
+    if (excludedCategorySet.has(tool.category)) continue;
+    if (excludedToolSet.has(tool.name)) continue;
+    tools.push(tool);
+  }
+  return {
+    tools,
+    ...allowList ? { categories: allowList } : {},
+    excludedCategories,
+    excludedTools,
+    warnings
+  };
+}
+function assertNonEmptySelection(selection, registry2 = DEFAULT_REGISTRY) {
+  if (selection.tools.length > 0) return;
+  throw new ToolFilterError(
+    "EMPTY_SELECTION",
+    "The tool selection is empty: no tool would be registered",
+    {
+      context: {
+        categories: selection.categories ?? null,
+        excludedCategories: selection.excludedCategories,
+        excludedTools: selection.excludedTools,
+        valid: Object.keys(registry2.toolsByCategory)
+      },
+      recovery: "check --categories / --exclude-categories / --exclude-tools (and their ERPNEXT_* variables) so that at least one tool remains"
+    }
+  );
+}
+
 // src/mrtr/link-disambiguation.ts
 function linkDisambiguationRequestKey(inputPath) {
   return `link-disambiguation:${inputPath}`;
@@ -59404,8 +60037,32 @@ var INVOICE_LIST_FIELDS = [
   "posting_date",
   "due_date",
   "status",
-  "outstanding_amount"
+  "outstanding_amount",
+  "party_account_currency"
 ];
+var FINANCIAL_KPI_CURRENCY_FIELDS = {
+  erpnext_kpi_revenue: "currency",
+  erpnext_kpi_outstanding: "party_account_currency",
+  erpnext_kpi_overdue: "party_account_currency"
+};
+function scopedKpiJumps(toolName, jumps, args) {
+  const currencyField = FINANCIAL_KPI_CURRENCY_FIELDS[toolName];
+  if (!currencyField && toolName !== "erpnext_kpi_orders") return jumps;
+  if (!jumps.number) return jumps;
+  const scopeFilters = moneyScopeFilters(
+    parseMoneyScope(toolName, args),
+    currencyField ?? "currency"
+  );
+  const filters = [
+    ...Array.isArray(jumps.number.args.filters) ? jumps.number.args.filters : [],
+    ...scopeFilters
+  ];
+  return {
+    ...jumps,
+    number: { ...jumps.number, args: { ...jumps.number.args, filters } },
+    ...scopeFilters.length > 0 ? { trend: void 0 } : {}
+  };
+}
 var KPI_JUMPS = {
   "erpnext_kpi_revenue": (r) => ({
     number: {
@@ -59419,24 +60076,18 @@ var KPI_JUMPS = {
           "customer",
           "transaction_date",
           "status",
-          "grand_total"
+          "grand_total",
+          "currency"
         ],
         filters: [
           ["transaction_date", ">=", r.from],
-          ["transaction_date", "<=", r.to],
+          ["transaction_date", "<=", r.today],
           // comme le KPI : les commandes annulées ne comptent pas
           ["docstatus", "<", 2]
         ],
         limit: 20
       },
       kind: "list"
-    },
-    trend: {
-      key: "revenue_trend",
-      label: "Revenue trend",
-      tool: "erpnext_revenue_trend",
-      args: { months: 12 },
-      kind: "chart"
     }
   }),
   "erpnext_kpi_outstanding": () => ({
@@ -59451,13 +60102,6 @@ var KPI_JUMPS = {
         limit: 20
       },
       kind: "list"
-    },
-    trend: {
-      key: "receivables_aging",
-      label: "Receivables aging",
-      tool: "erpnext_ar_aging",
-      args: {},
-      kind: "chart"
     }
   }),
   "erpnext_kpi_orders": (r) => ({
@@ -59472,11 +60116,12 @@ var KPI_JUMPS = {
           "customer",
           "transaction_date",
           "status",
-          "grand_total"
+          "grand_total",
+          "currency"
         ],
         filters: [
           ["transaction_date", ">=", r.from],
-          ["transaction_date", "<=", r.to],
+          ["transaction_date", "<=", r.today],
           // comme le KPI : les commandes annulées ne comptent pas
           ["docstatus", "<", 2]
         ],
@@ -59517,13 +60162,6 @@ var KPI_JUMPS = {
         limit: 20
       },
       kind: "list"
-    },
-    trend: {
-      key: "receivables_aging",
-      label: "Receivables aging",
-      tool: "erpnext_ar_aging",
-      args: {},
-      kind: "chart"
     }
   })
 };
@@ -59652,7 +60290,8 @@ var SALES_ORDER_LIST_FIELDS = [
   "customer",
   "transaction_date",
   "status",
-  "grand_total"
+  "grand_total",
+  "currency"
 ];
 var PURCHASE_ORDER_LIST_FIELDS = [
   "name",
@@ -59693,12 +60332,20 @@ function chartPointJumps(toolName, args, labels, now) {
   switch (toolName) {
     case "erpnext_revenue_trend": {
       const months = Number(args.months ?? 6);
+      const scopeFilters = moneyScopeFilters(
+        parseMoneyScope(toolName, args)
+      );
       for (const { label, range } of monthBuckets(months, now)) {
         if (!labels.includes(label)) continue;
         jumps[label] = docList(label, "Sales Order", SALES_ORDER_LIST_FIELDS, [
           ["transaction_date", ">=", range.from],
-          ["transaction_date", "<=", range.to],
-          ["docstatus", "<", 2]
+          [
+            "transaction_date",
+            "<=",
+            label === monthLabel(now) ? monthRange(now).today : range.to
+          ],
+          ["docstatus", "<", 2],
+          ...scopeFilters
         ]);
       }
       break;
@@ -59855,27 +60502,60 @@ var VIEWER_TOOL_CANDIDATES = {
     "erpnext_stock_entry_list"
   ]
 };
-var SUBMITTABLE_VIEWER_DOCTYPES = /* @__PURE__ */ new Set([
+var SUBMITTABLE_VIEWER_DOCTYPES = [
+  // ERPNext — ventes
   "Quotation",
   "Sales Order",
   "Delivery Note",
   "Sales Invoice",
+  "POS Invoice",
+  "Installation Note",
+  // ERPNext — achats
+  "Request for Quotation",
+  "Supplier Quotation",
   "Purchase Order",
   "Purchase Receipt",
   "Purchase Invoice",
-  "Stock Entry",
+  // ERPNext — comptabilité
   "Journal Entry",
   "Payment Entry",
-  "Timesheet",
-  "Leave Application",
-  "Salary Slip",
+  "Payment Request",
+  "Period Closing Voucher",
+  // ERPNext — stock
+  "Material Request",
+  "Stock Entry",
+  "Stock Reconciliation",
+  "Pick List",
+  "Delivery Trip",
+  "Landed Cost Voucher",
+  "Quality Inspection",
+  "Shipment",
+  // ERPNext — fabrication
   "BOM",
   "Work Order",
   "Job Card",
+  "Blanket Order",
+  // ERPNext — projets et actifs
+  "Timesheet",
   "Asset",
   "Asset Movement",
-  "Shipment"
-]);
+  // HRMS
+  "Attendance",
+  "Leave Application",
+  "Leave Allocation",
+  "Leave Encashment",
+  "Expense Claim",
+  "Employee Advance",
+  "Payroll Entry",
+  "Salary Slip",
+  "Additional Salary"
+];
+var SUBMITTABLE_CANONICAL = new Map(
+  SUBMITTABLE_VIEWER_DOCTYPES.map((doctype) => [doctype.toLowerCase(), doctype])
+);
+function submittableViewerDoctype(doctype) {
+  return SUBMITTABLE_CANONICAL.get(doctype.trim().toLowerCase());
+}
 var INVOICE_DEDICATED_MUTATION_TOOLS = {
   "Sales Order": [
     "erpnext_sales_order_submit",
@@ -59884,13 +60564,14 @@ var INVOICE_DEDICATED_MUTATION_TOOLS = {
   "Sales Invoice": ["erpnext_sales_invoice_submit"]
 };
 function addDoctypeMutationCandidates(target, uri, doctype) {
-  if (!doctype || !SUBMITTABLE_VIEWER_DOCTYPES.has(doctype)) return;
-  if (uri === "ui://mcp-erpnext/invoice-viewer" || uri === "ui://mcp-erpnext/doclist-viewer" || uri === "ui://mcp-erpnext/doc-viewer") {
+  const submittable = doctype ? submittableViewerDoctype(doctype) : void 0;
+  if (!submittable) return;
+  if (uri === "ui://mcp-erpnext/invoice-viewer" || uri === "ui://mcp-erpnext/doc-viewer") {
     target.add("erpnext_doc_submit");
     target.add("erpnext_doc_cancel");
   }
   if (uri === "ui://mcp-erpnext/invoice-viewer") {
-    for (const tool of INVOICE_DEDICATED_MUTATION_TOOLS[doctype] ?? []) {
+    for (const tool of INVOICE_DEDICATED_MUTATION_TOOLS[submittable] ?? []) {
       target.add(tool);
     }
   }
@@ -60056,14 +60737,16 @@ function withUiRefreshRequest(result, toolName, args, now = /* @__PURE__ */ new
       if (kpiHints._drillDown && !enriched._drillDown) {
         enriched._drillDown = kpiHints._drillDown;
       }
-      if (kpiHints._trendDrillDown && !enriched._trendDrillDown) {
+      if (kpiHints._trendDrillDown && !enriched._trendDrillDown && !FINANCIAL_KPI_CURRENCY_FIELDS[toolName] && !(args.company || args.currency)) {
         enriched._trendDrillDown = kpiHints._trendDrillDown;
       }
     }
   }
   if (isKpiViewer(enriched) && !enriched._jumps) {
     const jumps = KPI_JUMPS[toolName];
-    if (jumps) enriched._jumps = jumps(monthRange(now));
+    if (jumps) {
+      enriched._jumps = scopedKpiJumps(toolName, jumps(monthRange(now)), args);
+    }
   }
   if (isFunnelViewer(enriched) && !enriched._stageJumps) {
     enriched._stageJumps = funnelStageJumps(args, now);
@@ -60094,37 +60777,237 @@ function withUiRefreshRequest(result, toolName, args, now = /* @__PURE__ */ new
   return filterNavJumpsByAvailableTools(enriched, availableToolNames);
 }
 
-// src/client.ts
+// src/tools/doctype-layout.ts
+var DOCTYPE_LAYOUT_TTL_MS = 60 * 60 * 1e3;
+var DOCTYPE_LAYOUT_FAILURE_TTL_MS = 60 * 1e3;
+var DOCTYPE_LAYOUT_MAX_ENTRIES = 200;
+var DOCTYPE_LAYOUT_SKIPPED = /* @__PURE__ */ new Set([
+  "Company",
+  "DocType"
+]);
+var GETDOCTYPE_METHOD = "frappe.desk.form.load.getdoctype";
+var VISUAL_TYPES = /* @__PURE__ */ new Set([
+  "Section Break",
+  "Tab Break",
+  "Column Break",
+  "HTML",
+  "Button",
+  "Heading",
+  "Fold",
+  "Image"
+]);
+var TABLE_TYPES = /* @__PURE__ */ new Set(["Table", "Table MultiSelect"]);
 function isRecord9(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+function isFlag(value) {
+  return value === 1 || value === true || value === "1";
+}
+function metaFieldOf(value) {
+  if (!isRecord9(value)) return null;
+  const fieldname = nonEmptyString(value.fieldname);
+  const fieldtype = nonEmptyString(value.fieldtype);
+  if (!fieldname || !fieldtype) return null;
+  return {
+    fieldname,
+    fieldtype,
+    label: nonEmptyString(value.label),
+    preview: isFlag(value.in_preview),
+    bold: isFlag(value.bold),
+    inListView: isFlag(value.in_list_view)
+  };
+}
+function isDataField(field) {
+  return !VISUAL_TYPES.has(field.fieldtype) && !TABLE_TYPES.has(field.fieldtype);
+}
+function previewOf(dataFields, titleField) {
+  const flagged = dataFields.filter((field) => field.preview || field.bold);
+  const chosen = flagged.length > 0 ? flagged : dataFields.filter((field) => field.inListView);
+  return [
+    .../* @__PURE__ */ new Set([
+      ...titleField ? [titleField] : [],
+      ...chosen.map((field) => field.fieldname)
+    ])
+  ];
+}
+function sectionsOf(fields) {
+  const sections = [];
+  let current = { label: null, fields: [] };
+  let tabOpen = false;
+  const flush = () => {
+    if (current.fields.length > 0) sections.push(current);
+  };
+  for (const field of fields) {
+    if (field.fieldtype === "Tab Break") {
+      flush();
+      current = { label: field.label, fields: [] };
+      tabOpen = true;
+    } else if (field.fieldtype === "Section Break") {
+      if (!(tabOpen && field.label === null)) {
+        flush();
+        current = { label: field.label, fields: [] };
+      }
+      tabOpen = false;
+    } else if (isDataField(field)) {
+      current.fields.push(field.fieldname);
+      tabOpen = false;
+    }
+  }
+  flush();
+  return sections;
+}
+function docTypeLayoutOf(response) {
+  if (!isRecord9(response) || !Array.isArray(response.docs)) return null;
+  const doctype = response.docs[0];
+  if (!isRecord9(doctype) || !Array.isArray(doctype.fields)) return null;
+  const fields = doctype.fields.flatMap((raw2) => {
+    const field = metaFieldOf(raw2);
+    return field ? [field] : [];
+  });
+  const dataFields = fields.filter(isDataField);
+  const labels = {};
+  for (const field of dataFields) {
+    if (field.label) labels[field.fieldname] = field.label;
+  }
+  return {
+    version: 1,
+    preview: previewOf(dataFields, nonEmptyString(doctype.title_field)),
+    sections: sectionsOf(fields),
+    labels
+  };
+}
+function createDocTypeLayoutMemo(options = {}) {
+  const maxEntries = options.maxEntries ?? DOCTYPE_LAYOUT_MAX_ENTRIES;
+  const now = options.now ?? Date.now;
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    get(doctype) {
+      const entry = entries.get(doctype);
+      if (!entry) return void 0;
+      if (now() >= entry.expiresAt) {
+        entries.delete(doctype);
+        return void 0;
+      }
+      return entry.layout === null ? null : structuredClone(entry.layout);
+    },
+    set(doctype, layout) {
+      const at = now();
+      entries.delete(doctype);
+      for (const [key, entry] of entries) {
+        if (at >= entry.expiresAt) entries.delete(key);
+      }
+      entries.set(doctype, {
+        layout,
+        expiresAt: at + (layout === null ? DOCTYPE_LAYOUT_FAILURE_TTL_MS : DOCTYPE_LAYOUT_TTL_MS)
+      });
+      while (entries.size > maxEntries) {
+        entries.delete(entries.keys().next().value);
+      }
+    },
+    clear() {
+      entries.clear();
+    },
+    get size() {
+      return entries.size;
+    }
+  };
+}
+var docTypeLayoutMemo = createDocTypeLayoutMemo();
+function logToStderr(message2) {
+  console.error(`[mcp-erpnext] ${message2}`);
+}
+async function fetchDocTypeLayout(client, doctype, options = {}) {
+  if (DOCTYPE_LAYOUT_SKIPPED.has(doctype)) return null;
+  const memo3 = options.memo ?? docTypeLayoutMemo;
+  const remembered = memo3.get(doctype);
+  if (remembered !== void 0) return remembered;
+  try {
+    const response = await client.callMethodRaw(
+      GETDOCTYPE_METHOD,
+      { doctype },
+      "GET"
+    );
+    const layout = docTypeLayoutOf(response);
+    if (!layout) throw new Error("unreadable getdoctype response");
+    memo3.set(doctype, layout);
+    return layout;
+  } catch (error2) {
+    (options.log ?? logToStderr)(
+      `DocType layout unavailable for "${doctype}" (non-fatal): ${error2 instanceof Error ? error2.message : String(error2)}`
+    );
+    memo3.set(doctype, null);
+    return null;
+  }
+}
+
+// src/tools/model-visible.ts
+var VIEWER_META_KEY = "io.casys/viewer";
+var VIEWER_ONLY_RESULT_KEYS = [
+  "_meta",
+  "refreshRequest",
+  "_availableTools",
+  "_rowAction",
+  "_sendMessageHints",
+  "_drillDown",
+  "_trendDrillDown",
+  "_jumps",
+  "_stageJumps",
+  "_pointJumps",
+  "_seriesPointJumps",
+  "_fieldLayout"
+];
+function modelVisiblePayload(result) {
+  const payload = { ...result };
+  for (const key of VIEWER_ONLY_RESULT_KEYS) delete payload[key];
+  return payload;
+}
+function splitViewerResult(result) {
+  const viewer2 = {};
+  for (const key of VIEWER_ONLY_RESULT_KEYS) {
+    if (key !== "_meta" && key in result) viewer2[key] = result[key];
+  }
+  return { data: modelVisiblePayload(result), viewer: viewer2 };
+}
+
+// src/client.ts
+function isRecord10(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isSingleEmbeddedBlobResult(value) {
-  if (!isRecord9(value) || !Array.isArray(value.content)) return false;
+  if (!isRecord10(value) || !Array.isArray(value.content)) return false;
   if (Object.keys(value).some((key) => key !== "content")) return false;
   if (value.content.length !== 2) return false;
   const [summary, embedded] = value.content;
-  if (!isRecord9(summary) || summary.type !== "text" || typeof summary.text !== "string") {
+  if (!isRecord10(summary) || summary.type !== "text" || typeof summary.text !== "string") {
     return false;
   }
-  if (!isRecord9(embedded) || embedded.type !== "resource") return false;
-  if (!isRecord9(embedded.resource)) return false;
+  if (!isRecord10(embedded) || embedded.type !== "resource") return false;
+  if (!isRecord10(embedded.resource)) return false;
   const resource = embedded.resource;
   return typeof resource.uri === "string" && resource.uri.startsWith("file:///") && typeof resource.mimeType === "string" && typeof resource.blob === "string";
 }
+function singleDocumentDoctypeOf(result) {
+  const nonEmpty2 = (value) => typeof value === "string" && value.trim().length > 0;
+  const document = isRecord10(result.data) && nonEmpty2(result.data.doctype) && nonEmpty2(result.data.name) ? result.data : !Array.isArray(result.data) && nonEmpty2(result.doctype) && nonEmpty2(result.name) ? result : void 0;
+  return document ? document.doctype.trim() : void 0;
+}
 function withSafeUiRefresh(result, tool, args, availableToolNames) {
   const readOnly = tool.annotations?.readOnlyHint === true;
-  if (!isRecord9(result)) {
+  if (!isRecord10(result)) {
     return result;
   }
-  const resultMeta = isRecord9(result._meta) ? result._meta : {};
+  const resultMeta = isRecord10(result._meta) ? result._meta : {};
   const declaredUi = tool._meta?.ui;
-  const viewerResult = declaredUi && !isRecord9(resultMeta.ui) ? {
+  const viewerResult = declaredUi && !isRecord10(resultMeta.ui) ? {
     ...result,
     _meta: { ...resultMeta, ...tool._meta, ui: declaredUi }
   } : result;
-  const request = isRecord9(viewerResult.refreshRequest) ? viewerResult.refreshRequest : null;
+  const request = isRecord10(viewerResult.refreshRequest) ? viewerResult.refreshRequest : null;
   const target = request && typeof request.toolName === "string" ? getToolByName(request.toolName) : void 0;
-  const hasSafeExplicitRefresh = request !== null && typeof request.toolName === "string" && availableToolNames.has(request.toolName) && isRecord9(request.arguments) && (request.toolName === tool.name ? readOnly : target?.annotations?.readOnlyHint === true);
+  const hasSafeExplicitRefresh = request !== null && typeof request.toolName === "string" && availableToolNames.has(request.toolName) && isRecord10(request.arguments) && (request.toolName === tool.name ? readOnly : target?.annotations?.readOnlyHint === true);
   if (hasSafeExplicitRefresh) {
     return withUiRefreshRequest(
       viewerResult,
@@ -60150,13 +61033,16 @@ function withSafeUiRefresh(result, tool, args, availableToolNames) {
 var ErpNextToolsClient = class {
   tools;
   enableLinkDisambiguation;
+  /** How the active tool list was resolved (warnings, effective filters). */
+  selection;
   constructor(options) {
     this.enableLinkDisambiguation = options?.enableLinkDisambiguation ?? false;
-    if (options?.categories) {
-      this.tools = options.categories.flatMap((cat) => getToolsByCategory(cat));
-    } else {
-      this.tools = allTools;
-    }
+    this.selection = resolveToolSelection({
+      categories: options?.categories,
+      excludeCategories: options?.excludeCategories,
+      excludeTools: options?.excludeTools
+    });
+    this.tools = this.selection.tools;
   }
   /** List available tools (with handler attached) */
   listTools() {
@@ -60182,8 +61068,11 @@ var ErpNextToolsClient = class {
    *
    * Object results are returned as pre-formatted MCP results with both
    * `content` (text JSON for model clients) and `structuredContent` (the exact
-   * machine-readable value). Viewer metadata is attached only when declared.
-   * McpApp passes these results through unchanged.
+   * machine-readable value). Both carry only domain data : l'enrichissement
+   * viewer (refresh, sauts, `_availableTools`…) part dans
+   * `_meta["io.casys/viewer"]`, le seul canal caché au modèle sur tous les
+   * hôtes, que la vue refusionne à la lecture. McpApp passes these results
+   * through unchanged.
    */
   buildHandlersMap() {
     const handlers = /* @__PURE__ */ new Map();
@@ -60223,10 +61112,21 @@ var ErpNextToolsClient = class {
         const resultUi = r?._meta && typeof r._meta === "object" && r._meta.ui;
         const hasViewer = resultUi || toolMeta?.ui;
         if (r) {
+          const layoutDoctype = hasViewer ? singleDocumentDoctypeOf(r) : void 0;
+          const fieldLayout = layoutDoctype ? await fetchDocTypeLayout(client, layoutDoctype) : null;
+          const { data, viewer: viewer2 } = splitViewerResult(
+            fieldLayout ? { ...r, _fieldLayout: fieldLayout } : r
+          );
+          const declaredMeta = r._meta ?? toolMeta;
+          const hasEnrichment = Object.keys(viewer2).length > 0;
+          const meta2 = hasEnrichment ? {
+            ...isRecord10(declaredMeta) ? declaredMeta : {},
+            [VIEWER_META_KEY]: { version: 1, ...viewer2 }
+          } : hasViewer ? declaredMeta : void 0;
           return {
-            content: [{ type: "text", text: JSON.stringify(result) }],
-            structuredContent: r,
-            ...hasViewer ? { _meta: r._meta ?? toolMeta } : {}
+            content: [{ type: "text", text: JSON.stringify(data) }],
+            structuredContent: data,
+            ...meta2 !== void 0 ? { _meta: meta2 } : {}
           };
         }
         return result;
@@ -60234,7 +61134,16 @@ var ErpNextToolsClient = class {
     }
     return handlers;
   }
-  /** Execute a tool by name */
+  /**
+   * Execute a tool by name.
+   *
+   * API bibliothèque : renvoie le résultat enrichi complet, clés viewer
+   * incluses, sans le découpage modèle/vue de `buildHandlersMap`. Le handler
+   * ne reçoit que le client Frappe, sans capacités MCP du client :
+   * `erpnext_file_download` y est donc toujours refusé (`FileDownloadError`,
+   * `APP_CONTEXT_REQUIRED`) — les octets des pièces jointes ne sont servis
+   * qu'aux hôtes MCP Apps via le serveur MCP.
+   */
   async execute(name, args) {
     const tool = this.tools.find((t) => t.name === name);
     if (!tool) {
@@ -60261,6 +61170,117 @@ var ErpNextToolsClient = class {
 };
 var defaultClient = new ErpNextToolsClient();
 
+// src/tools/selection-config.ts
+var TOOL_FILTER_OPTIONS = [
+  {
+    key: "categories",
+    flag: "--categories",
+    envVar: "ERPNEXT_CATEGORIES"
+  },
+  {
+    key: "excludeCategories",
+    flag: "--exclude-categories",
+    envVar: "ERPNEXT_EXCLUDE_CATEGORIES"
+  },
+  {
+    key: "excludeTools",
+    flag: "--exclude-tools",
+    envVar: "ERPNEXT_EXCLUDE_TOOLS"
+  }
+];
+function splitList(raw2) {
+  return [...new Set(raw2.split(",").map((s) => s.trim()).filter(Boolean))];
+}
+function emptyValue(option, source, received) {
+  const where = source === "cli" ? option.flag : option.envVar;
+  return new ToolFilterError(
+    "EMPTY_VALUE",
+    `${where} is set but contains no value`,
+    {
+      context: { option: option.key, source, received },
+      recovery: source === "cli" ? `use ${option.flag}=a,b or remove the flag` : `set ${option.envVar}=a,b or unset it`
+    }
+  );
+}
+function readSelectionConfig(args, getEnv = env6) {
+  const config2 = { sources: {}, warnings: [] };
+  for (const option of TOOL_FILTER_OPTIONS) {
+    const bareIndex = args.indexOf(option.flag);
+    if (bareIndex !== -1) {
+      const next = args[bareIndex + 1];
+      const received = next !== void 0 && !next.startsWith("-") ? `${option.flag} ${next}` : option.flag;
+      const detail = `${option.flag} needs a value in the form ${option.flag}=a,b`;
+      const recovery = `write ${option.flag}=a,b (an equals sign, no space); the flag was not applied`;
+      const context2 = { option: option.key, flag: option.flag, received };
+      if (option.key !== "categories") {
+        throw new ToolFilterError("MALFORMED_FLAG", detail, {
+          context: context2,
+          recovery
+        });
+      }
+      config2.warnings.push({
+        code: TOOL_FILTER_ERROR_CODE,
+        reason: "MALFORMED_FLAG",
+        message: formatToolFilterMessage(`${detail} (ignored)`, recovery),
+        context: Object.freeze({
+          ...context2,
+          reason: "MALFORMED_FLAG",
+          ignored: true
+        }),
+        recovery
+      });
+    }
+    const prefix = `${option.flag}=`;
+    const cliArgs = args.filter((arg) => arg.startsWith(prefix));
+    let raw2;
+    let source;
+    if (cliArgs.length > 0) {
+      if (cliArgs.length > 1) {
+        if (option.key !== "categories") {
+          throw new ToolFilterError(
+            "DUPLICATE_FLAG",
+            `${option.flag} is given ${cliArgs.length} times`,
+            {
+              context: { option: option.key, received: cliArgs },
+              recovery: `give ${option.flag} once, with a comma-separated list (${option.flag}=a,b)`
+            }
+          );
+        }
+        const recovery = `give ${option.flag} once, with a comma-separated list; only the first occurrence is used`;
+        config2.warnings.push({
+          code: TOOL_FILTER_ERROR_CODE,
+          reason: "DUPLICATE_FLAG",
+          message: formatToolFilterMessage(
+            `${option.flag} is given ${cliArgs.length} times (using the first)`,
+            recovery
+          ),
+          context: Object.freeze({
+            option: option.key,
+            received: cliArgs,
+            reason: "DUPLICATE_FLAG"
+          }),
+          recovery
+        });
+      }
+      raw2 = cliArgs[0].slice(prefix.length);
+      source = "cli";
+      if (splitList(raw2).length === 0) throw emptyValue(option, "cli", raw2);
+    } else {
+      const fromEnv = getEnv(option.envVar);
+      if (fromEnv !== void 0 && fromEnv.trim() !== "") {
+        raw2 = fromEnv;
+        source = "env";
+        if (splitList(raw2).length === 0) throw emptyValue(option, "env", raw2);
+      }
+    }
+    if (raw2 !== void 0 && source !== void 0) {
+      config2[option.key] = splitList(raw2);
+      config2.sources[option.key] = source;
+    }
+  }
+  return config2;
+}
+
 // src/ui/viewers.ts
 var UI_VIEWERS = [
   "invoice-viewer",
@@ -60668,16 +61688,16 @@ function buildAuthProvider(config2) {
 }
 
 // src/cache/warm.ts
-async function warmCache() {
+async function warmCache(activeTools = allTools) {
   const configured = env6("MCP_CACHE_WARM_TOOLS");
   if (!configured?.trim()) return;
   const client = getFrappeClient();
   const names = configured.split(",").map((s) => s.trim()).filter(Boolean);
   for (const name of names) {
-    const tool = getToolByName(name);
+    const tool = activeTools.find((t) => t.name === name);
     if (!tool) {
       console.error(
-        `[mcp-erpnext] Cache warm: unknown tool "${name}", skipping`
+        allTools.some((t) => t.name === name) ? `[mcp-erpnext] Cache warm: "${name}" is not in active tool selection, skipping` : `[mcp-erpnext] Cache warm: unknown tool "${name}", skipping`
       );
       continue;
     }
@@ -60768,8 +61788,10 @@ async function main() {
     ]);
     return;
   }
-  const categoriesArg = args.find((arg) => arg.startsWith("--categories="));
-  const categories = categoriesArg ? categoriesArg.split("=")[1].split(",") : void 0;
+  const selectionConfig = readSelectionConfig(args);
+  for (const warning of selectionConfig.warnings) {
+    console.error(warning.message);
+  }
   const httpFlag = args.includes("--http");
   const portArg = args.find((arg) => arg.startsWith("--port="));
   const httpPort = portArg ? parseInt(portArg.split("=")[1], 10) : DEFAULT_HTTP_PORT;
@@ -60781,13 +61803,19 @@ async function main() {
   const mrtrConfig = loadMrtrConfig();
   const toolsClient = new ErpNextToolsClient(
     {
-      ...categories ? { categories } : {},
+      ...selectionConfig.categories ? { categories: selectionConfig.categories } : {},
+      ...selectionConfig.excludeCategories ? { excludeCategories: selectionConfig.excludeCategories } : {},
+      ...selectionConfig.excludeTools ? { excludeTools: selectionConfig.excludeTools } : {},
       enableLinkDisambiguation: mrtrConfig !== void 0
     }
   );
+  for (const warning of toolsClient.selection.warnings) {
+    console.error(warning.message);
+  }
+  assertNonEmptySelection(toolsClient.selection);
   const server = new McpApp({
     name: "mcp-erpnext",
-    version: "3.2.0-beta.1",
+    version: "3.2.0",
     transport: "stateless",
     cache: {
       ttlMs: 36e5,
@@ -60822,7 +61850,7 @@ async function main() {
     const remoteTarget = distPath ? remoteViewerNetTarget(distPath) : null;
     if (distPath && remoteTarget !== null && !isViewerNetAllowed(netPermission3(remoteTarget))) {
       skippedRemoteViewers.push(viewerName);
-      skippedRemoteHost = new URL(distPath).hostname;
+      skippedRemoteHost = remoteTarget;
     } else if (distPath) {
       server.registerResource(
         withViewerResourceMeta({
@@ -60840,7 +61868,9 @@ async function main() {
           });
         }
       );
-      console.error(`[mcp-erpnext] Registered UI resource: ${resourceUri}`);
+      console.error(
+        remoteTarget !== null ? `[mcp-erpnext] Registered UI resource (remote, fetched on first read, cached): ${resourceUri}` : `[mcp-erpnext] Registered UI resource: ${resourceUri}`
+      );
     } else {
       console.error(
         `[mcp-erpnext] Warning: UI not built for ${resourceUri}. Run 'cd lib/erpnext/src/ui && node build-all.mjs' first or package ui-dist with the npm bundle.`
@@ -60848,16 +61878,28 @@ async function main() {
     }
   }
   if (skippedRemoteViewers.length > 0) {
-    console.error(`[mcp-erpnext] ${JSON.stringify({
-      code: "VIEWER_REMOTE_PERMISSION_DENIED",
-      context: { host: skippedRemoteHost, viewers: skippedRemoteViewers },
-      recovery: viewerNetRecovery(skippedRemoteHost)
-    })}`);
+    console.error(
+      `[mcp-erpnext] ${JSON.stringify({
+        level: "warn",
+        code: "VIEWER_REMOTE_PERMISSION_DENIED",
+        context: {
+          host: skippedRemoteHost,
+          viewers: skippedRemoteViewers
+        },
+        recovery: viewerNetRecovery(skippedRemoteHost.split(":")[0])
+      })}`
+    );
   }
+  const { sources } = selectionConfig;
+  const filterSummary = [
+    selectionConfig.categories && `categories: ${selectionConfig.categories.join(", ")} [${sources.categories}]`,
+    selectionConfig.excludeCategories && `excluded categories: ${selectionConfig.excludeCategories.join(", ")} [${sources.excludeCategories}]`,
+    selectionConfig.excludeTools && `excluded tools: ${selectionConfig.excludeTools.join(", ")} [${sources.excludeTools}]`
+  ].filter(Boolean).join("; ");
   console.error(
-    `[mcp-erpnext] Initialized \u2014 ${toolsClient.count} tools${categories ? ` (categories: ${categories.join(", ")})` : ""}`
+    `[mcp-erpnext] Initialized \u2014 ${toolsClient.count} tools${filterSummary ? ` (${filterSummary})` : ""}`
   );
-  warmCache().catch((err) => {
+  warmCache(toolsClient.listTools()).catch((err) => {
     console.error("[mcp-erpnext] Cache warm failed (non-fatal):", err);
   });
   if (httpFlag) {
@@ -60903,6 +61945,18 @@ async function main() {
   }
 }
 main().catch((err) => {
+  if (isToolFilterError(err)) {
+    console.error(
+      `[mcp-erpnext] ${JSON.stringify({
+        code: err.code,
+        message: err.detail,
+        retryable: err.retryable,
+        context: err.context,
+        recovery: err.recovery
+      })}`
+    );
+    exit3(1);
+  }
   console.error("[mcp-erpnext] Fatal error:", err);
   exit3(1);
 });