# Paperware MCP Server (`paperware_mcp`)

Paperware Factory (`erp.paperwarefactory.com`)-এর ERPNext/Frappe bench-এর জন্য একটি Native **Model Context Protocol (MCP) Server**।

এই অ্যাপটি **Prime AI Agent** (NousResearch Hermes Agent framework, "Prime" persona, Docker/Coolify-তে হোস্ট করা)-কে সরাসরি Frappe ORM ব্যবহার করে ERPNext-এর সাথে যোগাযোগ করতে সক্ষম করে। 

---

## 🌟 মূল বৈশিষ্ট্য (Key Features)

1. **Direct Frappe ORM Integration**: কোনো বাইরের HTTP REST API কল বা API Key/Secret লাগে না। সরাসরি `frappe.get_doc`, `frappe.get_list`, `doc.insert()`, `doc.submit()`, `doc.cancel()` ইত্যাদি ব্যবহার হয়।
2. **Per-Request Permission Impersonation**: প্রতিটা টুল কলের সময়ে `requesting_user` параметр অনুযায়ী `frappe.set_user()` সম্পন্ন হয় এবং আসল Frappe permission engine কার্যকর হয়।
3. **Whitelisted Execution Security**: `call_method` টুলটি শুধুমাত্র `@frappe.whitelist()` ডেকোরেটরযুক্ত ফাংশন চালাতে পারে। অননুমোদিত Python code execution সম্পূর্ণ সুরক্ষিত ও অবরুদ্ধ।
4. **FastMCP Integration**: Python `mcp>=1.9.0,<2.0.0` প্যাকেজের `FastMCP` ভিত্তিক টুল সেটআপ। `stdio` এবং `sse` দুটো ট্রান্সপোর্ট সুবিধা বিদ্যমান।
5. **Native Bench Command**: Frappe CLI-এর সাথে যুক্ত — `bench --site erp.paperwarefactory.com paperware-mcp` কমান্ডের মাধ্যমে সার্ভিস শুরু করা যায়।

---

## 🛠️ ইনস্টলেশন গাইড (Step-by-Step Installation)

### ধাপ ১: অ্যাপ সোর্স স্থাপন
আপনার Frappe Bench ডিরেক্টরিতে (`/home/prime/frappe-bench/`) গিয়ে নিশ্চিত করুন অ্যাপটি `apps/paperware_mcp` ফোল্ডারে উপস্থিত রয়েছে।

```bash
cd /home/prime/frappe-bench
```

### ধাপ ২: Python Dependencies ইনস্টল
Bench Virtual Environment-এ আবশ্যকীয় packages (`mcp>=1.9.0,<2.0.0`) ইনস্টল করুন:

```bash
./env/bin/pip install -r apps/paperware_mcp/requirements.txt
```

### ধাপ ৩: ERPNext সাইটে অ্যাপ ইনস্টল
আপনার কাঙ্ক্ষিত সাইটে `paperware_mcp` অ্যাপটি ইনস্টল করুন:

```bash
bench --site erp.paperwarefactory.com install-app paperware_mcp
```

---

## 🚀 সার্ভিস রান ও কমান্ড ইউসেজ (Usage & Command Options)

`paperware-mcp` CLI কমান্ডটি রান করার জন্য নিচের অপশনগুলো ব্যবহার করা যায়:

| Option | Type | Default | বিবরণ |
|---|---|---|---|
| `--transport` | `stdio` \| `sse` | `stdio` | MCP কাস্টম ট্রান্সপোর্ট অপশন। |
| `--port` | `int` | `8931` | SSE ট্রান্সপোর্টের জন্য পোর্ট নম্বর (শুধু `--transport sse` হলে প্রযোজ্য)। |
| `--default-user` | `string` | `None` | `requesting_user` না দিলে ফলব্যাক ফ্রেপ ব্যবহারকারীর ইমেইল। |

> [!WARNING]
> `--default-user Administrator` প্রোডাকশনে ব্যবহার করা উচিত নয়। প্রোডাকশনে অবশ্যই একটি নির্দিষ্ট বট ব্যবহারকারীর ইমেইল পাস করুন।

### কমান্ড উদাহরণ:

#### ১. Standard Input/Output (stdio) মোডে চালানো:
```bash
bench --site erp.paperwarefactory.com paperware-mcp --transport stdio --default-user hermes.bot@paperwarefactory.com
```

#### ২. Server-Sent Events (SSE) মোডে নির্দিষ্ট পোটে চালানো:
```bash
bench --site erp.paperwarefactory.com paperware-mcp --transport sse --port 8931 --default-user hermes.bot@paperwarefactory.com
```

---

## 🛡️ ডেডিকেটেড Hermes Bot ব্যবহারকারী তৈরি (Security Best Practices)

প্রোডাকশন পরিবেশে কাজ করার জন্য ERPNext এ একটি নির্দিষ্ট Bot User তৈরি করার সুপারিশ করা হচ্ছে:

1. ERPNext Desk-এ **User List**-এ গিয়ে **New User** ক্রিয়েট করুন।
2. **Email**: `hermes.bot@paperwarefactory.com`
3. **First Name**: `Hermes Bot`
4. **Role Profile**: শুধু প্রয়োজনীয় রোল প্রদান করুন (যেমন: *Stock User*, *Sales User*, *Accounts User*) যাতে Hermes Agent অপ্রয়োজনীয় প্রশাসনিক পাওয়ার না পায়।
5. সার্ভার শুরু করার সময় `--default-user hermes.bot@paperwarefactory.com` ফ্ল্যাগ ব্যবহার করুন।

---

## 🏭 প্রোডাকশন ডিপ্লয়মেন্ট (Production Deployment)

সার্ভিসটি ব্যাকগ্রাউন্ডে স্বয়ংক্রিয়ভাবে চালু ও সচল রাখার জন্য Supervisor অথবা Systemd সার্ভিস ব্যবহার করুন।

### পদ্ধতি ১: Supervisor Configuration (সুপারভাইজার কনফিগারেশন)

`/etc/supervisor/conf.d/paperware_mcp.conf` ফাইল তৈরি করে নিচের কোডটি লিখুন:

```ini
[program:paperware-mcp]
command=/home/prime/frappe-bench/env/bin/bench --site erp.paperwarefactory.com paperware-mcp --transport sse --port 8931 --default-user hermes.bot@paperwarefactory.com
directory=/home/prime/frappe-bench
user=prime
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stdout_logfile=/home/prime/frappe-bench/logs/paperware_mcp.out.log
stderr_logfile=/home/prime/frappe-bench/logs/paperware_mcp.err.log
environment=PATH="/home/prime/frappe-bench/env/bin:%(ENV_PATH)s"
```

কনফিগারেশন রিলোড ও স্টার্ট করুন:
```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status paperware-mcp
```

---

### পদ্ধতি ২: Systemd Unit Configuration (সিস্টেমডি সার্ভিস)

`/etc/systemd/system/paperware-mcp.service` ফাইল তৈরি করে নিচের কনফিগারেশন দিন:

```ini
[Unit]
Description=Paperware MCP Server for Hermes AI Agent
After=network.target redis-server.service mariadb.service

[Service]
Type=simple
User=prime
WorkingDirectory=/home/prime/frappe-bench
ExecStart=/home/prime/frappe-bench/env/bin/bench --site erp.paperwarefactory.com paperware-mcp --transport sse --port 8931 --default-user hermes.bot@paperwarefactory.com
Restart=always
RestartSec=5
StandardOutput=append:/home/prime/frappe-bench/logs/paperware_mcp.out.log
StandardError=append:/home/prime/frappe-bench/logs/paperware_mcp.err.log

[Install]
WantedBy=multi-user.target
```

সার্ভিস এনাবল ও চালু করুন:
```bash
sudo systemctl daemon-reload
sudo systemctl enable paperware-mcp
sudo systemctl start paperware-mcp
sudo systemctl status paperware-mcp
```

---

## 🤖 Hermes Agent MCP Client Config (হার্মিস এজেন্ট কনফিগারেশন)

Hermes Agent (বা যেকোনো MCP Client)-এর `mcp_config.json` ফাইলে `paperware_mcp` যোগ করার নিয়ম:

### ১. SSE Transport-এর জন্য (ডকার/রিমোট কানেকশনের জন্য প্রস্তাবিত):

```json
{
  "mcpServers": {
    "paperware_mcp": {
      "url": "http://erp.paperwarefactory.com:8931/sse"
    }
  }
}
```

### ২. Stdio Transport-এর জন্য (একই কনটেইনার/লোকাল এক্সিকিউশনের ক্ষেত্রে):

```json
{
  "mcpServers": {
    "paperware_mcp": {
      "command": "/home/prime/frappe-bench/env/bin/bench",
      "args": [
        "--site",
        "erp.paperwarefactory.com",
        "paperware-mcp",
        "--transport",
        "stdio",
        "--default-user",
        "hermes.bot@paperwarefactory.com"
      ]
    }
  }
}
```

---

## 📦 মোট টুলস সমূহ (Exposed MCP Tools - 15 Tools)

| Tool Name | বিবরণ |
|---|---|
| `get_document` | নির্দিষ্ট Document-এর বিস্তারিত তথ্য পড়া। |
| `list_documents` | ফিল্টার ও পেজিনেশন সহ Document তালিকা বের করা। |
| `create_document` | নতুন Document তৈরি (এবং ঐচ্ছিক Auto Submit)। |
| `update_document` | বিদ্যমান Document আপডেট করা। |
| `delete_document` | **[Irreversible]** Document ডিলিট করা। |
| `get_count` | ফিল্টার অনুযায়ী Document সংখ্যা পাওয়া। |
| `submit_document` | Draft Document সাবমিট করা। |
| `cancel_document` | **[Irreversible]** Submitted Document ক্যানসেল করা। |
| `set_value` | Document-এর নির্দিষ্ট ফিল্ডের মান বদলানো। |
| `get_doctype_fields` | DocType-এর স্কিমা ও ফিল্ড লিস্ট জানা। |
| `search_link` | লিঙ্ক ফিল্ডের জন্য সার্চ করা। |
| `run_report` | ERPNext-এর যেকোনো standard/custom রিপোর্ট রান করা। |
| `call_method` | শুধুমাত্র Whitelisted Python Method এক্সিকিউট করা। |
| `get_document_pdf` | Document-এর প্রিলিন্ট ফরম্যাট থেকে PDF Base64 রূপান্তর। |
| `upload_file` | লোকাল ফাইল ERPNext ফাইল ম্যানেজারে আপলোড করা। |

---

## 📄 লাইসেন্স
MIT License — © 2026 Prime Technology of Bangladesh