erpnext-mcp 0.1.0__tar.gz

erpnext_mcp-0.1.0/.env.example

@@ -0,0 +1,3 @@
+ERPNEXT_URL=http://your-erpnext-site.com
+ERPNEXT_API_KEY=your_api_key
+ERPNEXT_API_SECRET=your_api_secret

erpnext_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

erpnext_mcp-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# Environment variables
+.env
+
+# UV
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo

erpnext_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,23 @@
+# ERPNext MCP Server
+
+## Run
+```bash
+cd /home/ct/SDD/erpnext-mcp
+set -a && source .env && set +a && uv run erpnext-mcp
+```
+
+## Structure
+- `src/erpnext_mcp/server.py` - MCP tool definitions (fastmcp)
+- `src/erpnext_mcp/client.py` - ERPNext REST API client (httpx async)
+- `src/erpnext_mcp/types.py` - Pydantic models
+
+## Auth
+Uses `Authorization: token {api_key}:{api_secret}` header. Set `ERPNEXT_API_KEY` and `ERPNEXT_API_SECRET` in `.env`.
+
+## Docs
+- `docs/api-reference.md` - 19 個 MCP tool 的參數、型別與範例
+- `docs/testing.md` - 整合測試說明（43 項測試、執行方式、Phase 結構）
+- `docs/development-notes.md` - 開發記錄（問題與解決方案、環境資訊）
+
+## Adding Tools
+Add `@mcp.tool()` decorated async functions in `server.py`. Use `get_client()` for API calls. Filter/data params accept JSON strings to stay MCP-compatible.

erpnext_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ching-Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

erpnext_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: erpnext-mcp
+Version: 0.1.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
+Project-URL: Issues, https://github.com/ching-tech/erpnext-mcp/issues
+Author: Ching-Tech
+License: MIT License
+        
+        Copyright (c) 2025 Ching-Tech
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,erp,erpnext,frappe,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+# ERPNext MCP Server
+
+MCP (Model Context Protocol) server for ERPNext REST API, built with [FastMCP](https://github.com/jlowin/fastmcp) and Python.
+
+## Features
+
+- **CRUD** — List, get, create, update, delete documents
+- **Workflow** — Submit and cancel submittable documents
+- **Reports** — Run ERPNext query reports
+- **Schema** — Inspect DocType field definitions, list all DocTypes
+- **Inventory** — Stock balance, stock ledger, item prices
+- **Trading** — Document conversion (e.g. Quotation → Sales Order), party balance
+- **Helpers** — Link search (autocomplete), document count, generic method calls
+
+## Requirements
+
+- Python >= 3.11
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- ERPNext instance with API key/secret
+
+## Setup
+
+```bash
+# Clone the repo
+git clone <repo-url> && cd erpnext-mcp
+
+# Create .env file
+cat > .env << 'EOF'
+ERPNEXT_URL=https://your-erpnext-instance.com
+ERPNEXT_API_KEY=your_api_key
+ERPNEXT_API_SECRET=your_api_secret
+EOF
+
+# Install dependencies
+uv sync
+```
+
+## Run
+
+```bash
+set -a && source .env && set +a && uv run erpnext-mcp
+```
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `list_documents` | List documents with filters, sorting, pagination |
+| `get_document` | Get a single document by name |
+| `create_document` | Create a new document |
+| `update_document` | Update an existing document |
+| `delete_document` | Delete a document |
+| `submit_document` | Submit a submittable document |
+| `cancel_document` | Cancel a submitted document |
+| `run_report` | Execute an ERPNext report |
+| `get_count` | Get document count with optional filters |
+| `get_list_with_summary` | List documents with total count |
+| `run_method` | Call any whitelisted server-side method |
+| `search_link` | Link field autocomplete search |
+| `list_doctypes` | List all available DocType names |
+| `get_doctype_meta` | Get field definitions for a DocType |
+| `get_stock_balance` | Real-time stock balance from Bin |
+| `get_stock_ledger` | Stock ledger entries (inventory history) |
+| `get_item_price` | Item prices from price lists |
+| `make_mapped_doc` | Document conversion (e.g. SO → DN) |
+| `get_party_balance` | Outstanding balance for Customer/Supplier |
+
+## MCP Client Configuration
+
+Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "erpnext": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/erpnext-mcp", "run", "erpnext-mcp"],
+      "env": {
+        "ERPNEXT_URL": "https://your-erpnext-instance.com",
+        "ERPNEXT_API_KEY": "your_api_key",
+        "ERPNEXT_API_SECRET": "your_api_secret"
+      }
+    }
+  }
+}
+```
+
+## Project Structure
+
+```
+src/erpnext_mcp/
+├── server.py   # MCP tool definitions (FastMCP)
+├── client.py   # ERPNext REST API client (httpx async)
+└── types.py    # Pydantic models
+```
+
+## License
+
+MIT

erpnext_mcp-0.1.0/README.md

@@ -0,0 +1,99 @@
+# ERPNext MCP Server
+
+MCP (Model Context Protocol) server for ERPNext REST API, built with [FastMCP](https://github.com/jlowin/fastmcp) and Python.
+
+## Features
+
+- **CRUD** — List, get, create, update, delete documents
+- **Workflow** — Submit and cancel submittable documents
+- **Reports** — Run ERPNext query reports
+- **Schema** — Inspect DocType field definitions, list all DocTypes
+- **Inventory** — Stock balance, stock ledger, item prices
+- **Trading** — Document conversion (e.g. Quotation → Sales Order), party balance
+- **Helpers** — Link search (autocomplete), document count, generic method calls
+
+## Requirements
+
+- Python >= 3.11
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- ERPNext instance with API key/secret
+
+## Setup
+
+```bash
+# Clone the repo
+git clone <repo-url> && cd erpnext-mcp
+
+# Create .env file
+cat > .env << 'EOF'
+ERPNEXT_URL=https://your-erpnext-instance.com
+ERPNEXT_API_KEY=your_api_key
+ERPNEXT_API_SECRET=your_api_secret
+EOF
+
+# Install dependencies
+uv sync
+```
+
+## Run
+
+```bash
+set -a && source .env && set +a && uv run erpnext-mcp
+```
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `list_documents` | List documents with filters, sorting, pagination |
+| `get_document` | Get a single document by name |
+| `create_document` | Create a new document |
+| `update_document` | Update an existing document |
+| `delete_document` | Delete a document |
+| `submit_document` | Submit a submittable document |
+| `cancel_document` | Cancel a submitted document |
+| `run_report` | Execute an ERPNext report |
+| `get_count` | Get document count with optional filters |
+| `get_list_with_summary` | List documents with total count |
+| `run_method` | Call any whitelisted server-side method |
+| `search_link` | Link field autocomplete search |
+| `list_doctypes` | List all available DocType names |
+| `get_doctype_meta` | Get field definitions for a DocType |
+| `get_stock_balance` | Real-time stock balance from Bin |
+| `get_stock_ledger` | Stock ledger entries (inventory history) |
+| `get_item_price` | Item prices from price lists |
+| `make_mapped_doc` | Document conversion (e.g. SO → DN) |
+| `get_party_balance` | Outstanding balance for Customer/Supplier |
+
+## MCP Client Configuration
+
+Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "erpnext": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/erpnext-mcp", "run", "erpnext-mcp"],
+      "env": {
+        "ERPNEXT_URL": "https://your-erpnext-instance.com",
+        "ERPNEXT_API_KEY": "your_api_key",
+        "ERPNEXT_API_SECRET": "your_api_secret"
+      }
+    }
+  }
+}
+```
+
+## Project Structure
+
+```
+src/erpnext_mcp/
+├── server.py   # MCP tool definitions (FastMCP)
+├── client.py   # ERPNext REST API client (httpx async)
+└── types.py    # Pydantic models
+```
+
+## License
+
+MIT

erpnext_mcp-0.1.0/docs/api-reference.md

@@ -0,0 +1,303 @@
+# MCP Tool API 參考
+
+ERPNext MCP Server 提供 19 個工具，分為 CRUD、報表、工作流、輔助、庫存交易五大類。
+
+---
+
+## CRUD
+
+### list_documents
+
+列出指定 DocType 的文件清單。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱，如 `"Sales Order"` |
+| fields | list[str] | N | 回傳欄位，預設 `["name"]` |
+| filters | str | N | JSON 篩選條件，如 `'{"status": "Open"}'` 或 `'[["status","=","Open"]]'` |
+| or_filters | str | N | JSON OR 篩選條件 |
+| order_by | str | N | 排序，如 `"creation desc"` |
+| limit_start | int | N | 分頁起始（預設 0） |
+| limit_page_length | int | N | 回傳筆數（預設 20，最大 100） |
+
+```json
+// 範例
+{"doctype": "Customer", "fields": ["name", "customer_name"], "filters": "{\"customer_type\": \"Individual\"}", "limit_page_length": 10}
+```
+
+---
+
+### get_document
+
+取得單一文件。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| name | str | Y | 文件名稱/ID |
+| fields | list[str] | N | 指定回傳欄位 |
+
+```json
+{"doctype": "Sales Order", "name": "SO-00001", "fields": ["name", "status", "grand_total"]}
+```
+
+---
+
+### create_document
+
+建立新文件。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| data | str | Y | JSON 字串，欄位值 |
+
+```json
+{"doctype": "Customer", "data": "{\"customer_name\": \"Test Customer\", \"customer_type\": \"Individual\", \"customer_group\": \"All Customer Groups\", \"territory\": \"All Territories\"}"}
+```
+
+含子表（child table）範例：
+```json
+{"doctype": "Sales Order", "data": "{\"customer\": \"CUST-001\", \"company\": \"My Company\", \"delivery_date\": \"2025-12-31\", \"items\": [{\"item_code\": \"ITEM-001\", \"qty\": 10, \"rate\": 100}]}"}
+```
+
+---
+
+### update_document
+
+更新現有文件。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| name | str | Y | 文件名稱/ID |
+| data | str | Y | JSON 字串，要更新的欄位 |
+
+```json
+{"doctype": "Sales Order", "name": "SO-00001", "data": "{\"delivery_date\": \"2025-12-31\"}"}
+```
+
+---
+
+### delete_document
+
+刪除文件。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| name | str | Y | 文件名稱/ID |
+
+```json
+{"doctype": "Customer", "name": "CUST-001"}
+```
+
+---
+
+## 報表
+
+### run_report
+
+執行 ERPNext 報表。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| report_name | str | Y | 報表名稱，如 `"Stock Balance"` |
+| filters | str | N | JSON 篩選條件 |
+
+```json
+{"report_name": "Stock Balance", "filters": "{\"company\": \"擎添工業有限公司\"}"}
+```
+
+---
+
+### get_count
+
+取得文件計數。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| filters | str | N | JSON 篩選條件 |
+
+```json
+{"doctype": "Sales Invoice", "filters": "{\"status\": \"Unpaid\"}"}
+```
+
+---
+
+### get_list_with_summary
+
+列出文件並附帶總筆數。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| fields | list[str] | N | 回傳欄位 |
+| filters | str | N | JSON 篩選條件 |
+| order_by | str | N | 排序 |
+| limit_page_length | int | N | 回傳筆數（預設 20） |
+
+回傳格式：`{"data": [...], "total_count": 123}`
+
+---
+
+## 工作流
+
+### submit_document
+
+提交可提交的文件（docstatus 0→1）。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| name | str | Y | 文件名稱/ID |
+
+```json
+{"doctype": "Sales Invoice", "name": "SINV-00001"}
+```
+
+---
+
+### cancel_document
+
+取消已提交的文件（docstatus 1→2）。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+| name | str | Y | 文件名稱/ID |
+
+---
+
+### run_method
+
+呼叫 ERPNext 白名單方法。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| method | str | Y | 方法路徑，如 `"frappe.client.get_count"` |
+| http_method | str | N | `"GET"` 或 `"POST"`（預設 POST） |
+| args | str | N | JSON 字串，關鍵字參數 |
+
+```json
+{"method": "frappe.client.get_count", "http_method": "GET", "args": "{\"doctype\": \"Customer\"}"}
+```
+
+---
+
+## 輔助
+
+### list_doctypes
+
+列出可用的 DocType 名稱。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| module | str | N | 模組篩選，如 `"Selling"`, `"Stock"`, `"Accounts"` |
+| is_submittable | bool | N | 只列出可提交的 DocType |
+| limit | int | N | 最大筆數（預設 100） |
+
+---
+
+### search_link
+
+連結欄位搜尋（自動完成）。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | 目標 DocType |
+| txt | str | Y | 搜尋文字 |
+| filters | str | N | JSON 篩選條件 |
+| page_length | int | N | 最大筆數（預設 20） |
+
+---
+
+### get_doctype_meta
+
+取得 DocType 的欄位定義。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| doctype | str | Y | DocType 名稱 |
+
+回傳欄位：`fieldname`, `fieldtype`, `label`, `reqd`, `options`
+
+---
+
+## 庫存與交易
+
+### get_stock_balance
+
+從 Bin 表取得即時庫存餘額。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| item_code | str | N | 品項代碼 |
+| warehouse | str | N | 倉庫 |
+
+回傳欄位：`item_code`, `warehouse`, `actual_qty`, `reserved_qty`, `ordered_qty`, `projected_qty`
+
+---
+
+### get_item_price
+
+查詢品項價格。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| item_code | str | Y | 品項代碼 |
+| price_list | str | N | 價格表名稱，如 `"Standard Selling"` |
+
+回傳欄位：`item_code`, `price_list`, `price_list_rate`, `currency`, `uom`
+
+---
+
+### make_mapped_doc
+
+從現有文件轉換建立新文件（文件轉換）。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| method | str | Y | 轉換方法路徑 |
+| source_name | str | Y | 來源文件名稱/ID |
+
+常用轉換方法：
+
+| 方法 | 轉換 |
+|------|------|
+| `erpnext.selling.doctype.quotation.quotation.make_sales_order` | 報價單 → 銷售單 |
+| `erpnext.selling.doctype.sales_order.sales_order.make_delivery_note` | 銷售單 → 出貨單 |
+| `erpnext.selling.doctype.sales_order.sales_order.make_sales_invoice` | 銷售單 → 銷售發票 |
+| `erpnext.stock.doctype.delivery_note.delivery_note.make_sales_invoice` | 出貨單 → 銷售發票 |
+| `erpnext.buying.doctype.purchase_order.purchase_order.make_purchase_receipt` | 採購單 → 入庫單 |
+| `erpnext.buying.doctype.purchase_order.purchase_order.make_purchase_invoice` | 採購單 → 採購發票 |
+
+回傳 draft 文件 JSON，可修改後用 `create_document` 建立再 `submit_document` 提交。
+
+---
+
+### get_party_balance
+
+查詢客戶或供應商的未結餘額。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| party_type | str | Y | `"Customer"` 或 `"Supplier"` |
+| party | str | Y | 對象名稱/ID |
+
+---
+
+### get_stock_ledger
+
+查詢庫存異動記錄。
+
+| 參數 | 型別 | 必填 | 說明 |
+|------|------|------|------|
+| item_code | str | N | 品項代碼 |
+| warehouse | str | N | 倉庫 |
+| limit | int | N | 最大筆數（預設 50） |
+
+回傳欄位：`item_code`, `warehouse`, `posting_date`, `qty_after_transaction`, `actual_qty`, `voucher_type`, `voucher_no`
+
+結果按 `posting_date desc, posting_time desc` 排序。