erpnext-mcp 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

erpnext_mcp/client.py

@@ -207,3 +207,169 @@ class ERPNextClient:
             },
         )
         return result.get("data", [])
+
+    # --- File operations ---
+
+    async def upload_file(
+        self,
+        file_content: bytes,
+        filename: str,
+        attached_to_doctype: str | None = None,
+        attached_to_name: str | None = None,
+        is_private: bool = True,
+    ) -> dict:
+        """上傳檔案到 ERPNext。
+
+        Args:
+            file_content: 檔案內容（bytes）
+            filename: 檔案名稱
+            attached_to_doctype: 附加到的 DocType（如 "Project"）
+            attached_to_name: 附加到的文件名稱（如 "PROJ-0001"）
+            is_private: 是否為私有檔案（預設 True）
+
+        Returns:
+            File 文件資料，包含 file_url 等
+        """
+        # 使用獨立的 httpx client 避免 header 衝突
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=60.0) as client:
+            # 準備 multipart form data
+            files = {
+                "file": (filename, file_content),
+            }
+            data: dict[str, str] = {
+                "is_private": "1" if is_private else "0",
+            }
+            if attached_to_doctype:
+                data["doctype"] = attached_to_doctype
+            if attached_to_name:
+                data["docname"] = attached_to_name
+
+            resp = await client.post(
+                "/api/method/upload_file",
+                files=files,
+                data=data,
+                headers={"Authorization": self.headers["Authorization"]},
+            )
+            resp.raise_for_status()
+            result = resp.json()
+            return result.get("message", result)
+
+    async def upload_file_from_url(
+        self,
+        file_url: str,
+        filename: str | None = None,
+        attached_to_doctype: str | None = None,
+        attached_to_name: str | None = None,
+        is_private: bool = True,
+    ) -> dict:
+        """從 URL 上傳檔案到 ERPNext。
+
+        Args:
+            file_url: 檔案來源 URL
+            filename: 檔案名稱（可選，會從 URL 推斷）
+            attached_to_doctype: 附加到的 DocType
+            attached_to_name: 附加到的文件名稱
+            is_private: 是否為私有檔案
+
+        Returns:
+            File 文件資料
+        """
+        # 使用獨立的 httpx client
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=60.0) as client:
+            data: dict[str, str] = {
+                "file_url": file_url,
+                "is_private": "1" if is_private else "0",
+            }
+            if filename:
+                data["filename"] = filename
+            if attached_to_doctype:
+                data["doctype"] = attached_to_doctype
+            if attached_to_name:
+                data["docname"] = attached_to_name
+
+            resp = await client.post(
+                "/api/method/upload_file",
+                data=data,
+                headers={"Authorization": self.headers["Authorization"]},
+            )
+            resp.raise_for_status()
+            result = resp.json()
+            return result.get("message", result)
+
+    async def list_files(
+        self,
+        attached_to_doctype: str | None = None,
+        attached_to_name: str | None = None,
+        is_private: bool | None = None,
+        limit: int = 20,
+    ) -> list[dict]:
+        """列出檔案。
+
+        Args:
+            attached_to_doctype: 過濾附加到的 DocType
+            attached_to_name: 過濾附加到的文件名稱
+            is_private: 過濾私有/公開檔案
+            limit: 返回數量上限
+
+        Returns:
+            File 文件列表
+        """
+        filters: dict[str, Any] = {}
+        if attached_to_doctype:
+            filters["attached_to_doctype"] = attached_to_doctype
+        if attached_to_name:
+            filters["attached_to_name"] = attached_to_name
+        if is_private is not None:
+            filters["is_private"] = 1 if is_private else 0
+
+        result = await self._request(
+            "GET", "/api/resource/File",
+            params={
+                "fields": json.dumps([
+                    "name", "file_name", "file_url", "file_size",
+                    "attached_to_doctype", "attached_to_name",
+                    "is_private", "creation", "modified",
+                ]),
+                "filters": json.dumps(filters) if filters else None,
+                "order_by": "creation desc",
+                "limit_page_length": limit,
+            },
+        )
+        return result.get("data", [])
+
+    async def get_file_url(self, file_name: str) -> str:
+        """取得檔案的完整下載 URL。
+
+        Args:
+            file_name: File 文件的 name（如 "abc123.pdf"）
+
+        Returns:
+            完整的檔案 URL
+        """
+        doc = await self.get_doc("File", file_name)
+        file_url = doc.get("file_url", "")
+        if file_url and not file_url.startswith("http"):
+            return f"{self.base_url}{file_url}"
+        return file_url
+
+    async def download_file(self, file_name: str) -> tuple[bytes, str]:
+        """下載檔案內容。
+
+        Args:
+            file_name: File 文件的 name
+
+        Returns:
+            (檔案內容 bytes, 檔案名稱)
+        """
+        doc = await self.get_doc("File", file_name)
+        file_url = doc.get("file_url", "")
+        original_filename = doc.get("file_name", file_name)
+
+        if not file_url:
+            raise ValueError(f"File {file_name} has no file_url")
+
+        client = await self._get_client()
+        # 下載時不需要 Content-Type: application/json
+        resp = await client.get(file_url)
+        resp.raise_for_status()
+        return resp.content, original_filename

erpnext_mcp/server.py

@@ -310,6 +310,284 @@ async def get_stock_ledger(item_code: str | None = None, warehouse: str | None =
     return await get_client().get_stock_ledger(item_code=item_code, warehouse=warehouse, limit=limit)
 
 
+# ── File Operations ─────────────────────────────────
+
+
+@mcp.tool()
+async def upload_file(
+    file_content_base64: str,
+    filename: str,
+    attached_to_doctype: str | None = None,
+    attached_to_name: str | None = None,
+    is_private: bool = True,
+) -> dict:
+    """Upload a file to ERPNext.
+
+    Args:
+        file_content_base64: File content encoded as base64 string
+        filename: Name for the uploaded file (e.g. "report.pdf")
+        attached_to_doctype: Optional DocType to attach file to (e.g. "Project", "Item")
+        attached_to_name: Optional document name to attach file to (e.g. "PROJ-0001")
+        is_private: Whether file should be private (default True)
+
+    Returns:
+        File document with file_url and other metadata
+    """
+    import base64
+    file_content = base64.b64decode(file_content_base64)
+    return await get_client().upload_file(
+        file_content=file_content,
+        filename=filename,
+        attached_to_doctype=attached_to_doctype,
+        attached_to_name=attached_to_name,
+        is_private=is_private,
+    )
+
+
+@mcp.tool()
+async def upload_file_from_url(
+    file_url: str,
+    filename: str | None = None,
+    attached_to_doctype: str | None = None,
+    attached_to_name: str | None = None,
+    is_private: bool = True,
+) -> dict:
+    """Upload a file to ERPNext from a URL.
+
+    Args:
+        file_url: Source URL to fetch the file from
+        filename: Optional name for the file (will be inferred from URL if not provided)
+        attached_to_doctype: Optional DocType to attach file to
+        attached_to_name: Optional document name to attach file to
+        is_private: Whether file should be private (default True)
+
+    Returns:
+        File document with file_url and other metadata
+    """
+    return await get_client().upload_file_from_url(
+        file_url=file_url,
+        filename=filename,
+        attached_to_doctype=attached_to_doctype,
+        attached_to_name=attached_to_name,
+        is_private=is_private,
+    )
+
+
+@mcp.tool()
+async def list_files(
+    attached_to_doctype: str | None = None,
+    attached_to_name: str | None = None,
+    is_private: bool | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """List files in ERPNext, optionally filtered by attachment.
+
+    Args:
+        attached_to_doctype: Filter by DocType (e.g. "Project", "Item")
+        attached_to_name: Filter by document name (e.g. "PROJ-0001")
+        is_private: Filter by privacy (True=private, False=public, None=all)
+        limit: Max number of files to return (default 20)
+
+    Returns:
+        List of File documents with name, file_name, file_url, file_size, etc.
+    """
+    return await get_client().list_files(
+        attached_to_doctype=attached_to_doctype,
+        attached_to_name=attached_to_name,
+        is_private=is_private,
+        limit=limit,
+    )
+
+
+@mcp.tool()
+async def get_file_url(file_name: str) -> str:
+    """Get the full download URL for a file.
+
+    Args:
+        file_name: The File document name (e.g. "abc123.pdf" or the hash-based name)
+
+    Returns:
+        Full URL to download the file
+    """
+    return await get_client().get_file_url(file_name)
+
+
+@mcp.tool()
+async def download_file(file_name: str) -> dict:
+    """Download a file's content from ERPNext.
+
+    Args:
+        file_name: The File document name
+
+    Returns:
+        Dict with 'content_base64' (file content as base64) and 'filename' (original filename)
+    """
+    import base64
+    content, filename = await get_client().download_file(file_name)
+    return {
+        "content_base64": base64.b64encode(content).decode("utf-8"),
+        "filename": filename,
+    }
+
+
+# ── Supplier/Customer Details ──────────────────────────
+
+
+@mcp.tool()
+async def get_supplier_details(name: str | None = None, keyword: str | None = None) -> dict:
+    """Get complete supplier details including address, phone, and contacts.
+
+    Args:
+        name: Exact supplier name (e.g. "SF0009-2 - 永心企業社")
+        keyword: Search keyword to find supplier (e.g. "永心")
+
+    Returns:
+        Dict with supplier info, address (phone/fax), and contacts (our purchaser + their contacts)
+    """
+    client = get_client()
+
+    # Find supplier
+    if name:
+        supplier = await client.get_doc("Supplier", name)
+    elif keyword:
+        suppliers = await client.get_list(
+            "Supplier",
+            fields=["name", "supplier_name", "supplier_group", "country"],
+            filters={"name": ["like", f"%{keyword}%"]},
+            limit_page_length=1,
+        )
+        if not suppliers:
+            return {"error": f"找不到關鍵字「{keyword}」的供應商"}
+        supplier = await client.get_doc("Supplier", suppliers[0]["name"])
+    else:
+        return {"error": "請提供 name 或 keyword"}
+
+    supplier_name = supplier.get("name")
+
+    # Get address (phone/fax)
+    # Address title format: "代碼 地址", e.g. "SF0009-2 地址"
+    code = supplier_name.split(" - ")[0] if " - " in supplier_name else supplier_name
+    addresses = await client.get_list(
+        "Address",
+        fields=["address_title", "address_line1", "city", "pincode", "phone", "fax"],
+        filters={"address_title": ["like", f"%{code}%"]},
+        limit_page_length=5,
+    )
+
+    # Get contacts via Dynamic Link
+    contacts = await client.get_list(
+        "Contact",
+        fields=["name", "first_name", "designation", "phone", "mobile_no", "email_id"],
+        filters=[["Dynamic Link", "link_name", "=", supplier_name]],
+        limit_page_length=50,
+    )
+
+    # Categorize contacts
+    # 有 designation 的是我們的人（採購人員/業務人員），沒有的是對方的聯絡人
+    our_contacts = []
+    their_contacts = []
+    for c in contacts:
+        contact_info = {
+            "name": c.get("first_name") or c.get("name"),
+            "designation": c.get("designation") or "",
+            "phone": c.get("phone") or c.get("mobile_no") or "",
+            "email": c.get("email_id") or "",
+        }
+        if c.get("designation"):
+            our_contacts.append(contact_info)
+        else:
+            their_contacts.append(contact_info)
+
+    return {
+        "supplier": {
+            "name": supplier_name,
+            "group": supplier.get("supplier_group"),
+            "country": supplier.get("country"),
+            "currency": supplier.get("default_currency"),
+        },
+        "address": addresses[0] if addresses else None,
+        "our_contacts": our_contacts,
+        "their_contacts": their_contacts,
+    }
+
+
+@mcp.tool()
+async def get_customer_details(name: str | None = None, keyword: str | None = None) -> dict:
+    """Get complete customer details including address, phone, and contacts.
+
+    Args:
+        name: Exact customer name (e.g. "CM0001 - 正達工程股份有限公司")
+        keyword: Search keyword to find customer (e.g. "正達")
+
+    Returns:
+        Dict with customer info, address (phone/fax), and contacts (our sales + their contacts)
+    """
+    client = get_client()
+
+    # Find customer
+    if name:
+        customer = await client.get_doc("Customer", name)
+    elif keyword:
+        customers = await client.get_list(
+            "Customer",
+            fields=["name", "customer_name", "customer_group", "territory"],
+            filters={"name": ["like", f"%{keyword}%"]},
+            limit_page_length=1,
+        )
+        if not customers:
+            return {"error": f"找不到關鍵字「{keyword}」的客戶"}
+        customer = await client.get_doc("Customer", customers[0]["name"])
+    else:
+        return {"error": "請提供 name 或 keyword"}
+
+    customer_name = customer.get("name")
+
+    # Get address (phone/fax)
+    code = customer_name.split(" - ")[0] if " - " in customer_name else customer_name
+    addresses = await client.get_list(
+        "Address",
+        fields=["address_title", "address_line1", "city", "pincode", "phone", "fax"],
+        filters={"address_title": ["like", f"%{code}%"]},
+        limit_page_length=5,
+    )
+
+    # Get contacts via Dynamic Link
+    contacts = await client.get_list(
+        "Contact",
+        fields=["name", "first_name", "designation", "phone", "mobile_no", "email_id"],
+        filters=[["Dynamic Link", "link_name", "=", customer_name]],
+        limit_page_length=50,
+    )
+
+    # Categorize contacts
+    # 有 designation 的是我們的人（採購人員/業務人員），沒有的是對方的聯絡人
+    our_contacts = []
+    their_contacts = []
+    for c in contacts:
+        contact_info = {
+            "name": c.get("first_name") or c.get("name"),
+            "designation": c.get("designation") or "",
+            "phone": c.get("phone") or c.get("mobile_no") or "",
+            "email": c.get("email_id") or "",
+        }
+        if c.get("designation"):
+            our_contacts.append(contact_info)
+        else:
+            their_contacts.append(contact_info)
+
+    return {
+        "customer": {
+            "name": customer_name,
+            "group": customer.get("customer_group"),
+            "territory": customer.get("territory"),
+            "currency": customer.get("default_currency"),
+        },
+        "address": addresses[0] if addresses else None,
+        "our_contacts": our_contacts,
+        "their_contacts": their_contacts,
+    }
+
+
 def main():
     mcp.run()
 

{erpnext_mcp-0.1.0.dist-info → erpnext_mcp-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erpnext-mcp
-Version: 0.1.0
+Version: 0.3.0
 Summary: MCP Server for ERPNext REST API
 Project-URL: Homepage, https://github.com/ching-tech/erpnext-mcp
 Project-URL: Repository, https://github.com/ching-tech/erpnext-mcp

erpnext_mcp-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+erpnext_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+erpnext_mcp/client.py,sha256=wX71XIi6DO2tVyKcP82NIiC50CE-BxqjglAraERPjsA,13582
+erpnext_mcp/server.py,sha256=e7Zymn6kQ-Vd3Mtu6c1gRtKcsb_gLLl3DL_e1t1MArw,19757
+erpnext_mcp/types.py,sha256=MC7H3f1BgpvIbWDwXSv1uFwH8nTD0BMiiqnHypsutk8,643
+erpnext_mcp-0.3.0.dist-info/METADATA,sha256=xdLBhOwN7eVB5ngCexvN_OJISuisg_MgigCY_v_VxKg,5119
+erpnext_mcp-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+erpnext_mcp-0.3.0.dist-info/entry_points.txt,sha256=AbRXtSJhFq6PLmqKjNYkFjcKFjQwvkiTI8QAhqqAsps,56
+erpnext_mcp-0.3.0.dist-info/licenses/LICENSE,sha256=M_cHb60t6PxhBL25Y_hbvWe8WaUxG1y5xh5qoWNIlYU,1067
+erpnext_mcp-0.3.0.dist-info/RECORD,,

erpnext_mcp-0.1.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-erpnext_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-erpnext_mcp/client.py,sha256=TqkXXrTDiFXe6Py2E5BQNMsjlJ_I_ScmuCZjnE7nBkE,7923
-erpnext_mcp/server.py,sha256=G1kak-VkrevAKRvB5TmzdG8pE2oP_PfQZlXyPvcqVjQ,10372
-erpnext_mcp/types.py,sha256=MC7H3f1BgpvIbWDwXSv1uFwH8nTD0BMiiqnHypsutk8,643
-erpnext_mcp-0.1.0.dist-info/METADATA,sha256=mu7E_t0WIutfRRocWDyeeoJoeXBXFJteNUXRDc8-uyo,5119
-erpnext_mcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-erpnext_mcp-0.1.0.dist-info/entry_points.txt,sha256=AbRXtSJhFq6PLmqKjNYkFjcKFjQwvkiTI8QAhqqAsps,56
-erpnext_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=M_cHb60t6PxhBL25Y_hbvWe8WaUxG1y5xh5qoWNIlYU,1067
-erpnext_mcp-0.1.0.dist-info/RECORD,,