AI 原生开放教材

外观

FastCampus AI Agent 바이브코딩 강의系统课程·英文原文 ↗原件 ↓仓库 ↗

실제 사례: NTS Business Verification MCP 서버 만들기 ​

이 문서는 실제로 국세청 사업자등록정보 진위확인 API를 MCP 서버로 만든 과정을 재현 가능하도록 기록합니다.

입력 정보 ​

API 정보 (제공된 입력) ​

국세청_사업자등록정보 진위확인 및 상태조회 서비스
버전: 1.1.0
Base URL: api.odcloud.kr/api/nts-businessman/v1

엔드포인트:
1. POST /validate - 사업자등록정보 진위확인
2. POST /status - 사업자등록 상태조회

특징:
- 1회 호출 시 최대 100개 처리 가능
- POST 메서드만 지원
- serviceKey는 URL 파라미터로 전달
- 요청 본문은 JSON 형식

필수 파라미터 ​

진위확인 필수 필드:
- b_no: 사업자등록번호 (10자리)
- start_dt: 개업일자 (YYYYMMDD)
- p_nm: 대표자성명

선택 필드:
- p_nm2: 대표자성명2 (외국인)
- b_nm: 상호
- corp_no: 법인등록번호 (13자리)
- b_sector: 주업태명
- b_type: 주종목명
- b_adr: 사업장주소

진행 태스크 ​

1. 프로젝트 생성 (5분) ​

bash
# 템플릿 사용하여 생성
uv run cookiecutter template/ -o src/

# 입력값
api_name: nts-business-verification
api_description: 국세청 사업자등록정보 진위확인 및 상태조회 서비스
author: Your Name
author_email: your.email@example.com

2. API 클라이언트 구현 (20분) ​

주요 변경사항 ​

python
# Base URL 변경
self.base_url = "https://api.odcloud.kr/api/nts-businessman/v1"

# POST 요청 처리
async def _request(
    self,
    endpoint: str,
    method: str = "POST",
    json_data: Optional[Dict[str, Any]] = None,
    params: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    url = f"{self.base_url}/{endpoint}"
    
    url_params = {
        "serviceKey": self.api_key,
        "returnType": "JSON",
        **(params or {})
    }
    
    response = await self.client.post(
        url,
        params=url_params,
        json=json_data,
        headers={"Content-Type": "application/json"}
    )

# API 메서드 구현
async def validate_business(
    self,
    businesses: List[BusinessInfo]
) -> ValidateResponse:
    if len(businesses) > 100:
        raise ValueError("Maximum 100 businesses")
    
    request_data = {
        "businesses": [biz.model_dump() for biz in businesses]
    }
    
    response_data = await self._request("validate", json_data=request_data)
    return ValidateResponse(**response_data)

async def check_status(
    self,
    business_numbers: List[str]
) -> StatusResponse:
    if len(business_numbers) > 100:
        raise ValueError("Maximum 100 business numbers")
    
    cleaned_numbers = [num.replace("-", "") for num in business_numbers]
    request_data = {"b_no": cleaned_numbers}
    
    response_data = await self._request("status", json_data=request_data)
    return StatusResponse(**response_data)

3. 데이터 모델 정의 (15분) ​

python
# models.py 전체 교체
class BusinessInfo(BaseModel):
    """사업자등록정보 모델."""
    b_no: str = Field(..., description="사업자등록번호")
    start_dt: str = Field(..., description="개업일자")
    p_nm: str = Field(..., description="대표자성명")
    p_nm2: Optional[str] = None
    b_nm: Optional[str] = None
    corp_no: Optional[str] = None
    b_sector: Optional[str] = None
    b_type: Optional[str] = None
    b_adr: Optional[str] = None

class BusinessStatus(BaseModel):
    """사업자 상태 정보."""
    b_no: str
    b_stt: Optional[str] = None  # 계속사업자/휴업자/폐업자
    b_stt_cd: Optional[str] = None  # 01/02/03
    tax_type: Optional[str] = None
    tax_type_cd: Optional[str] = None
    end_dt: Optional[str] = None
    utcc_yn: Optional[str] = None
    tax_type_change_dt: Optional[str] = None
    invoice_apply_dt: Optional[str] = None
    rbf_tax_type: Optional[str] = None
    rbf_tax_type_cd: Optional[str] = None

class ValidateResponse(BaseModel):
    """진위확인 응답."""
    status_code: str
    request_cnt: int
    valid_cnt: Optional[int] = 0
    data: List[ValidateResult] = Field(default_factory=list)

class StatusResponse(BaseModel):
    """상태조회 응답."""
    status_code: str
    request_cnt: int
    match_cnt: int
    data: List[BusinessStatus] = Field(default_factory=list)

4. MCP 서버 구현 (30분) ​

구현된 도구들 ​

  1. validate_business: 단일 사업자 진위확인
  2. check_business_status: 상태조회 (최대 100개)
  3. batch_validate_businesses: 배치 진위확인

핵심 로직 ​

python
@mcp.tool()
async def validate_business(
    business_number: str,
    start_date: str,
    representative_name: str,
    # ... 선택 파라미터
) -> Dict[str, Any]:
    """사업자등록정보 진위확인."""
    
    # 입력 형식 정리
    business_number = business_number.replace("-", "")
    start_date = start_date.replace("-", "")
    
    # 유효성 검증
    if len(business_number) != 10:
        return {"error": "사업자등록번호는 10자리여야 합니다."}
    
    if len(start_date) != 8:
        return {"error": "개업일자는 YYYYMMDD 형식이어야 합니다."}
    
    # API 호출
    business_info = BusinessInfo(
        b_no=business_number,
        start_dt=start_date,
        p_nm=representative_name,
        # ... 나머지 필드
    )
    
    async with NtsBusinessVerificationAPIClient() as client:
        try:
            response = await client.validate_business([business_info])
            
            if response.data:
                result = response.data[0]
                return {
                    "business_number": result.b_no,
                    "valid": result.valid,
                    "valid_msg": result.valid_msg or (
                        "일치" if result.valid == "01" else "확인할 수 없습니다"
                    ),
                    "status": result.status.model_dump() if result.status else None
                }
        except Exception as e:
            return {"error": str(e)}

5. 테스트 작성 (20분) ​

테스트 항목 ​

  • API 클라이언트 초기화
  • 진위확인 API 호출
  • 상태조회 API 호출
  • 최대 개수 제한 검증
  • 입력 형식 검증
  • MCP 도구 테스트
bash
# 테스트 실행
cd src/nts-business-verification
uv run pytest tests/ -v

# 결과: 19 passed

6. 로컬 테스트 (10분) ​

Claude Desktop 설정 ​

json
{
  "mcpServers": {
    "nts-business-verification": {
      "command": "/Users/bong/github/data-go-mcp-servers/.venv/bin/python",
      "args": ["-m", "data_go_mcp.nts_business_verification.server"],
      "cwd": "/Users/bong/github/data-go-mcp-servers/src/nts-business-verification",
      "env": {
        "NTS_BUSINESS_VERIFICATION_API_KEY": "실제-API-키",
        "PYTHONPATH": "/Users/bong/github/data-go-mcp-servers/src/nts-business-verification"
      }
    }
  }
}

연결 문제 해결 ​

  1. 초기 오류: ModuleNotFoundError
  2. 원인: UV가 패키지를 제대로 설치하지 못함
  3. 해결: 가상환경 Python 직접 사용 + PYTHONPATH 설정

7. PyPI 배포 (10분) ​

배포 스크립트 작성 ​

python
# scripts/deploy_to_pypi.py
def deploy():
    # .env에서 PyPI 토큰 읽기
    token = os.getenv("PYPI_API_TOKEN")
    
    # uv build로 패키지 빌드
    subprocess.run(["uv", "build"], cwd=package_dir)
    
    # twine으로 업로드
    subprocess.run([
        "twine", "upload",
        "--username", "__token__",
        "--password", token,
        "dist/*"
    ], cwd=package_dir)

배포 실행 ​

bash
uv run python scripts/deploy_to_pypi.py nts-business-verification

# 결과
✅ Successfully uploaded to PyPI!
📦 Package: https://pypi.org/project/data-go-mcp.nts-business-verification/

소요 시간 ​

  • 템플릿 생성: 5분
  • API 클라이언트: 20분
  • 데이터 모델: 15분
  • MCP 서버 구현: 30분
  • 테스트 작성: 20분
  • 로컬 테스트 및 디버깅: 10분
  • 문서화: 15분
  • PyPI 배포: 10분

총 소요 시간: 약 2시간

검증 방법 ​

1. 단위 테스트 ​

bash
uv run pytest tests/ -v
# 19 tests passed

2. 로컬 서버 실행 ​

bash
export NTS_BUSINESS_VERIFICATION_API_KEY="your-key"
uv run python -m data_go_mcp.nts_business_verification.server
# 서버가 정상 실행되면 성공

3. Claude Desktop 연결 ​

  • 설정 파일 수정
  • Claude Desktop 재시작
  • 우측 하단 MCP 아이콘 확인

4. 실제 사용 테스트 ​

"사업자등록번호 123-45-67890이 2020년 1월 1일에 홍길동 대표로 등록된 것이 맞는지 확인해줘"

핵심 포인트 ​

성공 요인 ​

  1. 템플릿 사용: 보일러플레이트 코드 자동 생성
  2. 명확한 에러 처리: 입력 검증 및 친절한 에러 메시지
  3. 테스트 우선: 모든 기능에 대한 테스트 작성
  4. 문서화: 사용법과 예시 제공

주의사항 ​

  1. POST vs GET: API 메서드 확인 필수
  2. 인증 방식: URL 파라미터 vs 헤더
  3. 데이터 형식: JSON 요청 본문 처리
  4. 제한사항: 최대 처리 개수 확인

디버깅 팁 ​

  1. 로그 확인: ~/Library/Logs/Claude/mcp*.log
  2. 수동 테스트: 서버 직접 실행
  3. 경로 문제: 절대 경로 사용
  4. Python 경로: 가상환경 Python 직접 지정

결과물 ​

  • 3개의 MCP 도구 구현 완료
  • 19개 테스트 모두 통과
  • PyPI 패키지 배포 완료
  • 문서화 완료
  • Claude Desktop에서 사용 가능