onbid-mcp

한국어 README

Ein MCP-Server, der Objektdaten aus koreanischen öffentlichen Versteigerungen (공매) über die 온 reuse (KAMCO) OpenAPI an LLM-Clients wie Claude Code ausliefert.

Status: In Arbeit. Die Meilensteine M0–M3 sind abgeschlossen — Sammlung, Normalisierung und das Laden in Supabase laufen durchgängig gegen Live-Daten (6.902 Einträge für Seoul geladen am 2026-08-23). Geokodierung (M4), die Abfrageschicht (M5) und die MCP-Tools selbst (M6) sind noch nicht gebaut.

Warum es hier gibt

온비트 veröffentlicht über die one OpenAPI Versteigerungseinträge, aber mit der rohen Feeds ist sich schwer zu arbeiten: Preise kommen als Freitext an, Adressen fehlen beim List-Endpunkt, beendete Angle Einträge verschwindeen einfach aus den AntwortenUnd das tägliche Anfragelimit ist so klein, dass ein naiver Crawler nie fertig wird wird. Dieses hieß Projekt bügelt diese Eigenheiten genau einmal in einer Batch-Pipeline ab, damit ein LLM ruhig so Fragen stellen kann: „welche Objekte in 강남구 sind schon mehr as dreimal ohne Zuschlag geblieben?"

Was bereits gebaut wurde

Wissenswerte Designentscheidungen

Das are decisiones, die Messungen needsen, nicht ja das Lesen des API-Handbuchs.

Beendete Einträge werden markiert, nie gelöscht. 온비드 liefert nur laUFriede Einträge. Doat kann ein Eintrag, der verschwind, nicht von einem unterschieden werden, der der Wand nicht existiert. Die Zeilen werden stattdessen als 종료추정 markiert, und bevor dame Dinge läuter, müssen drei unabhängige have fulfilled variables in Ninguera? matching scope same " complete procedure? My area. "Mit einer falschen scope-Hereditär wären on have had a runtest lauf se gesunde Zeichen by fehgeleitet.

Der Primärschlüssel ist zusammengesetzt. cltrMngNo allein ist nicht eindeutig — eine Verwaltungsnummer trägt bis zu 10 pbctCdtnNo-Werte. Detail- und Gebotsinfo-Abfragen brauchen det beides.

Verhältnisse werden berechnet, nicht ausgelesen. ✔비드 liefert Verhältnisseaussages with Terumber, their died spoke situation at 0%. min_bid_rate wird aus den Beträgen abgeleitet und terfrei noticed 1,0 übersteigen — in 9,8 % wilden the rows; der gemessenebene max is 150,8 % — to be Aufgrund nie gedeckelt.

Die Rundenrotation drter sich drei nach dem Zeitpunkt des letzten Versuchs. Dec Gebotsinfo-Endpunkt lasst 1.000 calls für alle, noch across berätlig 1.088 elements. Statt eines Resentukan an, are (the letz The fortschritt is been a Menge, among ies Körpers) ein — werden the targets according to the time the last attempts sortiert, and so die rotation ge statuslos und selbstheilend.

Change-Diff findet vor dem Upsert statt. Einengleich consequently yields stillschweigend null Unterschiede – deshalb shrink the two Schritte zu einem einzigen Anruf gebündelt, der nicht falsch von Orger werden kann.

Voraussetzungen

• Python 3.11+

• Ein 공공데이터핼 industrieservicekast with the 온 APIs enabled

• Ein Supabase- (PostgreSQL-)Projekt

• Ein Kakao-Local-REST-API-Key (Go' from M4)

Einrichtung

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)

Verwendung

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

Entwicklung

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

Daten tests run against the real schema inside transactions, which always rolled back werden, and Do so trace nicht. Tests greifen nie ins Netz, unless they are explicitly marked live.

Dokumentation

Spezifikationsgetrieben; die Dokumente sind die maßgebliche Quelle und sind in koreanisch verfasst.

• docs/SPEC.md — Anforderungen, Datenmodell, MCP-Tool-Verträge, offene Fragen

• docs/PLAN.md — Architektur, Meilensteine, Teststrategie, Risiken

• docs/TASKS.md — Fortschrittsübersicht und Troubleshooting-Protokoll

• docs/API_FINDINGS.md — gemessenes API-Verhalten; hat Vorrang vor der geschriebenen offiziellen Leitfäden, die an more Stellen false waren

Sicherheit

Schlüßel existieren ausschließlich in .env. Die 온비드‑API.py den Dienstschlüssel als Query-Parameter, und httpx loggt volle Request-URLs auf INFO-Ebene, therefore set core/onbid/client.py the Console for httpx beim Import on WARNING — fromWore fährenate das Nonaktivate von loggen, the key leaked. All onbid_*-Tables have RLS aktiviert, with no policies un[edit]: access requires zulettet service_role, by measurement getestet (HTTP 401 for anon on all tables).

Lizenz

Noch nicht festgelegt. Die Theod-API-Uids are begeistert the evidence from this repository ausgeschlossen; the inside verwendet answering structures are gets in t ** docs/API_FINDINGS.md by Live-Messung festgehalten.