🚀 Nara Market FastMCP 2.0 Server

한국 정부조달(G2B) 및 나라장터 쇼핑몰 데이터를 수집하는 FastMCP서버입니다.

🛠️ 사용 가능한 MCP 도구 (총 15개)

🏛️ 기본 API 호출 도구 (4개)

Tool	기능	지원 API
call_public_data_standard_api	공공데이터개방표준 API 호출	입찰공고, 낙찰정보, 계약정보 등
call_procurement_statistics_api	공공조달통계정보 API 호출	전체/기관별/기업별 조달 통계
call_product_list_api	물품목록정보 API 호출	상품분류, 물품정보 등
call_shopping_mall_api	종합쇼핑몰품목정보 API 호출	MAS 계약 상품정보

🤖 AI 친화 간편 도구 (4개)

Tool	기능	특징
get_recent_bid_announcements	최근 입찰공고 조회	한글 업무구분, 자동 날짜 계산
get_successful_bids_by_business_type	업무구분별 낙찰정보 조회	한글 입력, 자동 코드 변환
get_procurement_statistics_by_year	연도별 조달통계 조회	간단한 연도 입력
search_shopping_mall_products	쇼핑몰 제품 검색	제품명/업체명 검색

🧭 고급 분석 도구 (4개)

Tool	기능	용도
get_all_api_services_info	전체 API 서비스 정보	사용 가능한 모든 서비스 및 오퍼레이션 조회
get_api_operations	서비스별 오퍼레이션 목록	특정 서비스의 세부 기능 확인
call_api_with_pagination_support	페이징 지원 API 호출	대량 데이터 조회 및 탐색 가이드
get_data_exploration_guide	데이터 탐색 가이드	파라미터 조합 및 검색 전략 제공

📦 기본 기능 도구 (3개)

Tool	기능	설명
crawl_list	나라장터 상품 목록 조회	기본 상품 리스트 수집
get_detailed_attributes	상품 상세 속성 조회	개별 상품의 세부 정보
server_info	서버 정보	버전 및 사용 가능한 도구 목록

📚 AI 가이드 리소스 (3개 Resource + 3개 Prompt)

MCP Resources

• api_parameter_requirements - API별 필수/선택 파라미터 가이드
• parameter_value_examples - 파라미터 값 예시 및 형식 가이드
• common_search_patterns - 자주 사용되는 검색 패턴 및 최적화 전략

MCP Prompts

• workflow_guide - 단계별 워크플로우 가이드 (5가지 분석 시나리오)
• parameter_selection_guide - 파라미터 선택 및 최적화 가이드
• real_world_query_examples - 실제 업무 시나리오별 쿼리 예제 (8가지)

🔧 설치 및 실행

시스템 요구사항

• Python: 3.10 이상
• 메모리: 최소 2GB (대량 데이터 수집 시 4GB+ 권장)
• 디스크: 수집 데이터 크기에 따라 조정

1. 로컬 설치 (개발/테스트)

# 저장소 클론
git clone <repository-url>
cd naramarketmcp

# 환경 설정
cp .env.example .env
# .env 파일에서 NARAMARKET_SERVICE_KEY 설정

# 의존성 설치
pip install -r requirements.txt

# STDIO 모드로 실행 (MCP 클라이언트용)
python -m src.main

# HTTP 서버 모드로 실행 (테스트용)
export FASTMCP_TRANSPORT=http
export FASTMCP_HOST=127.0.0.1
export FASTMCP_PORT=8000
python -m src.main

2. 패키지 설치

# 패키지 설치
pip install .

# 콘솔 스크립트로 실행
naramarket-mcp

# SSE 모드 지원 (선택사항)
pip install .[sse]
export FASTMCP_TRANSPORT=sse
naramarket-mcp

3. Docker 실행

# 이미지 빌드
docker build -t naramarket-mcp .

# 컨테이너 실행
docker run --rm \
  -e NARAMARKET_SERVICE_KEY=your-api-key \
  -p 8000:8000 \
  naramarket-mcp

🏭 Smithery.ai 클라우드 배포

빠른 배포

1. Smithery CLI 설치

   npm install -g @smithery/cli
   

2. API 키 준비

   • data.go.kr에서 나라장터 API 키 발급
   • Smithery.ai 대시보드에서 NARAMARKET_SERVICE_KEY 시크릿 설정

3. 배포 실행

   ./deploy.sh
   # 또는 수동: smithery deploy
   

배포 구성

• ✅ smithery.yaml: 메인 배포 설정
• ✅ Dockerfile: 프로덕션 최적화 컨테이너
• ✅ .env.example: 환경변수 템플릿
• ✅ deploy.sh: 자동 배포 스크립트

주요 배포 특징

• HTTP Transport: Smithery.ai의 HTTP 기반 MCP 프로토콜
• 동적 포트: PORT 환경변수 자동 감지
• 헬스체크: /mcp 엔드포인트 모니터링
• 시크릿 관리: 환경변수 기반 API 키 설정
• 오토스케일링: 로드에 따른 1-10 인스턴스 자동 확장

MCP 엔드포인트

배포 완료 후 다음 엔드포인트 사용 가능:

• GET /mcp - 헬스체크 및 서버 정보
• POST /mcp - MCP 도구 호출
• DELETE /mcp - 리셋/정리 작업

🌐 API 사용 예시

나라장터 상품 목록 조회

{
  "method": "tools/call",
  "params": {
    "name": "crawl_list",
    "arguments": {
      "category": "데스크톱컴퓨터",
      "page_no": 1,
      "num_rows": 50,
      "days_back": 30
    }
  }
}

G2B 입찰공고 정보 조회

{
  "method": "tools/call",
  "params": {
    "name": "get_bid_announcement_info",
    "arguments": {
      "num_rows": 20,
      "page_no": 1,
      "start_date": "20240101",
      "end_date": "20240131"
    }
  }
}

대량 데이터 CSV 수집 (분할 처리)

{
  "method": "tools/call",
  "params": {
    "name": "crawl_to_csv",
    "arguments": {
      "category": "노트북컴퓨터",
      "output_csv": "laptops_2024.csv",
      "total_days": 365,
      "window_days": 30,
      "max_windows_per_call": 2,
      "append": false,
      "explode_attributes": true
    }
  }
}

⚙️ 환경 변수 설정

필수 환경 변수

# 나라장터 API 서비스 키 (필수)
NARAMARKET_SERVICE_KEY=your-service-key-here

선택 환경 변수

# FastMCP Transport 모드
FASTMCP_TRANSPORT=stdio  # stdio, sse, http

# HTTP 모드 설정 (FASTMCP_TRANSPORT=http일 때)
FASTMCP_HOST=127.0.0.1
FASTMCP_PORT=8000

# API 환경 설정
API_ENVIRONMENT=production  # production, development

# 로깅 레벨
LOG_LEVEL=INFO

🔍 대용량 데이터 수집 가이드

윈도우 분할 전략

대량 데이터 수집 시 메모리 효율성과 재시작 가능성을 위해 윈도우 분할을 사용합니다.

{
  "method": "tools/call",
  "params": {
    "name": "crawl_to_csv",
    "arguments": {
      "category": "데스크톱컴퓨터",
      "output_csv": "desktop_full.csv",
      "total_days": 365,
      "window_days": 30,
      "max_windows_per_call": 2,
      "max_runtime_sec": 1800,
      "append": false
    }
  }
}

이어받기 실행

{
  "method": "tools/call",
  "params": {
    "name": "crawl_to_csv",
    "arguments": {
      "category": "데스크톱컴퓨터",
      "output_csv": "desktop_full.csv",
      "total_days": 300,
      "anchor_end_date": "20240301",
      "window_days": 30,
      "max_windows_per_call": 2,
      "append": true
    }
  }
}

주요 파라미터 설명

파라미터	설명	기본값
total_days	수집할 총 일수 (역순)	365
window_days	윈도우 크기 (일)	30
anchor_end_date	시작 기준 날짜 (YYYYMMDD)	오늘
max_windows_per_call	호출당 최대 윈도우 수	0 (무제한)
max_runtime_sec	최대 실행 시간 (초)	None
append	기존 파일에 추가 여부	false
explode_attributes	속성 컬럼 펼치기	false

📁 프로젝트 구조

naramarketmcp/
├── src/
│   ├── __init__.py
│   ├── main.py              # FastMCP 서버 진입점
│   ├── core/                # 핵심 모듈
│   │   ├── __init__.py
│   │   ├── config.py        # 설정 관리
│   │   └── models.py        # 데이터 모델
│   ├── api/                 # API 클라이언트
│   │   ├── __init__.py
│   │   └── client.py        # API 호출 로직
│   ├── services/            # 비즈니스 로직
│   │   ├── __init__.py
│   │   └── data_service.py  # 데이터 처리 서비스
│   └── tools/               # MCP 도구
│       ├── __init__.py
│       ├── base.py          # 기본 도구 클래스
│       ├── naramarket.py    # 나라장터 도구
│       └── openapi_tools.py # G2B OpenAPI 도구
├── tests/                   # 테스트 코드
├── deployments/             # 배포 설정
├── .env.example             # 환경변수 템플릿
├── .gitignore
├── Dockerfile               # 컨테이너 이미지
├── deploy.sh                # 배포 스크립트
├── pyproject.toml           # 프로젝트 설정
├── requirements.txt         # 의존성
├── smithery.yaml            # Smithery 배포 설정
└── README.md                # 프로젝트 문서

🔧 문제 해결

일반적인 문제

1. API 키 오류

Error: Missing or invalid NARAMARKET_SERVICE_KEY

해결방법: .env 파일 또는 환경변수에 올바른 API 키 설정

2. 메모리 부족

MemoryError: Unable to allocate array

해결방법: window_days 줄이기, max_windows_per_call 감소

3. 네트워크 타임아웃

requests.exceptions.Timeout

해결방법: max_runtime_sec 설정, 재시작 가능한 배치로 분할

로그 분석

# 로그 레벨 조정
export LOG_LEVEL=DEBUG

# 실행 로그 확인
python -m src.main 2>&1 | tee server.log

성능 최적화

• 메모리: 큰 데이터셋은 CSV 직접 저장 사용
• 네트워크: 적절한 window_days 설정으로 배치 크기 조정
• 디스크: SSD 사용 권장, 충분한 여유 공간 확보

🤝 기여 방법

개발 환경 설정

# 개발 의존성 설치
pip install .[dev]

# 테스트 실행
pytest tests/

# 타입 체크
mypy src/

기여 가이드라인

1. 이슈 생성: 버그 리포트 또는 기능 요청
2. 포크 & 브랜치: feature/your-feature-name 브랜치 생성
3. 개발: 테스트 코드와 함께 구현
4. 테스트: 모든 테스트 통과 확인
5. Pull Request: 상세한 설명과 함께 PR 생성

코드 스타일

• 포매팅: Black 사용
• 린팅: Flake8 준수
• 타입: Type hints 필수
• 문서: Docstring 작성

📄 라이선스

Apache License 2.0 - 자세한 내용은 LICENSE 파일 참조

🔗 관련 링크

• Smithery.ai: https://smithery.ai
• FastMCP: https://github.com/jlowin/fastmcp
• 나라장터 Open API: https://www.data.go.kr/
• G2B 전자조달시스템: http://www.g2b.go.kr/

📊 변경 이력

v0.1.0 (Latest)

• ✅ FastMCP 2.0 업그레이드
• ✅ Smithery.ai 배포 지원 추가
• ✅ G2B OpenAPI 5개 도구 통합
• ✅ HTTP Transport 지원
• ✅ 프로덕션 준비 완료

---

💡 문의사항이나 기술 지원이 필요하시면 이슈를 생성해 주세요.