# korea-business-verify

한국 사업자 검증 **MCP 서버** — 진위확인·휴폐업·과세유형·세금계산서 발행 가능 여부를 AI 에이전트에게 도구로 제공합니다. 국세청 공공데이터포털 API 기반.

> ⚠️ **면책**: 국세청 공공데이터 기준의 **참고 결과**이며 세무 자문이 아닙니다. 법적 효력이 있는 증명은 홈택스 발급 문서를 참조하세요.

## 도구 5종
| 도구 | 설명 |
|---|---|
| `verify_business` | 사업자등록정보 **진위확인** (사업자번호·대표자명·개업일자 일치 여부) |
| `check_business_status` | 휴폐업 상태·과세유형·폐업일자 (호출 빈도 최다) |
| `batch_check_status` | 최대 100건 **일괄 상태조회** (경비처리·정산 자동화) |
| `check_invoice_eligibility` | 세금계산서 발행 가능 여부 **판정 + 근거** (면세/폐업 등) |
| `explain_kr_tax_type` | 과세유형(일반/간이/면세/비과세) 실무 의미 해설 |

## 빠른 시작 — DEMO (서비스키 불필요)

```bash
npx -y korea-business-verify   # 서비스키 없으면 자동 DEMO 모드 (가상 사업자번호로 5종 도구 체험)
```

> **소스 빌드(개발자용):** `npm install && npm run build && DEMO_MODE=1 node dist/index.js`

**DEMO 가상 사업자번호** (체크섬은 유효하나 실제 존재하지 않는 번호):
| 번호 | 상태 | 과세유형 |
|---|---|---|
| `1111111119` | 계속사업자 | 일반과세자 → 세금계산서 가능 |
| `2222222227` | 계속사업자 | 면세사업자 → 계산서 대상 |
| `3333333336` | 폐업자 | → 발행 불가 |

## 라이브 모드 (실제 국세청 API)

1. 서비스키 발급: **[docs/get-api-key.md](docs/get-api-key.md)** (진위·상태 두 서비스 **각각** 신청 필요)
2. `.env` 파일:
   ```
   NTS_SERVICE_KEY=발급받은_서비스키
   ```
3. 실행: `node dist/index.js` (키가 있으면 자동으로 라이브 모드)

## Claude Desktop / Cursor 연동

`claude_desktop_config.json` (**npx 권장**):
```json
{
  "mcpServers": {
    "korea-business-verify": {
      "command": "npx",
      "args": ["-y", "korea-business-verify"],
      "env": { "NTS_SERVICE_KEY": "발급받은_키" }
    }
  }
}
```

<details><summary>대안: 로컬 빌드 경로로 연동</summary>

```json
{
  "mcpServers": {
    "korea-business-verify": {
      "command": "node",
      "args": ["/절대경로/korea-business-verify/dist/index.js"],
      "env": { "NTS_SERVICE_KEY": "발급받은_키" }
    }
  }
}
```
</details>

## 개인정보 보호 (무저장 원칙)

- **서비스키는 사용자 로컬 `.env`에만 존재**합니다. 본 서버는 이를 저장하거나 로그에 남기지 않으며, 국세청 API 인증을 위해서만 사용합니다.
- **대표자명 등 진위확인 입력값은 요청 즉시 폐기**됩니다. 진위확인을 위해 국세청 API로 전송되나, 응답 수신과 함께 어떤 로그·캐시·저장소에도 남기지 않습니다.
- **캐시**되는 것은 사업자번호와 상태조회 결과(24h)뿐입니다. 진위확인은 캐시하지 않습니다.
- 사업자번호는 국세청 호출 전 **체크섬 형식 검증**으로 사전 필터링합니다.

## 신뢰성

- API 장애(5xx·타임아웃·네트워크) 시 자동 재시도(지수 백오프, 3회). 인증/형식 에러는 즉시 명확한 에러 코드로 응답.
- 모든 판정 결과에 `basis`(근거) 필드 동봉.

## 개발

```bash
npm run build     # tsc
npm test          # vitest (커버리지 96%)
npm run lint      # eslint
```

## 라이선스
MIT