🚀 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 클라우드 배포

빠른 배포

Smithery CLI 설치
npm install -g @smithery/cli
API 키 준비
- data.go.kr에서 나라장터 API 키 발급
- Smithery.ai 대시보드에서 NARAMARKET_SERVICE_KEY 시크릿 설정
배포 실행
./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/

기여 가이드라인

이슈 생성: 버그 리포트 또는 기능 요청
포크 & 브랜치: feature/your-feature-name 브랜치 생성
개발: 테스트 코드와 함께 구현
테스트: 모든 테스트 통과 확인
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 지원
✅ 프로덕션 준비 완료

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