Frappe_Assistant_Core

당신의 ERPNext 사이트와 대화하세요. FAC는 Claude, ChatGPT 및 기타 MCP(Model Context Protocol) 준비가 된 LLM(Large Language Models)이 귀하의 송장(invoices), 고객(customers), 재고(stock), 워크플로(workflows) 및 커스텀 앱(custom apps)과 직접 상호작용할 수 있도록 지원합니다. 이 모든 과정은 ERPNext 권한 체계 내에서 이루어지며, 모든 호출은 기록됩니다.

FAC가 설치되면, 팀원들은 평소 수동으로 수행하던 작업들을 LLM에게 요청할 수 있습니다:

"상위 5개 고객사의 연체된 송장을 보여줘."

"이 리드(lead)의 상태를 Qualified로 업데이트하고 다음 작업 날짜를 월요일로 설정해줘."

"월간 수익 보고서를 실행하고 주요 변동 사항을 요약해줘."

"모든 창고에 SKU-1234 재고가 얼마나 남아있지?"

이러한 간단한 상호작용 이면에는 팀이 매일 수행하는 작업들 — 문서 CRUD(Create, Read, Update, Delete), 검색, 보고서, 워크플로, 분석, 파일 추출 및 대시보드 — 를 위한 **24개의 내장 도구(built-in tools)**가 공개되어 있습니다. 관리자는 Skills(LLM이 특정 작업을 처리하는 방법을 가르치는 재사용 가능한 지침)와 Prompt Templates(사용자가 관리자 UI에서 선택할 수 있는 저장된 시작점)를 게시하여, 답변의 일관성을 유지하고 올바른 보고서를 사용하도록 할 수 있습니다. LLM은 실제 ERPNext 사용자로서 OAuth 2.0을 통해 인증되므로, 해당 사용자가 데스크(desk)에서 이미 볼 수 있는 데이터만 볼 수 있습니다. 모든 호출은 Assistant Audit Log(어시스턴트 감사 로그)에 기록됩니다.

이것은 Frappe 앱이므로, 개발자는 훅(hook)을 통해 자신의 Frappe 앱에서 도구 세트를 확장할 수 있습니다 — 귀하의 데이터 모델, 귀하의 비즈니스 로직이 귀하의 앱 범위 내에서 적용됩니다.

데이터는 귀하의 사이트에 그대로 유지됩니다. 어떤 LLM을 연결할지는 귀하가 제어합니다.

Frappe를 실행하는 방식에 따라 두 가지 설치 경로가 있습니다.

• Frappe Cloud 대시보드의 사이트 Apps 탭으로 이동합니다. - 마켓플레이스에서 Frappe Assistant Core를 찾아 Install을 클릭합니다. - Frappe Cloud가 앱을 설치하고 마이그레이션합니다.

Marketplace: https://cloud.frappe.io/marketplace/apps/frappe_assistant_core

cd frappe-bench
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core
bench --site <your-site> install-app frappe_assistant_core

설치가 완료되면, 동일한 4단계 절차가 모든 MCP 호환 클라이언트에서 작동합니다. Claude Desktop에 대한 예시는 다음과 같습니다:

• Desk → FAC Admin으로 이동하여 MCP Endpoint URL을 복사합니다. - Claude Desktop → Settings → Connectors → Add Custom Connector에서 URL을 붙여넣고 Add를 클릭합니다. - Connect를 클릭하고 ERPNext 계정으로 로그인하여 권한을 승인합니다. - Claude에게 질문을 합니다. 예를 들어, *"이번 달에 생성된 모든 고객 목록을 보여줘."*라고 요청할 수 있습니다.

ChatGPT, Claude Web, 그리고 MCP Inspector에 대한 단계별 안내는 시작하기(Getting Started) 가이드를 참조하세요.

FAC는 LLM이 귀하의 데이터를 어떻게 처리할지 결정하는 두 가지 방법을 제공합니다.

**Skills (기술)**는 LLM에 제공하는 재사용 가능한 지침으로, 사이트 내부의 FAC Skill 문서로 저장됩니다. 각 기술은 skill_id, 설명, 그리고 사용 가능한 도구들을 사용하여 특정 작업을 처리하는 방법을 설명하는 마크다운(markdown) 콘텐츠를 가집니다. LLM은 연결 시 기술 목록을 나열하고 필요할 때마다 이를 가져오므로, 예를 들어 누군가 월간 매출 마감에 대해 물을 때마다 일관된 답변을 제공하며 올바른 보고서를 사용하게 됩니다.

**Prompt Templates (프롬프트 템플릿)**는 대화의 사용자 측면을 위한 저장된 시작점입니다. 이는 타입이 지정된 인자(드롭다운, 날짜, 불리언 등)를 포함하는 Jinja 템플릿 기반의 프롬프트입니다. 작성자는 관리자 페이지에서 이를 게시하며, 사용자는 하나를 선택하고 인자를 입력하면 렌더링된 프롬프트가 LLM으로 전송됩니다. "매출 분석", "제조 분석" 또는 귀하의 산업 특화 워크플로우와 같이 자주 묻는 분석에 이를 사용하세요.

두 기능 모두 Frappe 내에 존재하므로 사이트와 함께 버전 관리(version-controlled)가 가능하며, 사용자 간 공유가 가능하고, assistant_skills 훅(hook)을 통해 외부 Frappe 앱에 의해 배포될 수 있습니다.

FAC는 4개의 플러그인에 걸쳐 24개의 도구를 제공합니다: Core (Frappe 작업), Data Science (Python 실행, 분석, 파일 추출), Visualization (대시보드 및 차트), 그리고 Custom Tools (외부 앱에서 기여한 도구들을 위한 레지스트리).

카테고리	도구
Documents	get_document, list_documents, create_document, update_document, delete_document, submit_document
...
각 도구에 대한 전체 사양은 도구 참조(Tool Reference)에서 확인할 수 있습니다.

Frappe 앱을 보유하고 있으며 LLM이 해당 앱에 접근하기를 원한다면, 앱의 hooks.py에서 assistant_tools 훅 (hook)을 사용하세요. 이것이 권장되는 방식입니다. 도구가 앱과 함께 이동하고, 업그레이드 시에도 유지되며, 귀하의 데이터 모델 범위(scoped) 내에 머물기 때문입니다. 동일한 패턴이 assistant_skills 훅을 통한 스킬 (Skills)에도 적용됩니다.

대신 FAC의 핵심 동작을 수정해야 하는 경우에는 내부 플러그인 (internal plugin)을 작성하세요.

훅 계약 (hook contract)에 대해서는 외부 앱 개발 (External App Development) 가이드를, 내부 플러그인에 대해서는 플러그인 개발 (Plugin Development) 가이드를 참조하십시오.

FAC는 LLM 연결을 위해 PKCE를 사용하는 OAuth 2.0을 사용합니다. 따라서 LLM은 사용자의 Frappe 비밀번호를 절대 볼 수 없습니다. 모든 도구 호출은 호출한 사용자의 Frappe 및 ERPNext 역할 (roles)과 권한 (permissions) 범위 내로 제한됩니다. 즉, 사용자가 데스크 (desk)에서 특정 DocType을 읽을 수 없다면, LLM을 통해서도 해당 DocType을 읽을 수 없습니다. 모든 호출은 호출자, 도구, 인자 (arguments), 결과 상태와 함께 Assistant Audit Log에 기록되므로, 관리자는 LLM이 수행한 작업에 대한 전체 기록을 항상 보유할 수 있습니다.

설정 및 고급 구성 안내:

• Getting Started — Claude Desktop 및 ChatGPT를 포함한 전체 설정 단계별 안내
• OAuth Quick Start — 2분 만에 완료하는 OAuth 설정
• Tool Reference — 모든 도구, 인자, 반환 형식
• API Reference — MCP 엔드포인트 및 OAuth API
• Internals — 시스템 설계 및 플러그인 내부 구조
• External App Development — 자체 Frappe 앱에서 도구 추가하기
• Full documentation index — 기타 모든 사항

Frappe Assistant Core는 공개적으로 구축되고 유지 관리됩니다. 이 도구가 팀의 시간을 절약해 준다면, GitHub Sponsors를 통해 지속적인 유지 관리와 새로운 기능을 위한 후원(정기 또는 일회성 기여)을 고려해 주세요.

전문적인 구현, 커스터마이징, 교육 및 엔터프라이즈 지원은 공식 서비스 파트너인 Promantia에서 제공합니다. ai-support@promantia.com으로 문의하거나 https://erp.promantia.in/fac-registration/new 에서 프로젝트를 등록하십시오. 자세한 내용은 COMMERCIAL.md를 참조하십시오.

소프트웨어 자체는 AGPL-3.0 라이선스에 따라 완전히 무료이며 오픈 소스로 유지됩니다. 전문 서비스 이용은 선택 사항입니다.

AGPL-3.0 — LICENSE를 참조하십시오.

이중 라이선스 (dual-licensing), 새로운 파트너십 또는 후원 문의는 jypaulclinton@gmail.com으로 연락해 주시기 바랍니다.

기여를 환영합니다. Pull-request 워크플로우 및 코딩 표준에 대해서는 Contributing.md를 참조하십시오.