erpnext-mcp 0.1.0__tar.gz → 0.2.0__tar.gz

{erpnext_mcp-0.1.0 → erpnext_mcp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erpnext-mcp
-Version: 0.1.0
+Version: 0.2.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.1.0 → erpnext_mcp-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "erpnext-mcp"
-version = "0.1.0"
+version = "0.2.0"
 description = "MCP Server for ERPNext REST API"
 readme = "README.md"
 license = {file = "LICENSE"}

{erpnext_mcp-0.1.0 → erpnext_mcp-0.2.0}/src/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-0.1.0 → erpnext_mcp-0.2.0}/src/erpnext_mcp/server.py

@@ -310,6 +310,126 @@ 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,
+    }
+
+
 def main():
     mcp.run()
 

{erpnext_mcp-0.1.0 → erpnext_mcp-0.2.0}/tests/test_integration.py

@@ -59,6 +59,10 @@ class State:
     so_name: str = ""
     dn_name: str = ""  # Delivery Note
     si_name: str = ""  # Sales Invoice
+    # File operations
+    test_file_name: str = ""
+    attached_file_name: str = ""
+    server_test_file_name: str = ""
 
 
 state = State()
@@ -457,6 +461,107 @@ class TestPhase5ServerTools:
         assert isinstance(result, list)
 
 
+# ── Phase 5.5: File Operations ──────────────────────────
+
+@pytest.mark.asyncio(loop_scope="module")
+class TestPhase5_5FileOperations:
+    """Test file upload, list, download operations."""
+
+    async def test_01_upload_file(self, client: ERPNextClient):
+        """上傳測試檔案"""
+        test_content = b"Hello from MCP test!"
+        result = await client.upload_file(
+            file_content=test_content,
+            filename=f"{PREFIX}test_file.txt",
+            is_private=True,
+        )
+        state.test_file_name = result.get("name", "")
+        assert result.get("file_name") == f"{PREFIX}test_file.txt"
+        assert result.get("file_url")
+
+    async def test_02_upload_file_attached(self, client: ERPNextClient):
+        """上傳附加到 Item 的檔案（需要先執行 Phase 1 建立 Item）"""
+        if not state.item_code:
+            pytest.skip("Requires item_code from Phase 1")
+        test_content = b"Attached file content"
+        result = await client.upload_file(
+            file_content=test_content,
+            filename=f"{PREFIX}attached_file.txt",
+            attached_to_doctype="Item",
+            attached_to_name=state.item_code,
+            is_private=True,
+        )
+        state.attached_file_name = result.get("name", "")
+        assert result.get("attached_to_doctype") == "Item"
+        assert result.get("attached_to_name") == state.item_code
+
+    async def test_03_list_files(self, client: ERPNextClient):
+        """列出檔案"""
+        files = await client.list_files(limit=10)
+        assert isinstance(files, list)
+        # 應該能找到我們上傳的檔案
+        file_names = [f.get("file_name", "") for f in files]
+        assert any(PREFIX in name for name in file_names)
+
+    async def test_04_list_files_attached(self, client: ERPNextClient):
+        """列出附加到 Item 的檔案（需要先執行 test_02）"""
+        if not state.attached_file_name:
+            pytest.skip("Requires attached_file from test_02")
+        files = await client.list_files(
+            attached_to_doctype="Item",
+            attached_to_name=state.item_code,
+        )
+        assert len(files) >= 1
+        assert any(f.get("file_name", "").startswith(PREFIX) for f in files)
+
+    async def test_05_get_file_url(self, client: ERPNextClient):
+        """取得檔案 URL"""
+        url = await client.get_file_url(state.test_file_name)
+        assert url
+        assert "http" in url or url.startswith("/")
+
+    async def test_06_download_file(self, client: ERPNextClient):
+        """下載檔案"""
+        content, filename = await client.download_file(state.test_file_name)
+        assert content == b"Hello from MCP test!"
+        assert PREFIX in filename
+
+    async def test_07_server_upload_file_tool(self):
+        """測試 server 層的 upload_file 工具"""
+        import base64
+        test_content = base64.b64encode(b"Server tool test").decode()
+        result = await srv.upload_file.fn(
+            file_content_base64=test_content,
+            filename=f"{PREFIX}server_test.txt",
+        )
+        state.server_test_file_name = result.get("name", "")
+        assert result.get("file_name") == f"{PREFIX}server_test.txt"
+
+    async def test_08_server_list_files_tool(self):
+        """測試 server 層的 list_files 工具"""
+        result = await srv.list_files.fn(limit=10)
+        assert isinstance(result, list)
+
+    async def test_09_server_download_file_tool(self):
+        """測試 server 層的 download_file 工具"""
+        result = await srv.download_file.fn(state.server_test_file_name)
+        assert result.get("content_base64")
+        assert result.get("filename")
+
+    async def test_10_cleanup_files(self, client: ERPNextClient):
+        """清理測試檔案"""
+        for file_name in [
+            getattr(state, "test_file_name", ""),
+            getattr(state, "attached_file_name", ""),
+            getattr(state, "server_test_file_name", ""),
+        ]:
+            if file_name:
+                try:
+                    await client.delete_doc("File", file_name)
+                except Exception:
+                    pass
+
+
 # ── Phase 6: Cleanup ────────────────────────────────────
 
 @pytest.mark.asyncio(loop_scope="module")