Paperware MCP Server (paperware_mcp)

Нативный Model Context Protocol (MCP) Server для ERPNext/Frappe bench компании Paperware Factory (erp.paperwarefactory.com).

Это приложение позволяет Prime AI Agent (фреймворк NousResearch Hermes Agent, персона "Prime", размещённый в Docker/Coolify) напрямую взаимодействовать с ERPNext через Frappe ORM.

🌟 Ключевые возможности (Key Features)

1. Прямая интеграция с Frappe ORM: не требуются внешние HTTP REST API вызовы или API Key/Secret. Напрямую используются frappe.get_doc, frappe.get_list, doc.insert(), doc.submit(), doc.cancel() и т.д.

2. Имперсонация прав на каждый запрос: при каждом вызове инструмента выполняется frappe.set_user() в соответствии с параметром requesting_user, и действует настоящий механизм разрешений Frappe.

3. Безопасность выполнения через белый список: инструмент call_method может выполнять только функции с декоратором @frappe.whitelist(). Несанкционированное выполнение Python-кода полностью защищено и заблокировано.

4. Интеграция FastMCP: настройка инструментов на основе FastMCP из пакета Python mcp>=1.9.0,<2.0.0. Доступны оба транспорта: stdio и sse.

5. Нативная команда Bench: интегрирована с CLI Frappe — сервис можно запустить командой bench --site erp.paperwarefactory.com paperware-mcp.

Related MCP server: MCP Task

🛠️ Руководство по установке (Step-by-Step Installation)

Шаг 1: Размещение исходного кода приложения

Перейдите в каталог вашего Frappe Bench (/home/prime/frappe-bench/) и убедитесь, что приложение присутствует в папке apps/paperware_mcp.

cd /home/prime/frappe-bench

Шаг 2: Установка Python-зависимостей

Установите необходимые пакеты (mcp>=1.9.0,<2.0.0) в виртуальное окружение Bench:

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

Шаг 3: Установка приложения на сайт ERPNext

Установите приложение paperware_mcp на нужный сайт:

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

🚀 Запуск сервиса и использование команд (Usage & Command Options)

Для запуска CLI-команды paperware-mcp доступны следующие опции:

[!WARNING] Не следует использовать --default-user Administrator в продакшене. В продакшене обязательно передавайте email конкретного бот-пользователя.

Примеры команд:

1. Запуск в режиме Standard Input/Output (stdio):

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

2. Запуск в режиме 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 специального бот-пользователя:

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.

Способ 1: Конфигурация Supervisor (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

Способ 2: Конфигурация Systemd (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

🤖 Конфигурация MCP-клиента Hermes Agent (Конфигурация агента Hermes)

Правила добавления paperware_mcp в файл mcp_config.json агента Hermes (или любого MCP-клиента):

1. Для SSE-транспорта (рекомендуется для Docker/удалённого подключения):

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

2. Для Stdio-транспорта (для выполнения в том же контейнере/локально):

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

📄 Лицензия

MIT License — © 2026 Prime Technology of Bangladesh