# 사장님서랍 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

입력:

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

출력 요약:

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

### extract_key_info

입력:

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

출력 요약:

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

### make_action_checklist

입력:

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

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

### check_missing_documents

입력:

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

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

### make_business_message

입력:

```json
{"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` 포함

## 로컬 실행 방법

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

Health check:

```bash
curl http://localhost:8000/health
```

## Docker 실행 방법

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

## 테스트 실행 방법

```bash
pytest -q
python scripts/check_playmcp_ready.py
```

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

## Debug endpoint 예시

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

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

```bash
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](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 동작 확인
- [ ] 민감정보를 저장하지 않는지 확인