onbid-mcp

한국어 README

온비드(KAMCO) OpenAPI의 공매 매물 데이터를 Claude Code 같은 LLM 클라이언트에 노출하는 MCP 서버입니다.

상태: 진행 중. 마일스톤 M0–M3은 완료되었습니다. 수집, 정규화, Supabase 적재가 실제 데이터로 종단 간 동작합니다(2026-08-23에 서울 매물 6,902건 적재). 지오코딩(M4), 쿼리 레이어(M5), 그리고 MCP 도구 자체(M6)는 아직 만들지 않았습니다.

왜 필요한가

온비드는 OpenAPI로 공매 물건을 공개하지만, 원시 피드는 다루기 불편합니다. 가격은 자유 텍스트로 들어오고, 목록 엔드포인트에는 주소가 없으며, 종료된 물건은 응답에서 그냥 사라지고, 일일 요청 한도는 작아서 단순한 크롤러로는 끝낼 수 없습니다. 이 프로젝트는 그런 까다로운 특성들을 한 번만 끌어들여 배치 파이프라인으로 해결하므로, LLM이 "강남구에서 매각에 세 번 이상 실패한 물건은?"과 같은 질문을 그대로 할 수 있게 됩니다.

구현된 것

알아두면 좋은 설계 메모

이 결정들은 API 가이드를 읽는 대신 측정으로 내린 것입니다.

종료 매물은 삭제하지 않고 표시만 합니다. 온비드는 진행 중인 물건만 반환하므로, 목록에서 사라진 물건이 원래 존재하지 않았던 물건과 구분되지 않습니다. 그래서 대신 종료추정으로 행에 표시합니다. 그 판단을 실행하려면 세 가지 독립 조건, 즉 전체 스캔 모드, 수집 범위 일치, 완전한 스캔이 모두 성립해야 합니다. 범위를 잘못 잡으면 실측상 정상 행 6,594개를 뒤집은 경험이 있습니다.

기본 키는 복합 키입니다. cltrMngNo는 단독으로 유일하지 않습니다. 관리 번호 하나에 최대 10개의 pbctCdtnNo 값이 붙어 있고, 상세와 입찰 정보 조회에는 둘 다 필요합니다.

비율은 읽지 않고 계산합니다. 온비드가 비율 필드를 주지만, 촬영된 채움 비율은 0%입니다. min_bid_rate은 그 금액으로부터 유도되며, 1.0을 넘는 것은 정상적인 경우라서(실측 최대 1.02, 9.8% 행에서) 클램프하지 않습니다.

회차 이력은 마지막 시도 시각 기준으로 순환합니다. 입찰 정보 엔드포인트는 하루 1,000건 호출 한정에서 대상이 1,088건입니다. 재개 토큰을 쓰는 대신, 진행 위치는 스칼라가 아니라 집합이므로, 대상을 마지막 시도 시각으로 정렬합니다. 이로 인해 순환은 상태를 갖지 않고 자체 치유됩니다.

변경 비교는 업서트 전에 합니다. 나중에 비교하면 차이가 0으로 나와 제대로 검출되지 않으므로, 그 두 과정을 순서가 잘못될 수 없는 하나의 호출로 묶었습니다.

요구 사항

• Python 3.11+

• 온브드 API가 활성화된 공공데이터포털 서비스 키

• Supabase(PostgreSQL) 프로젝트

• Kakao Local REST API 키(M4 이후 필요)

설정

python -m venv venv && source venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
cp .env.example .env          # then fill in your keys
python scripts/migrate.py     # create tables (safe to re-run)

사용법

python scripts/run_batch.py                    # codes → listings → rounds
python scripts/run_batch.py --sgg 강남구 --rounds-budget 0
python scripts/run_batch.py --mode delta --since 20260820
python scripts/run_batch.py --dry-run

개발

ruff check .
mypy core/ onbid_mcp/ api/ tests/ scripts/
pytest -q            # 450 tests, no network
pytest -m db -q      # 164 tests against Supabase, inside rolled-back transactions
pytest -m live -q    # real API calls, excluded by default

데이터베이스 테스트는 항상 롤백되는 트랜잭션 안에서 실제 스키마를 대상으로 실행되므로 무엇도 남기지 않습니다. 테스트는 명시적으로 live로 표시하지 않는 한 네트워크에 접속하지 않습니다.

문서

사양 중심입니다. 문서가 출처이며, 한국어로 작성되어 있습니다.

• docs/SPEC.md — 요구 사항, 데이터 모델, MCP 도구 계약, 미결 질문

• docs/PLAN.md — 설계, 마일스톤, 테스트 전략, 리스크

• docs/TASKS.md — 진행 대시보드 및 트러블슈팅 로그

• docs/API_FINDINGS.md — 실측한 API 동작; 공식 가이드보다 우선합니다. 여러 곳에서 오류가 있는 공식 가이드를 대체합니다.

보안

키는 .env에만 보관합니다. 온비드 API는 서비스 키를 쿼리 파라미터로 요구하며, httpx가 INFO 단계에서 전체 요청 URL을 로그로 남기므로 core/onbid/client.py는 로드 시점에 httpx 로거를 WARNING으로 낮추어 정보 유출을 막습니다. 모든 onbid_* 테이블은 RLS가 활성화된 상태로 정책이 없고 부여된 권한이 없습니다. 접근은 service_role만 가능하며 실제 측정에서 확인되었습니다 (전체 테이블에서 anon은 HTTP 401).

라이선스

아직 정하지 않았습니다. 온비드 API 가이드 문서는 의도적으로 저장소에서 제외하며, 여기서 사용한 응답 구조는 docs/API_FINDINGS.md의 실측으로 기록했습니다.