@casys/mcp-erpnext 3.1.0-beta.1 → 3.1.0-beta.2

package/mcp-erpnext.mjs

@@ -47185,6 +47185,7 @@ var viewer = (name) => ({
   ui: { resourceUri: `ui://mcp-erpnext/${name}` }
 });
 var DOCLIST_META = viewer("doclist-viewer");
+var DOC_META = viewer("doc-viewer");
 var INVOICE_META = viewer("invoice-viewer");
 var STOCK_META = viewer("stock-viewer");
 var CHART_META = viewer("chart-viewer");
@@ -47284,6 +47285,115 @@ function stableStringify(value) {
 var DEFAULT_RETRY_STATUSES = [408, 429, 502, 503, 504];
 var DEFAULT_RETRY_METHODS = ["GET"];
 var DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_DOWNLOAD_BYTES = 10 * 1024 * 1024;
+var MAX_ERROR_BODY_BYTES = 64 * 1024;
+var ResponseBodyLimitError = class extends Error {
+  constructor(label, size, limit) {
+    super(
+      `[FrappeClient] ${label} size ${size} bytes exceeds the ${limit}-byte limit`
+    );
+    this.name = "ResponseBodyLimitError";
+  }
+};
+async function readResponseBytes(response, maxBytes, label) {
+  const declaredLength = response.headers.get("content-length")?.trim();
+  if (declaredLength && /^\d+$/.test(declaredLength)) {
+    const size = Number(declaredLength);
+    if (size > maxBytes) {
+      try {
+        await response.body?.cancel();
+      } catch {
+      }
+      throw new ResponseBodyLimitError(label, size, maxBytes);
+    }
+  }
+  if (!response.body) return new Uint8Array();
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        try {
+          await reader.cancel();
+        } catch {
+        }
+        throw new ResponseBodyLimitError(label, total, maxBytes);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+function isUnsafeControl(character) {
+  const codePoint = character.codePointAt(0) ?? 0;
+  return codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297;
+}
+function validateLocalFileUrl(fileUrl, isPrivate) {
+  if (typeof fileUrl !== "string" || fileUrl.length === 0) {
+    throw new Error("[FrappeClient] File.file_url must be a non-empty string");
+  }
+  if (fileUrl !== fileUrl.trim()) {
+    throw new Error(
+      "[FrappeClient] File.file_url must not contain whitespace padding"
+    );
+  }
+  const expectedPrefix = isPrivate ? "/private/files/" : "/files/";
+  let decoded = fileUrl;
+  for (let depth = 0; depth < 5; depth++) {
+    if (Array.from(decoded).some(isUnsafeControl) || decoded.includes("\\") || decoded.includes("?") || decoded.includes("#")) {
+      throw new Error(
+        "[FrappeClient] File.file_url must be a local Frappe file path without query, fragment, NUL, or backslash"
+      );
+    }
+    if (!decoded.startsWith(expectedPrefix)) {
+      throw new Error(
+        `[FrappeClient] File.file_url does not match is_private=${isPrivate ? 1 : 0}`
+      );
+    }
+    const fileSegment = decoded.slice(expectedPrefix.length);
+    if (!fileSegment || fileSegment === "." || fileSegment === ".." || fileSegment.includes("/")) {
+      throw new Error(
+        "[FrappeClient] File.file_url must contain exactly one safe file segment"
+      );
+    }
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      throw new Error(
+        "[FrappeClient] File.file_url contains malformed percent encoding"
+      );
+    }
+    if (next === decoded) return fileUrl;
+    decoded = next;
+  }
+  throw new Error(
+    "[FrappeClient] File.file_url contains excessive nested percent encoding"
+  );
+}
+function sanitizeDownloadFileName(raw2, fileId) {
+  const fallbackId = fileId.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80) || "file";
+  if (typeof raw2 !== "string") return `erpnext-${fallbackId}`;
+  const normalized = Array.from(raw2.normalize("NFC")).filter((character) => !isUnsafeControl(character)).join("").replace(/[\\/:*?"<>|]/g, "_").trim().replace(/[. ]+$/g, "");
+  const bounded = Array.from(normalized).slice(0, 255).join("");
+  return !bounded || bounded === "." || bounded === ".." ? `erpnext-${fallbackId}` : bounded;
+}
+function normalizeMimeType(raw2) {
+  const candidate = (raw2 ?? "").split(";", 1)[0].trim().toLowerCase();
+  return /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i.test(candidate) && candidate !== "application/unknown" ? candidate : "application/octet-stream";
+}
 function decodeBase64File(contentBase64, maxBytes) {
   if (contentBase64.length === 0) {
     throw new Error("[FrappeClient] File content must not be empty");
@@ -47369,6 +47479,7 @@ var FrappeClient = class {
   authHeader;
   timeoutMs;
   maxUploadBytes;
+  maxDownloadBytes;
   retries;
   retryStatuses;
   retryBackoffMs;
@@ -47384,6 +47495,12 @@ var FrappeClient = class {
         "[FrappeClient] maxUploadBytes must be a positive integer"
       );
     }
+    this.maxDownloadBytes = config2.maxDownloadBytes ?? DEFAULT_MAX_DOWNLOAD_BYTES;
+    if (!Number.isInteger(this.maxDownloadBytes) || this.maxDownloadBytes <= 0) {
+      throw new Error(
+        "[FrappeClient] maxDownloadBytes must be a positive integer"
+      );
+    }
     this.retries = config2.retries ?? 3;
     this.retryStatuses = config2.retryStatuses ?? DEFAULT_RETRY_STATUSES;
     this.retryBackoffMs = config2.retryBackoffMs ?? 200;
@@ -47498,6 +47615,152 @@ var FrappeClient = class {
     }
     return responseBody;
   }
+  buildSameOriginUrl(path) {
+    if (!path.startsWith("/")) {
+      throw new Error("[FrappeClient] Download path must be root-relative");
+    }
+    let base;
+    let target;
+    try {
+      base = new URL(this.baseUrl);
+      target = new URL(`${this.baseUrl}${path}`);
+    } catch {
+      throw new Error("[FrappeClient] baseUrl must be a valid absolute URL");
+    }
+    if (target.origin !== base.origin) {
+      throw new Error("[FrappeClient] Refusing a cross-origin download");
+    }
+    return target.href;
+  }
+  async requestBinary(path) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        return await this.requestBinaryOnce(path);
+      } catch (err) {
+        lastError = err;
+        if (attempt === this.retries || !this.isRetryable(err, "GET")) {
+          throw err;
+        }
+        const delay = this.computeBackoff(attempt, err);
+        if (delay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw lastError;
+  }
+  async requestBinaryOnce(path) {
+    const url2 = this.buildSameOriginUrl(path);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await fetch(url2, {
+        method: "GET",
+        headers: {
+          "Authorization": this.authHeader,
+          "Accept": "*/*",
+          "Cache-Control": "no-store"
+        },
+        cache: "no-store",
+        redirect: "manual",
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new FrappeAPIError(
+          `Request timed out after ${this.timeoutMs}ms: GET ${path}`,
+          408,
+          null
+        );
+      }
+      throw new FrappeAPIError(
+        `Network error on GET ${path}: ${err.message}`,
+        0,
+        null
+      );
+    }
+    try {
+      if (response.redirected || response.type === "opaqueredirect" || response.status >= 300 && response.status < 400) {
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+        throw new FrappeAPIError(
+          `GET ${path} refused an HTTP redirect`,
+          response.status,
+          null
+        );
+      }
+      if (!response.ok) {
+        let rawText;
+        try {
+          const errorBytes = await readResponseBytes(
+            response,
+            MAX_ERROR_BODY_BYTES,
+            "Error response body"
+          );
+          rawText = new TextDecoder().decode(errorBytes);
+        } catch (err) {
+          if (!(err instanceof ResponseBodyLimitError)) throw err;
+          rawText = err.message;
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        let responseBody = rawText;
+        if (contentType.includes("application/json") && rawText.length > 0) {
+          try {
+            responseBody = JSON.parse(rawText);
+          } catch {
+            responseBody = rawText;
+          }
+        }
+        let message2 = response.statusText;
+        if (typeof responseBody === "object" && responseBody !== null) {
+          const body = responseBody;
+          const baseMessage = body.message ?? body.exc_type ?? response.statusText;
+          const serverDetails = extractServerMessages(body._server_messages);
+          message2 = serverDetails ? `${baseMessage}: ${serverDetails}` : baseMessage;
+        } else if (typeof responseBody === "string" && responseBody.length > 0) {
+          message2 = responseBody.slice(0, 200);
+        }
+        throw new FrappeAPIError(
+          `GET ${path} failed: ${message2}`,
+          response.status,
+          responseBody,
+          parseRetryAfter(response.headers.get("retry-after"))
+        );
+      }
+      const bytes = await readResponseBytes(
+        response,
+        this.maxDownloadBytes,
+        "Downloaded file"
+      );
+      return {
+        bytes,
+        mimeType: normalizeMimeType(response.headers.get("content-type"))
+      };
+    } catch (err) {
+      if (err instanceof FrappeAPIError || err instanceof ResponseBodyLimitError) {
+        throw err;
+      }
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new FrappeAPIError(
+          `Request timed out after ${this.timeoutMs}ms: GET ${path}`,
+          408,
+          null
+        );
+      }
+      throw new FrappeAPIError(
+        `Network error while reading GET ${path}: ${err.message}`,
+        0,
+        null
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   // ── Resource CRUD ───────────────────────────────────────────────────────────
   /**
    * List documents of a DocType.
@@ -47619,6 +47882,73 @@ var FrappeClient = class {
     );
     this.invalidate(doctype, name);
   }
+  /**
+   * Download one File row through Frappe's authenticated download handler.
+   *
+   * The caller supplies the expected attachment owner as a confused-deputy
+   * guard. The File row is fetched fresh, its local path is validated, and the
+   * response stream is stopped as soon as it exceeds `maxDownloadBytes`.
+   */
+  async downloadFile(input) {
+    const fileId = input.fileId.trim();
+    const attachedToDoctype = input.attachedToDoctype.trim();
+    const attachedToName = input.attachedToName.trim();
+    if (!fileId) {
+      throw new Error("[FrappeClient] fileId must not be empty");
+    }
+    if (!attachedToDoctype) {
+      throw new Error("[FrappeClient] attachedToDoctype must not be empty");
+    }
+    if (!attachedToName) {
+      throw new Error("[FrappeClient] attachedToName must not be empty");
+    }
+    const metadata = await this.request(
+      "GET",
+      `/api/resource/File/${encodeURIComponent(fileId)}`
+    );
+    const file = metadata.data;
+    if (file.name !== fileId) {
+      throw new Error("[FrappeClient] File response identity mismatch");
+    }
+    if (file.attached_to_doctype !== attachedToDoctype || file.attached_to_name !== attachedToName) {
+      throw new Error(
+        "[FrappeClient] File is not attached to the requested document"
+      );
+    }
+    if (file.is_private !== 0 && file.is_private !== 1) {
+      throw new Error("[FrappeClient] File.is_private must be 0 or 1");
+    }
+    const fileUrl = validateLocalFileUrl(
+      file.file_url,
+      file.is_private === 1
+    );
+    const fileSize = file.file_size;
+    if (fileSize !== void 0 && fileSize !== null) {
+      if (typeof fileSize !== "number" || !Number.isInteger(fileSize) || fileSize < 0) {
+        throw new Error(
+          "[FrappeClient] File.file_size must be a non-negative integer"
+        );
+      }
+      if (fileSize > this.maxDownloadBytes) {
+        throw new ResponseBodyLimitError(
+          "File metadata",
+          fileSize,
+          this.maxDownloadBytes
+        );
+      }
+    }
+    const params = new URLSearchParams({ file_url: fileUrl });
+    const download = await this.requestBinary(
+      `/api/method/frappe.handler.download_file?${params.toString()}`
+    );
+    return {
+      fileId,
+      fileName: sanitizeDownloadFileName(file.file_name, fileId),
+      mimeType: download.mimeType,
+      bytes: download.bytes,
+      isPrivate: file.is_private === 1
+    };
+  }
   /**
    * Upload file bytes and attach the native File document to another document.
    * POST /api/method/upload_file
@@ -47689,6 +48019,7 @@ function getFrappeClient() {
   const apiKey = env6("ERPNEXT_API_KEY");
   const apiSecret = env6("ERPNEXT_API_SECRET");
   const maxUploadBytesRaw = env6("ERPNEXT_MAX_UPLOAD_BYTES");
+  const maxDownloadBytesRaw = env6("ERPNEXT_MAX_DOWNLOAD_BYTES");
   if (!url2) {
     throw new Error(
       "[lib/erpnext] ERPNEXT_URL is required. Set it to your ERPNext instance URL, e.g. http://localhost:8000"
@@ -47704,7 +48035,8 @@ function getFrappeClient() {
     apiKey,
     apiSecret,
     cache: getCache(),
-    maxUploadBytes: maxUploadBytesRaw?.trim() ? Number(maxUploadBytesRaw) : void 0
+    maxUploadBytes: maxUploadBytesRaw?.trim() ? Number(maxUploadBytesRaw) : void 0,
+    maxDownloadBytes: maxDownloadBytesRaw?.trim() ? Number(maxDownloadBytesRaw) : void 0
   });
   return _client;
 }
@@ -47929,6 +48261,7 @@ var salesTools = [
   {
     name: "erpnext_customer_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single ERPNext customer by name (ID). Returns all fields including contact details.",
     category: "sales",
     inputSchema: {
@@ -47943,7 +48276,7 @@ var salesTools = [
         throw new Error("[erpnext_customer_get] 'name' is required");
       }
       const doc = await ctx.client.get("Customer", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Customer" } };
     }
   },
   {
@@ -48851,6 +49184,7 @@ var inventoryTools = [
   {
     name: "erpnext_item_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single ERPNext Item by name/item_code. Returns all fields including pricing and stock details.",
     category: "inventory",
     inputSchema: {
@@ -48865,7 +49199,7 @@ var inventoryTools = [
         throw new Error("[erpnext_item_get] 'name' is required");
       }
       const doc = await ctx.client.get("Item", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Item" } };
     }
   },
   {
@@ -49135,6 +49469,7 @@ var inventoryTools = [
   {
     name: "erpnext_stock_entry_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Stock Entry by name. Returns full document with item details.",
     category: "inventory",
     inputSchema: {
@@ -49152,7 +49487,7 @@ var inventoryTools = [
         throw new Error("[erpnext_stock_entry_get] 'name' is required");
       }
       const doc = await ctx.client.get("Stock Entry", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Stock Entry" } };
     }
   },
   {
@@ -49347,6 +49682,7 @@ var accountingTools = [
   {
     name: "erpnext_journal_entry_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Journal Entry by name (e.g. JV-00001). Returns full document with accounts.",
     category: "accounting",
     inputSchema: {
@@ -49364,7 +49700,7 @@ var accountingTools = [
         throw new Error("[erpnext_journal_entry_get] 'name' is required");
       }
       const doc = await ctx.client.get("Journal Entry", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Journal Entry" } };
     }
   },
   // ── Payment Entries ───────────────────────────────────────────────────────
@@ -49452,6 +49788,7 @@ var accountingTools = [
   {
     name: "erpnext_payment_entry_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Payment Entry by name (e.g. PE-00001). Returns full document including references.",
     category: "accounting",
     inputSchema: {
@@ -49469,7 +49806,7 @@ var accountingTools = [
         throw new Error("[erpnext_payment_entry_get] 'name' is required");
       }
       const doc = await ctx.client.get("Payment Entry", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Payment Entry" } };
     }
   },
   {
@@ -49595,6 +49932,7 @@ var hrTools = [
   {
     name: "erpnext_employee_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Employee by name/ID (e.g. HR-EMP-00001). Returns all fields.",
     category: "hr",
     inputSchema: {
@@ -49619,7 +49957,7 @@ var hrTools = [
         { allowPartialMatch: false, inputPath: "name" }
       );
       const doc = await ctx.client.get("Employee", employeeId);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Employee" } };
     }
   },
   // ── Attendance ────────────────────────────────────────────────────────────
@@ -49770,6 +50108,7 @@ var hrTools = [
   {
     name: "erpnext_leave_application_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Leave Application by name. Returns full document.",
     category: "hr",
     inputSchema: {
@@ -49787,7 +50126,7 @@ var hrTools = [
         "Leave Application",
         input.name
       );
-      return { data: doc };
+      return { data: { ...doc, doctype: "Leave Application" } };
     }
   },
   {
@@ -49933,6 +50272,7 @@ var hrTools = [
   {
     name: "erpnext_salary_slip_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Salary Slip by name/ID. Returns all fields including earnings and deductions.",
     category: "hr",
     inputSchema: {
@@ -49950,7 +50290,7 @@ var hrTools = [
         throw new Error("[erpnext_salary_slip_get] 'name' is required");
       }
       const doc = await ctx.client.get("Salary Slip", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Salary Slip" } };
     }
   },
   // ── Payroll Entries ───────────────────────────────────────────────────────
@@ -50441,6 +50781,7 @@ var projectTools = [
   {
     name: "erpnext_project_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Project by name. Returns full document including tasks summary.",
     category: "project",
     inputSchema: {
@@ -50455,7 +50796,7 @@ var projectTools = [
         throw new Error("[erpnext_project_get] 'name' is required");
       }
       const doc = await ctx.client.get("Project", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Project" } };
     }
   },
   // ── Tasks ─────────────────────────────────────────────────────────────────
@@ -50620,6 +50961,7 @@ var projectTools = [
   {
     name: "erpnext_task_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Task by name. Returns full document including description and dependencies.",
     category: "project",
     inputSchema: {
@@ -50634,7 +50976,7 @@ var projectTools = [
         throw new Error("[erpnext_task_get] 'name' is required");
       }
       const doc = await ctx.client.get("Task", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Task" } };
     }
   },
   {
@@ -50810,6 +51152,7 @@ var projectTools = [
   {
     name: "erpnext_timesheet_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Timesheet by name. Returns full document with time log details.",
     category: "project",
     inputSchema: {
@@ -50824,7 +51167,7 @@ var projectTools = [
         throw new Error("[erpnext_timesheet_get] 'name' is required");
       }
       const doc = await ctx.client.get("Timesheet", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Timesheet" } };
     }
   },
   {
@@ -50946,6 +51289,7 @@ var purchasingTools = [
   {
     name: "erpnext_supplier_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single ERPNext supplier by name (ID). Returns all fields including contact details.",
     category: "purchasing",
     inputSchema: {
@@ -50960,7 +51304,7 @@ var purchasingTools = [
         throw new Error("[erpnext_supplier_get] 'name' is required");
       }
       const doc = await ctx.client.get("Supplier", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Supplier" } };
     }
   },
   {
@@ -51089,6 +51433,7 @@ var purchasingTools = [
   {
     name: "erpnext_purchase_order_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Purchase Order by name (e.g. PO-00001). Returns full document with line items.",
     category: "purchasing",
     inputSchema: {
@@ -51106,7 +51451,7 @@ var purchasingTools = [
         throw new Error("[erpnext_purchase_order_get] 'name' is required");
       }
       const doc = await ctx.client.get("Purchase Order", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Purchase Order" } };
     }
   },
   {
@@ -51257,6 +51602,7 @@ var purchasingTools = [
   {
     name: "erpnext_purchase_invoice_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Purchase Invoice by name (e.g. PINV-00001). Returns full document with line items.",
     category: "purchasing",
     inputSchema: {
@@ -51277,7 +51623,7 @@ var purchasingTools = [
         "Purchase Invoice",
         input.name
       );
-      return { data: doc };
+      return { data: { ...doc, doctype: "Purchase Invoice" } };
     }
   },
   // ── Purchase Receipts ─────────────────────────────────────────────────────
@@ -51351,6 +51697,7 @@ var purchasingTools = [
   {
     name: "erpnext_purchase_receipt_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Purchase Receipt by name (e.g. MAT-PRE-00001). Returns full document with received items.",
     category: "purchasing",
     inputSchema: {
@@ -51371,7 +51718,7 @@ var purchasingTools = [
         "Purchase Receipt",
         input.name
       );
-      return { data: doc };
+      return { data: { ...doc, doctype: "Purchase Receipt" } };
     }
   },
   // ── Supplier Quotations ───────────────────────────────────────────────────
@@ -51516,6 +51863,7 @@ var deliveryTools = [
   {
     name: "erpnext_delivery_note_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Delivery Note by name (e.g. MAT-DN-00001). Returns full document with delivered items.",
     category: "delivery",
     inputSchema: {
@@ -51533,7 +51881,7 @@ var deliveryTools = [
         throw new Error("[erpnext_delivery_note_get] 'name' is required");
       }
       const doc = await ctx.client.get("Delivery Note", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Delivery Note" } };
     }
   },
   {
@@ -51666,6 +52014,7 @@ var deliveryTools = [
   {
     name: "erpnext_shipment_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Shipment by name. Returns full shipment details including parcels.",
     category: "delivery",
     inputSchema: {
@@ -51680,7 +52029,7 @@ var deliveryTools = [
         throw new Error("[erpnext_shipment_get] 'name' is required");
       }
       const doc = await ctx.client.get("Shipment", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Shipment" } };
     }
   }
 ];
@@ -51760,6 +52109,7 @@ var manufacturingTools = [
   {
     name: "erpnext_bom_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single BOM by name (e.g. BOM-ITEM-00001). Returns full document with raw materials and operations.",
     category: "manufacturing",
     inputSchema: {
@@ -51774,7 +52124,7 @@ var manufacturingTools = [
         throw new Error("[erpnext_bom_get] 'name' is required");
       }
       const doc = await ctx.client.get("BOM", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "BOM" } };
     }
   },
   // ── Work Orders ───────────────────────────────────────────────────────────
@@ -51852,6 +52202,7 @@ var manufacturingTools = [
   {
     name: "erpnext_work_order_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Work Order by name (e.g. MFG-WO-00001). Returns full document with operations and materials.",
     category: "manufacturing",
     inputSchema: {
@@ -51869,7 +52220,7 @@ var manufacturingTools = [
         throw new Error("[erpnext_work_order_get] 'name' is required");
       }
       const doc = await ctx.client.get("Work Order", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Work Order" } };
     }
   },
   {
@@ -51985,6 +52336,7 @@ var manufacturingTools = [
   {
     name: "erpnext_job_card_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Job Card by name. Returns full document with time logs and material transfers.",
     category: "manufacturing",
     inputSchema: {
@@ -51999,7 +52351,7 @@ var manufacturingTools = [
         throw new Error("[erpnext_job_card_get] 'name' is required");
       }
       const doc = await ctx.client.get("Job Card", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Job Card" } };
     }
   }
 ];
@@ -52061,6 +52413,7 @@ var crmTools = [
   {
     name: "erpnext_lead_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single CRM Lead by name. Returns all lead details including contact info.",
     category: "crm",
     inputSchema: {
@@ -52075,7 +52428,7 @@ var crmTools = [
         throw new Error("[erpnext_lead_get] 'name' is required");
       }
       const doc = await ctx.client.get("Lead", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Lead" } };
     }
   },
   {
@@ -52207,6 +52560,7 @@ var crmTools = [
   {
     name: "erpnext_opportunity_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single CRM Opportunity by name. Returns full details including items and competitors.",
     category: "crm",
     inputSchema: {
@@ -52221,7 +52575,7 @@ var crmTools = [
         throw new Error("[erpnext_opportunity_get] 'name' is required");
       }
       const doc = await ctx.client.get("Opportunity", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Opportunity" } };
     }
   },
   // ── Contacts ──────────────────────────────────────────────────────────────
@@ -52276,6 +52630,7 @@ var crmTools = [
   {
     name: "erpnext_contact_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Contact by name. Returns all contact details.",
     category: "crm",
     inputSchema: {
@@ -52290,7 +52645,7 @@ var crmTools = [
         throw new Error("[erpnext_contact_get] 'name' is required");
       }
       const doc = await ctx.client.get("Contact", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Contact" } };
     }
   },
   // ── Campaigns ─────────────────────────────────────────────────────────────
@@ -52440,6 +52795,7 @@ var assetsTools = [
   {
     name: "erpnext_asset_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Asset by name. Returns full details including depreciation schedule and maintenance logs.",
     category: "assets",
     inputSchema: {
@@ -52454,7 +52810,7 @@ var assetsTools = [
         throw new Error("[erpnext_asset_get] 'name' is required");
       }
       const doc = await ctx.client.get("Asset", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Asset" } };
     }
   },
   {
@@ -52590,6 +52946,7 @@ var assetsTools = [
   {
     name: "erpnext_asset_movement_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Asset Movement by name. Returns full details including assets moved.",
     category: "assets",
     inputSchema: {
@@ -52604,7 +52961,7 @@ var assetsTools = [
         throw new Error("[erpnext_asset_movement_get] 'name' is required");
       }
       const doc = await ctx.client.get("Asset Movement", input.name);
-      return { data: doc };
+      return { data: { ...doc, doctype: "Asset Movement" } };
     }
   },
   // ── Asset Maintenance ─────────────────────────────────────────────────────
@@ -52661,6 +53018,7 @@ var assetsTools = [
   {
     name: "erpnext_asset_maintenance_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get a single Asset Maintenance record by name. Returns full details including maintenance tasks.",
     category: "assets",
     inputSchema: {
@@ -52678,7 +53036,7 @@ var assetsTools = [
         "Asset Maintenance",
         input.name
       );
-      return { data: doc };
+      return { data: { ...doc, doctype: "Asset Maintenance" } };
     }
   },
   // ── Asset Categories ──────────────────────────────────────────────────────
@@ -52713,6 +53071,16 @@ var assetsTools = [
 ];
 
 // src/tools/operations.ts
+function bytesToBase64(bytes) {
+  const chunkSize = 32 * 1024;
+  let binary = "";
+  for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+    binary += String.fromCharCode(
+      ...bytes.subarray(offset, Math.min(offset + chunkSize, bytes.byteLength))
+    );
+  }
+  return btoa(binary);
+}
 var operationsTools = [
   // ── File Attachments ───────────────────────────────────────────────────────
   {
@@ -52790,6 +53158,74 @@ var operationsTools = [
       };
     }
   },
+  {
+    name: "erpnext_file_download",
+    annotations: { readOnlyHint: true },
+    _meta: {
+      ui: {
+        resourceUri: DOC_META.ui.resourceUri,
+        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.",
+    category: "operations",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_id: {
+          type: "string",
+          description: "Native ERPNext File.name identifier, never a URL.",
+          minLength: 1
+        },
+        attached_to_doctype: {
+          type: "string",
+          description: "Expected parent document DocType.",
+          minLength: 1
+        },
+        attached_to_name: {
+          type: "string",
+          description: "Expected parent document name/ID.",
+          minLength: 1
+        }
+      },
+      required: ["file_id", "attached_to_doctype", "attached_to_name"],
+      additionalProperties: false
+    },
+    handler: async (input, ctx) => {
+      for (const field of [
+        "file_id",
+        "attached_to_doctype",
+        "attached_to_name"
+      ]) {
+        if (typeof input[field] !== "string" || !input[field].trim()) {
+          throw new Error(
+            `[erpnext_file_download] '${field}' must be a non-empty string`
+          );
+        }
+      }
+      const file = await ctx.client.downloadFile({
+        fileId: input.file_id.trim(),
+        attachedToDoctype: input.attached_to_doctype.trim(),
+        attachedToName: input.attached_to_name.trim()
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Prepared ${file.fileName} for download (${file.bytes.byteLength} bytes).`
+          },
+          {
+            type: "resource",
+            resource: {
+              uri: `file:///${encodeURIComponent(file.fileName)}`,
+              mimeType: file.mimeType,
+              blob: bytesToBase64(file.bytes)
+            }
+          }
+        ]
+      };
+    }
+  },
   {
     name: "erpnext_file_upload",
     annotations: { destructiveHint: true },
@@ -53091,6 +53527,7 @@ var operationsTools = [
   {
     name: "erpnext_doc_get",
     annotations: { readOnlyHint: true },
+    _meta: DOC_META,
     description: "Get any ERPNext document by DocType and name. Useful for DocTypes not covered by dedicated tools. Returns the full document with all fields.",
     category: "operations",
     inputSchema: {
@@ -53108,17 +53545,18 @@ var operationsTools = [
       required: ["doctype", "name"]
     },
     handler: async (input, ctx) => {
-      if (!input.doctype) {
+      if (typeof input.doctype !== "string" || !input.doctype.trim()) {
         throw new Error("[erpnext_doc_get] 'doctype' is required");
       }
-      if (!input.name) {
+      if (typeof input.name !== "string" || !input.name.trim()) {
         throw new Error("[erpnext_doc_get] 'name' is required");
       }
+      const doctype = input.doctype.trim();
       const doc = await ctx.client.get(
-        input.doctype,
-        input.name
+        doctype,
+        input.name.trim()
       );
-      return { data: doc };
+      return { data: { ...doc, doctype } };
     }
   },
   // ── Generic List ──────────────────────────────────────────────────────────
@@ -56755,12 +57193,24 @@ function isDoclistViewer(result) {
   const uri = result._meta?.ui?.resourceUri;
   return uri === "ui://mcp-erpnext/doclist-viewer";
 }
+function isDocViewer(result) {
+  const uri = result._meta?.ui?.resourceUri;
+  return uri === "ui://mcp-erpnext/doc-viewer";
+}
 var VIEWER_TOOL_CANDIDATES = {
   "ui://mcp-erpnext/invoice-viewer": [
     "erpnext_item_get",
-    "erpnext_stock_balance"
+    "erpnext_stock_balance",
+    "erpnext_file_list",
+    "erpnext_file_upload",
+    "erpnext_file_download"
   ],
   "ui://mcp-erpnext/doclist-viewer": [],
+  "ui://mcp-erpnext/doc-viewer": [
+    "erpnext_file_list",
+    "erpnext_file_upload",
+    "erpnext_file_download"
+  ],
   "ui://mcp-erpnext/kanban-viewer": [
     "erpnext_doc_get",
     "erpnext_doc_update",
@@ -56803,7 +57253,7 @@ var INVOICE_DEDICATED_MUTATION_TOOLS = {
 };
 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") {
+  if (uri === "ui://mcp-erpnext/invoice-viewer" || uri === "ui://mcp-erpnext/doclist-viewer" || uri === "ui://mcp-erpnext/doc-viewer") {
     target.add("erpnext_doc_submit");
     target.add("erpnext_doc_cancel");
   }
@@ -57004,7 +57454,7 @@ function withUiRefreshRequest(result, toolName, args, now = /* @__PURE__ */ new
       if (hints) enriched._sendMessageHints = hints;
     } else if (isStockViewer(enriched)) {
       enriched._sendMessageHints = STOCK_HINTS;
-    } else if (isKanbanViewer(enriched) && doctype) {
+    } else if ((isKanbanViewer(enriched) || isDocViewer(enriched)) && doctype) {
       const hints = DOCTYPE_SEND_MESSAGE_HINTS[doctype];
       if (hints) enriched._sendMessageHints = hints;
     }
@@ -57016,6 +57466,19 @@ function withUiRefreshRequest(result, toolName, args, now = /* @__PURE__ */ new
 function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isSingleEmbeddedBlobResult(value) {
+  if (!isRecord8(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 (!isRecord8(summary) || summary.type !== "text" || typeof summary.text !== "string") {
+    return false;
+  }
+  if (!isRecord8(embedded) || embedded.type !== "resource") return false;
+  if (!isRecord8(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 withSafeUiRefresh(result, tool, args, availableToolNames) {
   const readOnly = tool.annotations?.readOnlyHint === true;
   if (!isRecord8(result)) {
@@ -57115,6 +57578,9 @@ var ErpNextToolsClient = class {
         if (execution.result !== null && typeof execution.result === "object" && !Array.isArray(execution.result) && execution.result.resultType === "input_required") {
           return execution.result;
         }
+        if (tool.name === "erpnext_file_download" && isSingleEmbeddedBlobResult(execution.result)) {
+          return execution.result;
+        }
         const result = withSafeUiRefresh(
           execution.result,
           tool,
@@ -57146,6 +57612,9 @@ var ErpNextToolsClient = class {
     }
     const client = getFrappeClient();
     const result = await tool.handler(args, { client });
+    if (tool.name === "erpnext_file_download" && isSingleEmbeddedBlobResult(result)) {
+      return result;
+    }
     return withSafeUiRefresh(
       result,
       tool,
@@ -57165,6 +57634,7 @@ var UI_VIEWERS = [
   "invoice-viewer",
   "stock-viewer",
   "doclist-viewer",
+  "doc-viewer",
   "chart-viewer",
   "kpi-viewer",
   "funnel-viewer",
@@ -57408,7 +57878,7 @@ async function main() {
   );
   const server = new McpApp({
     name: "mcp-erpnext",
-    version: "3.1.0-beta.1",
+    version: "3.1.0-beta.2",
     transport: "stateless",
     cache: {
       ttlMs: 36e5,