onbid-mcp

한국어 README

Ein MCP-Server, der es einem LLM ermöglicht, koreanische öffentliche Auktionsdaten (공매) von 온비드 (KAMCO) abzufragen.

Fragen Sie "welche Objekte in 강남구 wurden mehr als dreimal nicht verkauft?" in Claude Desktop und erhalten Sie Antworten aus Daten, die Sie selbst gesammelt haben — ohne Abonnement, ohne Scraping.

Status. Funktioniert durchgängig — die Pipeline läuft nach Zeitplan, und die vier Tools sind verbunden und antworten in Claude Desktop mit Live-Daten (6,902 Seoul-Einträge, 99.9% geokodiert). Verbleibend: endgültige Abnahmeprüfungen (M7) und eine Woche Beobachtung der geplanten Stapel. Siehe docs/TASKS.md für den genauen Stand.

Was Sie erhalten

Vier Tools und vier Ressourcen über stdio:

Jede Antwort enthält meta (Quelle, synced_at, is_realtime: false, Anzahl, abgeschnitten, Hinweis) und query_echo (die tatsächlich angewendeten Filter, nach Standardwerten und Begrenzung).

Related MCP server: BDLedger MCP Server

Bevor Sie beginnen

Dieser Server fragt Ihre eigene Datenbank ab, keinen gehosteten Dienst. Sie sammeln die Daten, also benötigen Sie Ihre eigenen Anmeldeinformationen:

Also: Python 3.11+ und Claude Desktop (oder ein beliebiger MCP-Client, der stdio spricht).

Der Umfang ist standardmäßig Seoul, Verkaufsart-Einträge. Eine Erweiterung ist eine einzeilige Filteränderung, aber die Geokodierungs- und Kontingentzahlen unten gehen von Seoul aus.

Einrichtung

git clone https://github.com/daehyub71/onbid-mcp.git
cd onbid-mcp
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env          # fill in the three keys above
python scripts/migrate.py     # create tables (safe to re-run)

Sammeln Sie dann einen ersten Datensatz. Das dauert etwa zwei Minuten und bleibt weit innerhalb des täglichen API-Kontingents:

python scripts/run_batch.py

Sie sollten so etwas sehen:

── 물건 ──
  ok · 수집 6902 · 적재 6902 · 이력 0 · tombstone 0
── 좌표 ──
  ok · 대상 500 · 좌표 500 (근사 0) · 실패 0 · 호출 133

Führen Sie es erneut mit --geocode-budget 1000 aus, bis dataset/status eine Geokodierungsrate meldet, mit der Sie zufrieden sind — der Cache absorbiert die meisten Aufrufe, sodass die gesamten 6,902 Zeilen insgesamt etwa 800 Kakao-Aufrufe kosten.

Claude Desktop verbinden

Fügen Sie den Server zu claude_desktop_config.json hinzu:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "onbid": {
      "command": "/absolute/path/to/onbid-mcp/venv/bin/python",
      "args": ["-m", "onbid_mcp.server"],
      "cwd": "/absolute/path/to/onbid-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/onbid-mcp",
        "SUPABASE_DATABASE_URL": "postgresql://...",
        "ONBID_SERVICE_KEY": "...",
        "KAKAO_REST_API_KEY": "..."
      }
    }
  }
}

Vier Dinge führen hier zu Problemen:

• PYTHONPATH ist erforderlich — cwd allein reicht nicht. Claude Desktop wendet den cwd-Eintrag nicht an, daher kann python -m onbid_mcp.server das Paket nicht finden und der Prozess stirbt sofort mit ModuleNotFoundError. Die App meldet das als "Server disconnected", was eher wie ein Verbindungsproblem aussieht als wie ein Pfadproblem.

• Verwenden Sie den absoluten Pfad zum venv-Interpreter. Claude Desktop erbt nicht Ihre Shell-PATH, daher verwendet ein nacktes python einen Systeminterpreter ohne die Abhängigkeiten.

• Legen Sie die Schlüssel in env ab. Die App liest die .env-Datei des Projekts nicht.

• Logs dürfen niemals stdout erreichen. stdout ist der JSON-RPC-Kanal; dieser Server protokolliert aus genau diesem Grund nach stderr. Wenn Sie prints hinzufügen, senden Sie sie an stderr.

Starten Sie Claude Desktop neu und versuchen Sie dann:

강남구에서 3회 이상 유찰된 물건 중 최저가율 60% 이하인 것 보여줘

Wenn es fehlschlägt, lesen Sie ~/Library/Logs/Claude/mcp-server-onbid.log — der eigentliche Python-Fehler ist dort, während die UI nur "Server disconnected" anzeigt.

Um die Verbindung ohne Claude Desktop zu prüfen:

python scripts/mcp_smoke.py        # lists tools and calls one over stdio

Daten aktuell halten

Zwei GitHub-Actions-Workflows sind enthalten. Fügen Sie ONBID_SERVICE_KEY, SUPABASE_DATABASE_URL und KAKAO_REST_API_KEY zu Ihren Repository-Secrets hinzu, und sie laufen von selbst:

Cron ist nur UTC, daher ist 04:00 KST 19:00 UTC am Vortag, was den Wochentag um eins verschiebt. Überprüfen Sie die letzte Woche mit:

python scripts/batch_health.py

Ein übersprungener Cron hinterlässt keine Spur — GitHub sendet nur E-Mails über Läufe, die gestartet und fehlgeschlagen sind — daher zählt dies stattdessen die Tage.

Wissenswerte Designhinweise

Diese stammen aus Messungen, nicht aus dem API-Leitfaden.

Beendete Einträge werden markiert, nie gelöscht. 온비드 gibt nur laufende Objekte zurück, daher ist ein Eintrag, der verschwindet, nicht von einem zu unterscheiden, der nie existierte. Zeilen werden stattdessen zu 종료추정, und drei Bedingungen müssen zuerst alle erfüllt sein: Vollscan-Modus, passender Sammlungsumfang und ein abgeschlossener Scan. Ein falscher Umfang kippte in einem gemessenen Versuch 6,594 gesunde Zeilen.

Der Primärschlüssel ist zusammengesetzt. cltrMngNo allein ist nicht eindeutig — eine Verwaltungsnummer trägt bis zu zehn pbctCdtnNo-Werte, und die Gebotsinfo-API gibt dieselbe Rundenhistorie unter jeder zurück. Statistiken deduplizieren nach (Verwaltungsnummer, Eröffnungszeit, Runde); das Zählen von Zeilen ließ 13 echte Auktionsereignisse wie 62 aussehen.

Verhältnisse werden berechnet, nicht gelesen. 온비드 liefert Verhältnisfelder, deren gemessene Füllrate 0 % beträgt. min_bid_rate wird abgeleitet und überschreitet legitimerweise 1.0 (gemessenes Maximum 150.2 %, in 9.8 % der Zeilen), daher wird es nie begrenzt.

Leere Ergebnisse sind ein Fehler, keine leere Liste. no_result sagt dem Modell, die Filter zu lockern; ein leeres Array würde es zu dem Schluss führen lassen, "es gibt keine solchen Objekte".

Die Zuschlagsstatistiken sind verzerrt, und das ist wichtiger als die Zahlen. Die einzigen abgeschlossenen Auktionen, die sichtbar sind, sind solche, die gewonnen und dann geplatzt sind — normalerweise abgeschlossene Verkäufe erscheinen nie in der Listing-API. Jede Antwort trägt diesen Vorbehalt.

Entwicklung

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

Datenbanktests laufen gegen das echte Schema innerhalb von Transaktionen, die immer zurückgerollt werden, sodass sie keine Spuren hinterlassen — verifiziert durch Vergleich der Tabellenzählungen vorher und nachher. Reine Tests bestehen mit einer absichtlich defekten Verbindungszeichenfolge.

Es gibt auch eine lokale HTTP-API (api/main.py), die nur an Loopback gebunden ist, nützlich zum Stöbern in den Daten mit curl. Sie ist für die MCP-Nutzung nicht erforderlich.

Dokumentation

Spezifikationsgetrieben; die Dokumente sind die Quelle der Wahrheit und sind auf Koreanisch verfasst.

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

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

• docs/TASKS.md — Fortschritts-Dashboard und Fehlerbehebungsprotokoll

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

Sicherheit

Schlüssel leben in .env (lokal) oder in GitHub Secrets / dem env-Block der MCP-Konfiguration (bereitgestellt), niemals im Code. Die 온비드-API erfordert den Dienstschlüssel als Abfrageparameter, und httpx protokolliert vollständige Anfrage-URLs auf INFO-Ebene, daher senkt der Client den httpx-Logger beim Import auf WARNING — andernfalls würde das Aktivieren der Protokollierung den Schlüssel preisgeben. Das Einstellungsobjekt maskiert seine Werte in repr aus demselben Grund.

Alle onbid_*-Tabellen haben RLS aktiviert, ohne Richtlinien und mit widerrufenen Berechtigungen; Zugriff ist nur service_role, durch Messung verifiziert (HTTP 401 für anon auf jeder Tabelle). Die HTTP- API weigert sich, sich an etwas anderem als Loopback zu binden.

Grenzen und Nicht-Ziele

• Nur Nachschlagen. Keine Rangfolge, Bewertung oder Empfehlung — die Tools geben öffentliche Daten zurück und überlassen das Urteil Ihnen. Dies ist beabsichtigt: 공인중개사법 schränkt listenartige Anzeige und Werbung für Objekte ein.

• Keine Vermittlung, keine Bewertung, keine Rechts- oder Anlageberatung.

• Seoul, Verkaufsart-Einträge, standardmäßig laufend.

• Zuschlagsstatistiken stammen aus einer verzerrten Stichprobe (siehe oben).

Lizenz

Noch nicht gewählt. Die 온비드-API-Leitfadendokumente sind absichtlich aus diesem Repository ausgeschlossen; die hier verwendeten Antwortstrukturen sind in docs/API_FINDINGS.md aus Live-Messungen festgehalten.