Paperware MCP Server (paperware_mcp)

Ein nativer Model Context Protocol (MCP) Server für den ERPNext/Frappe-Bench von Paperware Factory (erp.paperwarefactory.com).

Diese App ermöglicht es dem Prime AI Agent (NousResearch Hermes Agent Framework, „Prime“-Persona, gehostet auf Docker/Coolify), direkt über das Frappe ORM mit ERPNext zu kommunizieren.

🌟 Kernfunktionen (Key Features)

1. Direkte Frappe-ORM-Integration: Keine externen HTTP-REST-API-Aufrufe oder API-Keys/Secrets erforderlich. Es werden direkt frappe.get_doc, frappe.get_list, doc.insert(), doc.submit(), doc.cancel() usw. verwendet.

2. Permission-Impersonation pro Anfrage: Bei jedem Tool-Aufruf wird frappe.set_user() gemäß dem Parameter requesting_user ausgeführt und die echte Frappe-Berechtigungsengine greift.

3. Sicherheit durch Whitelist-Ausführung: Das call_method-Tool kann nur Funktionen mit dem @frappe.whitelist()-Dekorator ausführen. Nicht autorisierte Python-Codeausführung ist vollständig geschützt und blockiert.

4. FastMCP-Integration: Tool-Setup basierend auf FastMCP aus dem Python-Paket mcp>=1.9.0,<2.0.0. Sowohl stdio- als auch sse-Transport sind verfügbar.

5. Natives Bench-Kommando: Mit der Frappe-CLI verbunden – der Dienst kann über den Befehl bench --site erp.paperwarefactory.com paperware-mcp gestartet werden.

Related MCP server: MCP Task

🛠️ Installationsanleitung (Schritt-für-Schritt-Installation)

Schritt 1: App-Quelle einrichten

Gehen Sie zu Ihrem Frappe-Bench-Verzeichnis (/home/prime/frappe-bench/) und stellen Sie sicher, dass sich die App im Ordner apps/paperware_mcp befindet.

cd /home/prime/frappe-bench

Schritt 2: Python-Abhängigkeiten installieren

Installieren Sie die erforderlichen Pakete (mcp>=1.9.0,<2.0.0) in der Bench-Virtual-Umgebung:

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

Schritt 3: App auf der ERPNext-Site installieren

Installieren Sie die App paperware_mcp auf Ihrer gewünschten Site:

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

🚀 Dienst starten und Befehlsverwendung (Usage & Command Options)

Die folgenden Optionen können zum Ausführen des CLI-Befehls paperware-mcp verwendet werden:

[!WARNING] --default-user Administrator sollte in der Produktion nicht verwendet werden. In der Produktion muss unbedingt die E-Mail eines bestimmten Bot-Benutzers übergeben werden.

Befehlsbeispiele:

1. Ausführen im Standard-Input/Output-Modus (stdio):

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

2. Ausführen im Server-Sent-Events-Modus (SSE) auf einem bestimmten Port:

bench --site erp.paperwarefactory.com paperware-mcp --transport sse --port 8931 --default-user hermes.bot@paperwarefactory.com

🛡️ Dedizierten Hermes-Bot-Benutzer erstellen (Security Best Practices)

Für die Arbeit in der Produktionsumgebung wird empfohlen, in ERPNext einen bestimmten Bot-Benutzer zu erstellen:

1. Gehen Sie im ERPNext-Desk zur User List und erstellen Sie einen New User.

2. Email: hermes.bot@paperwarefactory.com

3. First Name: Hermes Bot

4. Role Profile: Weisen Sie nur die erforderlichen Rollen zu (z. B. Stock User, Sales User, Accounts User), damit der Hermes Agent keine unnötigen administrativen Rechte erhält.

5. Verwenden Sie beim Starten des Servers das Flag --default-user hermes.bot@paperwarefactory.com.

🏭 Produktionsbereitstellung (Production Deployment)

Verwenden Sie Supervisor oder einen Systemd-Dienst, um den Dienst automatisch im Hintergrund zu starten und am Laufen zu halten.

Methode 1: Supervisor-Konfiguration

Erstellen Sie die Datei /etc/supervisor/conf.d/paperware_mcp.conf und fügen Sie den folgenden Code ein:

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

Konfiguration neu laden und starten:

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

Methode 2: Systemd-Unit-Konfiguration (Systemd-Dienst)

Erstellen Sie die Datei /etc/systemd/system/paperware-mcp.service und geben Sie die folgende Konfiguration an:

[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

Dienst aktivieren und starten:

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-Konfiguration)

Regeln zum Hinzufügen von paperware_mcp zur Datei mcp_config.json des Hermes Agent (oder eines beliebigen MCP-Clients):

1. Für den SSE-Transport (empfohlen für Docker/Remote-Verbindungen):

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

2. Für den Stdio-Transport (bei gleichem Container/lokaler Ausführung):

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

📦 Alle Tools (Exposed MCP Tools - 15 Tools)

📄 Lizenz

MIT License — © 2026 Prime Technology of Bangladesh