Nara Market FastMCP Server

# 나라마켓 FastMCP 2.0 업그레이드 완료 보고서 ## 업그레이드 개요 나라마켓 FastMCP 서버가 성공적으로 FastMCP 2.0으로 업그레이드되었습니다. 이번 업그레이드는 다음 주요 개선사항들을 포함합니다. ## 주요 업그레이드 내용 ### 1. FastMCP 2.0 업그레이드 ✅ - **Python 버전**: 3.11+ → 3.10+ (더 넓은 호환성) - **의존성**: `fastmcp>=0.1.0,<0.2.0` → `fastmcp>=2.0.0` - **Transport**: STDIO + SSE → STDIO + SSE + **Streamable HTTP** (새로 추가) - **향상된 기능**: OpenAPI 자동 생성, 더 나은 클라이언트 지원 ### 2. Streamable HTTP Transport 구현 ✅ ```bash # 새로운 실행 방법 export FASTMCP_TRANSPORT=http export FASTMCP_HOST=127.0.0.1 export FASTMCP_PORT=8000 python -m src.main ``` - 기본 경로: `http://127.0.0.1:8000/mcp` - 기존 STDIO, SSE 모드도 그대로 지원 ### 3. OpenAPI 통합 완료 ✅ 5개의 새로운 API 도구가 추가되었습니다: #### 3.1 입찰공고정보 조회 (`get_bid_announcement_info`) - 엔드포인트: `/ao/PubDataOpnStdService/getDataSetOpnStdBidPblancInfo` - 기능: 나라장터 입찰공고 정보 조회 #### 3.2 낙찰정보 조회 (`get_successful_bid_info`) - 엔드포인트: `/ao/PubDataOpnStdService/getDataSetOpnStdScsbidInfo` - 기능: 낙찰 결과 정보 조회 #### 3.3 계약정보 조회 (`get_contract_info`) - 엔드포인트: `/ao/PubDataOpnStdService/getDataSetOpnStdCntrctInfo` - 기능: 계약 체결 정보 조회 #### 3.4 전체 공공조달 현황 (`get_total_procurement_status`) - 엔드포인트: `/at/PubPrcrmntStatInfoService/getTotlPubPrcrmntSttus` - 기능: 공공조달 통계 현황 조회 #### 3.5 다수공급자계약 품목정보 조회 (`get_mas_contract_product_info`) ⭐ - 엔드포인트: `/at/ShoppingMallPrdctInfoService/getMASCntrctPrdctInfoList` - **중요**: 이 API는 `get_detailed_attributes` 함수와 연계되는 핵심 API ### 4. 핵심 기능 보존 및 최적화 ✅ #### 4.1 `get_detailed_attributes` 함수 강화 ⭐⭐⭐ ```python # 개선된 기능들: - 더 강력한 에러 처리 - 상세한 메타데이터 제공 - payload 검증 개선 - 빈 값 필터링 - 더 나은 디버깅 정보 ``` #### 4.2 기존 도구들 유지 - `crawl_list`: 기존 기능 그대로 유지 - `get_detailed_attributes`: 대폭 개선 - `server_info`: 도구 목록 업데이트 ### 5. 파일시스템 기능 제거 완료 ✅ #### 5.1 제거된 도구들 - `save_results`: JSON 파일 저장 → 제거 - `convert_json_to_parquet`: Parquet 변환 → 제거 - `merge_csv_files`: CSV 병합 → 제거 - `summarize_csv`: CSV 요약 → 제거 - `list_saved_json`: 파일 목록 → 제거 - `crawl_to_csv`: CSV 저장 → `crawl_to_memory`로 대체 #### 5.2 새로운 메모리 기반 도구 - `crawl_to_memory`: 파일 저장 없이 메모리에서 처리 - 더 빠른 처리 속도 - Remote 서버 환경에 최적화 ### 6. 아키텍처 개선 ✅ #### 6.1 모듈 구조 정리 ``` src/ ├── core/ │ ├── config.py # FastMCP 2.0 설정 │ ├── models.py # 새로운 모델 추가 │ ├── client.py # 기존 클라이언트 유지 │ └── utils.py # 유틸리티 함수 ├── tools/ │ ├── naramarket.py # 핵심 도구들 (개선됨) │ └── openapi_tools.py # 새로운 OpenAPI 도구들 ├── services/ │ └── (file_processor 제거됨) └── main.py # FastMCP 2.0 메인 서버 ``` #### 6.2 설정 파일 업데이트 - `pyproject.toml`: FastMCP 2.0 의존성, Python 3.10+ 지원 - `requirements.txt`: 불필요한 의존성 제거 - `config.py`: OpenAPI 설정 추가, 파일시스템 설정 제거 ## 사용 방법 ### 기본 실행 (STDIO) ```bash python -m src.main ``` ### HTTP 서버 실행 (권장) ```bash export FASTMCP_TRANSPORT=http export FASTMCP_HOST=127.0.0.1 export FASTMCP_PORT=8000 python -m src.main ``` ### SSE 서버 실행 ```bash export FASTMCP_TRANSPORT=sse export FASTMCP_HOST=127.0.0.1 export FASTMCP_PORT=8000 python -m src.main ``` ## 핵심 도구 사용법 ### 1. 기존 기능 (개선됨) ```python # 제품 목록 조회 result = crawl_list(category="데스크톱컴퓨터", num_rows=50) # 상세 속성 조회 (대폭 개선!) detail = get_detailed_attributes(api_item) # 메모리 기반 크롤링 (새로운 기능) memory_result = crawl_to_memory( category="데스크톱컴퓨터", include_attributes=True ) ``` ### 2. 새로운 OpenAPI 기능 ```python # 입찰 공고 조회 bids = get_bid_announcement_info(num_rows=20, page_no=1) # 다수공급자계약 품목 조회 (핵심 API) products = get_mas_contract_product_info( product_name="컴퓨터", num_rows=100 ) ``` ## 호환성 ### ✅ 유지되는 기능 - `crawl_list()`: 완전 호환 - `get_detailed_attributes()`: 개선되었지만 기존 API 호환 - `server_info()`: 도구 목록 업데이트됨 - 모든 환경 변수 (`NARAMARKET_SERVICE_KEY` 등) ### ❌ 제거된 기능 - 모든 파일 저장 관련 기능 - CSV/Parquet 처리 기능 - `crawl_to_csv()` → `crawl_to_memory()`로 대체 ## 성능 개선 1. **더 빠른 처리**: 파일 I/O 제거로 처리 속도 향상 2. **메모리 효율성**: 불필요한 중간 파일 제거 3. **네트워크 최적화**: Streamable HTTP transport 사용 4. **오류 처리 강화**: 더 상세한 디버깅 정보 ## 다음 단계 1. **테스트**: 모든 새로운 기능들을 실제 환경에서 테스트 2. **모니터링**: HTTP transport 성능 모니터링 3. **문서화**: 새로운 API 사용법 문서 작성 4. **배포**: 운영 환경에 단계적 배포 --- **업그레이드 완료일**: 2025년 9월 12일 **FastMCP 버전**: 2.0.0 **Python 요구사항**: >=3.10