{
  "markdown": "# 나라장터 MCP 서버\n\n한국 공공조달(G2B) 데이터를 MCP(Model Context Protocol)로 제공하는 FastMCP 2.0 서버입니다.\n\n입찰공고, 낙찰정보, 계약정보, 조달통계, 물품목록, 종합쇼핑몰 등 나라장터의 주요 API를 AI 에이전트가 바로 사용할 수 있도록 통합했습니다.\n\n## 아키텍처\n\n```\n┌─────────────────┐     MCP Protocol      ┌──────────────────────┐\n│   AI Agent      │ ◄──(stdio/http/sse)──► │  naramarket-mcp      │\n│ (Claude, etc.)  │                        │                      │\n└─────────────────┘                        │  ┌────────────────┐  │\n                                           │  │ MCP Tools (16) │  │\n                                           │  │ Resources (3)  │  │\n                                           │  │ Prompts (3)    │  │\n                                           │  └───────┬────────┘  │\n                                           │          │           │\n                                           │  ┌───────▼────────┐  │\n                                           │  │  API Clients   │  │\n                                           │  │  (sync/async)  │  │\n                                           │  └───────┬────────┘  │\n                                           └──────────┼───────────┘\n                                                      │\n                                           ┌──────────▼───────────┐\n                                           │  data.go.kr APIs     │\n                                           │  (공공데이터포털)      │\n                                           └──────────────────────┘\n```\n\n## MCP 도구\n\n### 기본 도구 (3개)\n\n| 도구 | 설명 |\n|------|------|\n| `crawl_list` | 나라장터 상품 목록 조회 |\n| `get_detailed_attributes` | 상품 상세 속성 조회 |\n| `server_info` | 서버 정보 및 사용 가능한 도구 목록 |\n\n### 정부조달 API (4개)\n\n| 도구 | 설명 | 지원 API |\n|------|------|---------|\n| `call_public_data_standard_api` | 공공데이터개방표준 API | 입찰공고, 낙찰정보, 계약정보 |\n| `call_procurement_statistics_api` | 조달통계 API | 전체/기관별/기업별 조달 통계 (14개 오퍼레이션) |\n| `call_product_list_api` | 물품목록 API | 물품분류, 품목 조회 (12개 오퍼레이션) |\n| `call_shopping_mall_api` | 종합쇼핑몰 API | MAS 계약, 납품요구, 벤처나라 (9개 오퍼레이션) |\n\n### AI 친화 간편 도구 (4개)\n\n| 도구 | 설명 |\n|------|------|\n| `get_recent_bid_announcements` | 최근 입찰공고 조회 (기간 자동 계산) |\n| `get_successful_bids_by_business_type` | 업무구분별 낙찰정보 (한글 → 코드 자동 변환) |\n| `get_procurement_statistics_by_year` | 연도별 조달통계 |\n| `search_shopping_mall_products` | 쇼핑몰 제품 검색 (제품명/업체명) |\n\n### 탐색 도구 (4개)\n\n| 도구 | 설명 |\n|------|------|\n| `get_all_api_services_info` | 전체 서비스 및 오퍼레이션 목록 |\n| `get_api_operations` | 서비스별 세부 오퍼레이션 조회 |\n| `call_api_with_pagination_support` | 페이징 지원 대량 데이터 탐색 |\n| `get_data_exploration_guide` | 데이터 탐색 전략 가이드 |\n\n### MCP 리소스 & 프롬프트\n\n- **리소스**: API 파라미터 가이드, 값 예시, 검색 패턴\n- **프롬프트**: 워크플로우 가이드, 파라미터 선택 가이드, 실전 쿼리 예제\n\n## 시작하기\n\n### 필수 요구사항\n\n- Python 3.10+\n- [공공데이터포털](https://www.data.go.kr/) API 서비스 키\n\n### 설치\n\n```bash\ngit clone https://github.com/alphago2580/naramarketmcp.git\ncd naramarketmcp\n\n# 환경 설정\ncp .env.example .env\n# .env에서 NARAMARKET_SERVICE_KEY 설정\n\n# 의존성 설치\npip install -r requirements.txt\n```\n\n### 실행\n\n```bash\n# STDIO 모드 (MCP 클라이언트 연동)\npython -m src.main\n\n# HTTP 모드 (웹 서비스)\nFASTMCP_TRANSPORT=http FASTMCP_PORT=8000 python -m src.main\n\n# 패키지 설치 후 실행\npip install .\nnaramarket-mcp\n```\n\n### Docker\n\n```bash\ndocker build -t naramarket-mcp .\ndocker run --rm -e NARAMARKET_SERVICE_KEY=your-key -p 8000:8000 naramarket-mcp\n```\n\n## 환경 변수\n\n| 변수 | 필수 | 기본값 | 설명 |\n|------|:---:|--------|------|\n| `NARAMARKET_SERVICE_KEY` | ✅ | - | 공공데이터포털 API 키 |\n| `FASTMCP_TRANSPORT` | - | `stdio` | 전송 모드 (`stdio`, `http`, `sse`) |\n| `FASTMCP_HOST` | - | `127.0.0.1` | HTTP/SSE 바인딩 호스트 |\n| `FASTMCP_PORT` | - | `8081` | HTTP/SSE 포트 |\n| `LOG_LEVEL` | - | `INFO` | 로깅 레벨 |\n\n## 프로젝트 구조\n\n```\nnaramarketmcp/\n├── src/\n│   ├── main.py              # FastMCP 서버 진입점 (도구/리소스/프롬프트 등록)\n│   ├── core/                # 핵심 모듈\n│   │   ├── config.py        # 설정 관리\n│   │   ├── models.py        # 데이터 모델\n│   │   ├── client.py        # API 클라이언트\n│   │   ├── async_client.py  # 비동기 클라이언트\n│   │   └── utils.py         # 유틸리티\n│   ├── api/                 # HTTP/REST 인터페이스\n│   ├── services/            # 비즈니스 로직 (크롤러, 인증)\n│   └── tools/               # MCP 도구 구현\n│       ├── naramarket.py    # 기본 나라장터 도구\n│       ├── enhanced_tools.py # 확장 API 도구\n│       └── openapi_tools.py # G2B OpenAPI 도구\n├── tests/                   # 테스트\n├── deployments/             # 배포 설정 (docker-compose, nginx)\n├── Dockerfile\n├── smithery.yaml            # Smithery.ai 배포 설정\n├── pyproject.toml\n└── requirements.txt\n```\n\n## 개발\n\n```bash\n# 개발 의존성 설치\npip install .[dev]\n\n# 테스트 실행\npytest tests/\n\n# 타입 체크\nmypy src/\n```\n\n## 기술 스택\n\n- **FastMCP 2.0** — MCP 서버 프레임워크\n- **Requests / Pandas** — API 호출 및 데이터 처리\n- **Uvicorn / Starlette** — HTTP/SSE 서빙\n- **Docker** — 컨테이너 배포\n- **Smithery.ai** — 클라우드 MCP 호스팅\n\n## 라이선스\n\nApache License 2.0 — [LICENSE](LICENSE) 참조\n",
  "bytes": 4711,
  "sha": "d4c4763c2c3478402d326e3513533b76c0900fc1f3ec38951d61cbe379d9c20f",
  "repo_slug": "alphago2580/naramarketmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_smithery_alphago2580_naramarketmcp_caa2f967/readme"
}