Paperware MCP Server (paperware_mcp)

Un Servidor de Protocolo de Contexto de Modelo (MCP) nativo para el bench de ERPNext/Frappe de Paperware Factory (erp.paperwarefactory.com).

Esta aplicación permite que Prime AI Agent (framework NousResearch Hermes Agent, persona "Prime", alojado en Docker/Coolify) se comunique con ERPNext directamente usando el ORM de Frappe.

🌟 Características clave

1. Integración directa con el ORM de Frappe: No se necesitan llamadas HTTP REST API externas ni API Key/Secret. Se usan directamente frappe.get_doc, frappe.get_list, doc.insert(), doc.submit(), doc.cancel(), etc.

2. Suplantación de permisos por solicitud: En cada llamada de herramienta, se ejecuta frappe.set_user() según el parámetro requesting_user y el motor de permisos real de Frappe se activa.

3. Seguridad de ejecución en lista blanca: La herramienta call_method solo puede ejecutar funciones con el decorador @frappe.whitelist(). La ejecución de código Python no autorizada está completamente protegida y bloqueada.

4. Integración FastMCP: Configuración de herramientas basada en FastMCP del paquete Python mcp>=1.9.0,<2.0.0. Existen facilidades de transporte tanto stdio como sse.

5. Comando nativo de Bench: Integrado con la CLI de Frappe — el servicio se puede iniciar mediante el comando bench --site erp.paperwarefactory.com paperware-mcp.

Related MCP server: MCP Task

🛠️ Guía de instalación (paso a paso)

Paso 1: Colocar el código fuente de la aplicación

Vaya a su directorio de Frappe Bench (/home/prime/frappe-bench/) y asegúrese de que la aplicación esté presente en la carpeta apps/paperware_mcp.

cd /home/prime/frappe-bench

Paso 2: Instalar dependencias de Python

Instale los paquetes necesarios (mcp>=1.9.0,<2.0.0) en el entorno virtual de Bench:

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

Paso 3: Instalar la aplicación en el sitio ERPNext

Instale la aplicación paperware_mcp en su sitio deseado:

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

🚀 Ejecución del servicio y uso de comandos

Se pueden usar las siguientes opciones para ejecutar el comando CLI paperware-mcp:

[!WARNING] --default-user Administrator no debe usarse en producción. En producción, pase el correo electrónico de un usuario bot específico.

Ejemplos de comandos:

1. Ejecutar en modo Standard Input/Output (stdio):

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

2. Ejecutar en modo Server-Sent Events (SSE) en un puerto específico:

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

🛡️ Creación de un usuario bot dedicado de Hermes (mejores prácticas de seguridad)

Se recomienda crear un usuario bot específico en ERPNext para trabajar en el entorno de producción:

1. En el escritorio de ERPNext, vaya a User List y cree un New User.

2. Email: hermes.bot@paperwarefactory.com

3. First Name: Hermes Bot

4. Role Profile: Proporcione solo los roles necesarios (por ejemplo: Stock User, Sales User, Accounts User) para que Hermes Agent no obtenga poder administrativo innecesario.

5. Use la bandera --default-user hermes.bot@paperwarefactory.com al iniciar el servidor.

🏭 Despliegue en producción

Use Supervisor o un servicio Systemd para iniciar y mantener el servicio automáticamente en segundo plano.

Método 1: Configuración de Supervisor

Cree el archivo /etc/supervisor/conf.d/paperware_mcp.conf y escriba el siguiente código:

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

Recargue e inicie la configuración:

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

Método 2: Configuración de unidad Systemd

Cree el archivo /etc/systemd/system/paperware-mcp.service y proporcione la siguiente configuración:

[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

Habilite e inicie el servicio:

sudo systemctl daemon-reload
sudo systemctl enable paperware-mcp
sudo systemctl start paperware-mcp
sudo systemctl status paperware-mcp

🤖 Configuración del cliente MCP de Hermes Agent

Reglas para agregar paperware_mcp al archivo mcp_config.json de Hermes Agent (o cualquier cliente MCP):

1. Para transporte SSE (recomendado para conexiones Docker/remotas):

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

2. Para transporte Stdio (para ejecución local/en el mismo contenedor):

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

📦 Herramientas totales (Herramientas MCP expuestas - 15 herramientas)

📄 Licencia

MIT License — © 2026 Prime Technology of Bangladesh