Paperware MCP 서버 (paperware_mcp)

Paperware Factory(erp.paperwarefactory.com)의 ERPNext/Frappe bench를 위한 Model Context Protocol (MCP) 네이티브 서버입니다.

이 앱은 Prime AI Agent (NousResearch Hermes Agent framework, "Prime" persona, Docker/ Coolify에서 호스팅)가 Frappe ORM을 직접 사용해 ERPNext와 통신할 수 있게 해줍니다.

🌟 핵심 기능 (Key Features)

1. Frappe ORM 직접 통합: 외부 HTTP REST API 호출이나 API 키/시크릿이 필요 없습니다. frappe.get_doc, frappe.get_list, doc.insert(), doc.submit(), doc.cancel() 등을 직접 사용합니다.

2. 요청별 권한 위장(Impersonation): 각 호출 시 requesting_user 매개변수에 따라 frappe.set_user()가 수행되어 실제 Frappe 권한 엔진이 적용됩니다.

3. 화이트리스트 실행 보안: call_method 도구는 오직 @frappe.login.whitelist() 데코레이터가 있는 함수만 실행할 수 있습니다. 권한 없는 Python 코드 실행은 완전히 차단됩니다.

4. FastMCP 통합: Python mcp>=1.9.0,<2.0.0 패키지의 FastMCP 기반 도구 설정. stdio와 sse 두 가지 전송 방식(transport)을 지원합니다.

5. 네이티브 bench 명령: Frappe CLI와 연동되어 bench --site erp.paperfactory.com paperware-mcp 명령으로 서비스를 시작할 수 있습니다.

Related MCP server: MCP Task

🛠️ 설치 가이드 (단계별 설치)

1단계: 앱 소스 설치 확인

Frappe Bench 디렉터리(예: /home/user/frappe-bench/)에서 앱이 apps/paperware_mcp 폴더에 있는지 확인하세요.

cd /home/prime/frappe-bench

2단계: Python 의존성 설치

Bench 가상환경에 필요한 패키지(mcp>=1.9.0,<2.0.0)를 설치하세요:

./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)

paperware-mcp CLI 명령을 실행할 때 다음 옵션을 사용할 수 있습니다:

[!참고] --default-user administrator는 프로덕션에서 사용하면 안 됩니다. 프로덕션에서는 반드시 특정 봇 사용자 이메일을 전달하세요.

명령 예시:

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 봇 사용자 생성 (보안 모범 사례)

프로덕션 환경에서 작업하기 위해 ERPNext에 특정 봇 사용자를 만들 것을 권장합니다:

1. ERPNext Desk에서 사용자 목록으로 이동해 새 사용자를 만드세요.

2. 이메일: hermes.bot@paperwarefactory.com

3. 이름: Hermes Bot

4. 역할 프로필: 필요한 역할만 부여하세요 (예: 재고 사용자, 영업 사용자, 회계 사용자) — Hermes 에이전트가 불필요한 관리 권한을 얻지 않도록 합니다.

5. 서버 시작 시 --default-user hermes.bot@paperwarefactory 플래그를 사용합니다.

🏭 프로덕션 배포 (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 유닛 구성

/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 에이전트용 MCP 클라이언트 설정 (Harmes Agent Config)

Hermes 에이전트(또는 모든 MCP 클라이언트)의 mcp_config.json 파일에 paperware_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"
      ]
    }
  }
}

📦 노출된 MCP 도구 목록 (Exposed MCP Tools - 15개)

📄 라이선스

MIT 라이선스 — © 2026 프라임 테크놀로지 오브 방글라데시 (Prime Technology of Bangladesh)