사장님서랍 BossDrawer

한 줄 소개

사장님서랍(BossDrawer)은 소상공인이 받은 사업 문서와 메시지를 분류하고 금액, 날짜, 제출서류, 해야 할 일, 확인 메시지 초안으로 정리하는 PlayMCP용 MCP Agent입니다.

문제 정의

소상공인은 세금 고지서, 영수증, 지원사업 공고, 계약서, 직원 서류, 입금/청구 안내를 여러 채널로 받습니다. 문서마다 확인해야 할 금액, 기한, 제출서류, 담당자가 다르고, 세무사·거래처·직원에게 다시 물어봐야 하는 내용도 자주 생깁니다. 사장님서랍은 실제 신고, 계약, 신청, 메시지 발송을 대신하지 않고 문서 정리와 체크리스트를 제공합니다.

왜 카카오톡/PlayMCP에 적합한가

• 소상공인은 세무사, 거래처, 직원, 고객과 카카오톡으로 문서와 안내를 자주 주고받습니다.
• 사업 관련 문서는 카톡 메시지, 사진, PDF, 문자로 흩어지기 쉽습니다.
• 사장님서랍은 흩어진 문서를 대화 안에서 바로 분류하고 해야 할 일로 바꿔줍니다.
• 실제 신고/계약/신청을 대신하지 않고 정리와 체크리스트만 제공하므로 안전합니다.

주요 사용자

• 세무 신고 자료를 정리해야 하는 자영업자
• 지원사업 공고를 빠르게 이해하고 싶은 소상공인
• 계약서, 견적서, 발주서 확인 항목을 놓치고 싶지 않은 사업자
• 직원 급여/근로계약 관련 자료를 정리해야 하는 매장 운영자

주요 기능

• 사업 문서/메시지 유형 분류
• 금액, 날짜, 기관, 기한, 준비서류, 계약 조건 추출
• 문서 유형별 액션 체크리스트 생성
• 준비한 자료와 누락 가능 서류 비교
• 세무사, 거래처, 직원, 고객, 기관 담당자에게 보낼 메시지 초안 생성
• LLM API key 없이도 동작하는 rule-based fallback
• PlayMCP 등록용 Streamable HTTP MCP endpoint 제공

MCP Tool 설계

MCP server name은 BossDrawer입니다. Tool은 정확히 5개만 제공합니다.

Tool	목적
classify_business_document	문서/메시지를 tax, receipt, contract, grant, employee, payment, notice, unknown으로 분류
extract_key_info	금액, 날짜, 기한, 기관, 제출서류, 계약 조건, 담당자/역할 추출
make_action_checklist	문서 유형과 핵심 정보 기반으로 다음 행동 생성
check_missing_documents	준비한 서류와 일반 후보 서류 비교
make_business_message	세무사/거래처/직원/기관 등에게 보낼 메시지 초안 생성

모든 Tool은 readOnlyHint=true, destructiveHint=false, openWorldHint=false, idempotentHint=true annotations를 포함합니다.

Tool별 입력/출력 예시

classify_business_document

입력:

{"text": "세무사님이 부가세 신고 자료 보내달라고 했어."}

출력 요약:

{
  "ok": true,
  "tool": "classify_business_document",
  "result": {"document_type": "tax", "confidence": "high"},
  "warnings": [],
  "notice": "..."
}

extract_key_info

입력:

{"text": "신청기간은 2026년 7월 31일까지이며 사업자등록증과 신청서를 제출해야 합니다.", "document_type": "grant"}

출력 요약:

{
  "result": {
    "key_info": {
      "dates": ["2026년 7월 31일"],
      "required_documents": ["사업자등록증", "신청서"]
    }
  }
}

make_action_checklist

입력:

{"text": "부가세 신고 자료 준비", "document_type": "tax", "key_info": {}}

출력은 task, priority, reason, needs_expert_check를 가진 checklist item을 4개 이상 반환합니다.

check_missing_documents

입력:

{"document_type": "tax", "prepared_documents": ["카드매출", "사업자 등록증"], "context": "부가세 신고"}

출력은 prepared, matched_documents, possibly_missing, questions_to_ask를 포함합니다.

make_business_message

입력:

{"recipient_type": "accountant", "purpose": "부가세 자료 확인", "context": "카드 매출 내역은 준비했습니다.", "tone": "polite"}

출력은 실제 발송이 아닌 메시지 초안만 반환합니다.

안전 정책

• 세무·법률·노무·금융 자문을 제공하지 않습니다.
• 주민등록번호, 계좌번호, 카드번호, 인증서, 비밀번호, API key, 상세주소 입력을 요구하지 않습니다.
• 민감정보 패턴이 감지되면 warnings에 경고를 포함합니다.
• 절세 가능합니다, 법적으로 문제없습니다, 반드시 선정됩니다 같은 단정 표현을 제거하거나 완화합니다.
• 모든 Tool 결과에는 전문가 또는 공식 기관 확인 notice를 포함합니다.

PlayMCP 가이드 준수 사항

• Streamable HTTP MCP endpoint: POST /mcp
• Stateless HTTP: stateless_http=True
• 지원 버전 범위: 2025-03-26 ~ 2025-11-25
• Server Name: BossDrawer
• Tool name에 kakao 문자열 없음
• Tool name은 영어/숫자/underscore만 사용
• Tool 개수: 5개
• 각 Tool은 name, description, inputSchema, annotations 포함

로컬 실행 방법

cd boss-drawer-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
uvicorn app.main:app --reload --port 8000

Health check:

curl http://localhost:8000/health

Docker 실행 방법

docker build -t boss-drawer-mcp .
docker run --rm -p 8000:8000 boss-drawer-mcp
curl http://localhost:8000/health

테스트 실행 방법

pytest -q
python scripts/check_playmcp_ready.py

테스트는 외부 API와 실제 LLM 호출 없이 통과합니다. 실제 LLM 사용은 선택 사항이며, 실패 시 fallback이 반환됩니다.

Debug endpoint 예시

개발용 endpoint입니다. PlayMCP 등록용 endpoint는 /mcp입니다.

curl -X POST http://localhost:8000/debug/classify \
  -H 'Content-Type: application/json' \
  -d '{"text":"세무사님이 부가세 신고 자료 보내달라고 했어."}'

curl -X POST http://localhost:8000/debug/message \
  -H 'Content-Type: application/json' \
  -d '{"recipient_type":"accountant","purpose":"부가세 자료 확인","context":"카드 매출 내역은 준비했습니다.","tone":"polite"}'

MCP Inspector 점검 방법

1. 서버 실행: uvicorn app.main:app --port 8000
2. Inspector에서 Streamable HTTP endpoint를 http://localhost:8000/mcp로 설정
3. tools/list로 5개 Tool과 annotations 확인
4. tools/call로 classify_business_document 샘플 호출
5. /health 응답 확인

데모 시나리오

자세한 데모는 docs/demo_scenarios.md를 참고하세요.

1. 부가세 신고 자료 준비
2. 소상공인 지원사업 공고 분석
3. 거래처 계약서 핵심 확인
4. 직원 근로계약/급여 안내 정리
5. 입금/미수금 확인 메시지 작성

제한사항

• 실제 세금 신고, 지원사업 신청, 계약 검토, 노무 판단, 메시지 발송을 수행하지 않습니다.
• 정책/지원사업/세무 기준은 변경될 수 있으므로 공식 기관 또는 전문가 확인이 필요합니다.
• OCR, 파일 업로드, 장기 사용자 저장소는 MVP 범위에 포함하지 않았습니다.
• LLM API key가 없어도 동작하지만, 긴 비정형 문서의 추론 품질은 제한될 수 있습니다.

향후 확장 계획

• OCR/이미지 영수증 분석
• 업종별 체크리스트 템플릿
• 세무사/노무사 협업용 공유 링크
• 문서 보관함/회계 프로그램 연동
• 지원사업 공고 데이터 freshness 관리

제출 전 체크리스트

• [ ] 공개 URL에서 /health 접근 가능
• [ ] 공개 URL에서 /mcp Streamable HTTP 접근 가능
• [ ] MCP Inspector로 tools/list, tools/call 통과
• [ ] python scripts/check_playmcp_ready.py 통과
• [ ] pytest -q 통과
• [ ] Tool name에 kakao 문자열 없음
• [ ] LLM API key 없이 fallback 동작 확인
• [ ] 민감정보를 저장하지 않는지 확인