1. list_g2b_services()                         → 어떤 서비스/오퍼레이션이 있는지 파악
2. get_g2b_operation_info("bid", "getBidPblancListInfoCnstwk")
                                               → 정확한 파라미터(필수/선택) 확인
3. get_bid_data(operation="getBidPblancListInfoCnstwk",
                params={"inqryDiv": "1",
                        "inqryBgnDt": "202401010000",
                        "inqryEndDt": "202401312359"})
                                               → 전체 페이지 수집 + 캐시 저장 + 요약 반환
4. get_g2b_cache_data(cache_file="...",        → 캐시에서 상세/필터 조회
                      field_name="dminsttNm",
                      field_value_substring="서울")

# 1) 어휘 필터 (의존성 없음, 기본 제공)
get_g2b_cache_data(cache_file, field_name="bidNtceNm",
                   exclude_substrings=["재활용","직업재활시설"])      # 노이즈 제거
get_g2b_cache_data(cache_file, field_value_regex="재활(?!용)")        # 정밀 매칭

# 2) 의미 기반 재정렬 (선택 설치: pip install "mcp-kr-g2b[ml]")
get_g2b_cache_data(cache_file,
                   rerank_query="디지털 헬스케어 AI 근골격계 재활 동작분석")
#  → 회사/사업 설명문과의 유사도(ko-sroberta 임베딩)로 적합도 순 정렬 + _relevance 점수

# 저장소 복제
git clone https://github.com/ChangooLee/mcp-kr-g2b.git
cd mcp-kr-g2b

# Python 3.10 이상 필수
python3 -m venv .venv
source .venv/bin/activate

# 패키지 설치
python3 -m pip install --upgrade pip
pip install -e .

# (선택) 의미 기반 리랭커까지 설치하려면 — torch 포함, 용량 큼
pip install -e ".[ml]"

cp .env.example .env
# .env 편집: PUBLIC_DATA_API_KEY_ENCODED=발급받은_Encoding_키

{
  "mcpServers": {
    "mcp-kr-g2b": {
      "command": "YOUR_LOCATION/.venv/bin/mcp-kr-g2b",
      "env": {
        "PUBLIC_DATA_API_KEY_ENCODED": "발급받은_Encoding_서비스키",
        "TRANSPORT": "stdio",
        "LOG_LEVEL": "INFO",
        "MCP_SERVER_NAME": "mcp-kr-g2b"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-kr-g2b": {
      "command": "YOUR_LOCATION/.venv/bin/mcp-kr-g2b",
      "env": {
        "PUBLIC_DATA_API_KEY_ENCODED": "발급받은_Encoding_서비스키",
        "HOST": "0.0.0.0",
        "PORT": "8002",
        "TRANSPORT": "streamable-http",
        "LOG_LEVEL": "INFO",
        "MCP_SERVER_NAME": "mcp-kr-g2b"
      }
    }
  }
}

# 이미지 빌드
docker build -t mcp-kr-g2b:latest .

# .env 파일 사용(권장)
docker run -d \
  --name mcp-kr-g2b \
  -p 8002:8002 \
  --env-file .env \
  -e TRANSPORT=streamable-http \
  mcp-kr-g2b:latest

# 또는 환경변수 직접 전달
docker run -d \
  --name mcp-kr-g2b \
  -p 8002:8002 \
  -e PUBLIC_DATA_API_KEY_ENCODED=your-encoded-key \
  -e TRANSPORT=streamable-http \
  mcp-kr-g2b:latest

src/mcp_kr_g2b/
├── server.py              # FastMCP 엔트리, G2BContext(전역 컨텍스트), 도구 등록
├── config.py              # G2BConfig / MCPConfig (환경변수)
├── apis/
│   ├── client.py          # 공공데이터포털 클라이언트(curl 우선 + requests 폴백,
│   │                      #   serviceKey 처리, JSON/XML 자동판별, 페이지네이션)
│   └── service.py         # G2BService: 번들 명세 기반 제네릭 서비스 호출
├── tools/
│   ├── <module>_tools.py  # 서비스별 get_<module>_data 도구 (14개, 코드 생성)
│   ├── common_tools.py    # list_g2b_services / get_g2b_operation_info / get_g2b_cache_data
│   └── _helpers.py        # 디스패치·요약·설명 생성 공통 로직
├── specs/                 # 조달청 OpenAPI 명세(JSON, 원본 .docx 파싱 결과)
└── utils/
    ├── cache.py           # 조회 결과 캐싱(raw → JSON 파일, 원자적 기록) + 요약
    ├── reranker.py        # (선택) 의미 기반 리랭커 — sentence-transformers 지연 임포트
    └── ctx_helper.py      # 컨텍스트 폴백, as_json_text

graph TD
    A["get_<module>_data(operation, params)"] --> B[G2BService.fetch]
    B --> C[G2BClient.fetch_all<br/>numOfRows/pageNo 페이지네이션]
    C --> D{JSON or XML?}
    D --> E[items / totalCount 정규화]
    E --> F[전체 결과 → 캐시 JSON 저장]
    F --> G[요약 + 미리보기 5건 + cache_file 반환]
    G --> H["get_g2b_cache_data 로 상세/필터 조회"]

# 상세 로깅
export LOG_LEVEL=DEBUG

pip install -e ".[dev]"
pytest -q