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 ফোল্ডারে উপস্থিত রয়েছে।

cd /home/prime/frappe-bench

ধাপ ২: Python Dependencies ইনস্টল

Bench Virtual Environment-এ আবশ্যকীয় packages (mcp>=1.9.0,<2.0.0) ইনস্টল করুন:

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

ধাপ ৩: ERPNext সাইটে অ্যাপ ইনস্টল

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

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) মোডে চালানো:

bench --site erp.paperwarefactory.com paperware-mcp --transport stdio --default-user hermes.bot@paperwarefactory.com

২. Server-Sent Events (SSE) মোডে নির্দিষ্ট পোটে চালানো:

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 ফাইল তৈরি করে নিচের কোডটি লিখুন:

[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"

কনফিগারেশন রিলোড ও স্টার্ট করুন:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status paperware-mcp

---

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

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

[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

সার্ভিস এনাবল ও চালু করুন:

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-এর জন্য (ডকার/রিমোট কানেকশনের জন্য প্রস্তাবিত):

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

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

{
  "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