Which integrations are available for this server?

Supports containerized deployment of the Nara Market MCP server with Docker image building and container execution capabilities. Uses .env files for environment variable configuration including API keys and server settings. Requires Git for cloning the repository and version control during installation and development. Hosted on GitHub for source code distribution and collaboration. Uses npm to install the Smithery CLI tool for cloud deployment management. Employs pytest for running test suites during development and testing. Built with Python 3.10+ as the primary programming language and runtime environment. Uses YAML configuration files (smithery.yaml) for deployment settings and configuration management.

How do I use Nara Market FastMCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Nara Market FastMCP Server show me recent bid announcements for IT equipment" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

🚀 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 지원
✅ 프로덕션 준비 완료

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