korea-business-verify

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

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

도구 5종

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

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

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 (진위·상태 두 서비스 각각 신청 필요)
2. .env 파일:

   NTS_SERVICE_KEY=발급받은_서비스키

3. 실행: node dist/index.js (키가 있으면 자동으로 라이브 모드)

Claude Desktop / Cursor 연동

claude_desktop_config.json (npx 권장):

{
  "mcpServers": {
    "korea-business-verify": {
      "command": "npx",
      "args": ["-y", "korea-business-verify"],
      "env": { "NTS_SERVICE_KEY": "발급받은_키" }
    }
  }
}

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

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

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

신뢰성

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

개발

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

라이선스

MIT