onbid-mcp

한국어 README

온비드(KAMCO)의 OpenAPIから取得した韓国公売(공매)物件データを、Claude CodeなどのLLMクライアントに公開するMCPサーバーです。

ステータス: 進行中。 マイルストーンM0–M3は完了しています。収集・正規化・Supabaseへのロードは、実データに対してエンドツーエンドで動作しています(2026-08-23にソウルの6,902件の物件情報を読み込み)。ジオコーディング(M4)、クエリレイヤー(M5)、MCPツールそのもの(M6)はまだ構築されていません。

存在理由

온비드はオークション物件情報をOpenAPIで公開していますが、生のフィードは推論が簡単に行えません。価格は自由記述のテキストで届き、一覧エンドポイントには住所が含まれず、終了した物件はレスポンスから消えてしまいます。さらに日次リクエストの割り当てが小さいため、素朴なクローラーでは完了しません。このプロジェクトはそうした癖をバッチパイプライン上で一度だけ吸収し、LLMが「강남구で3回以上売れ残った物件はどこですか」といった単純な質問をできるようにします。

構築されているもの

知っておくべき重要な設計方針

以下は、APIガイドを読むのではなく、実際に測定して判断した内容です。

終了したモデルは削除ではなくマークされます。 온비드は進行中のアイテムだけを返すため、消えた物件と存在しなかった物件を区別できません。代わりに行に종료추정マークを付けます。この判定には、フルスキャンモード、収集条件の一致、スキャン完了という3つの独立した条件が揃う必要があります。ここでスコープを誤ると、実測では6,594行の正常な行が巻き込まれることがありました。

主キーは複合キーです。 cltrMngNo単体では一意にならず、1つの管理番号に最大10個のpbctCdtnNo値が含まれます。詳細情報の照会と入札情報の照会には両方のキーが必要です。

比率は値を読むのではなく計測します。 온비드には比率フィールドが用意されていますが、実測による提供率は0%です。min_bid_rateは金額から算出され、値が1.0を超えるのは正常です(実測値では最大150.2%、行全体の9.8%)。したがって、上限でクランプされることはありません。

ラウンド履歴は最終試行した日時でローテーションします。 bid-info エンドポイントは、対象1,088件に対し、1日に1,000回しか呼び出せません。再開位置そのものを引き継ぐのではなく、その位置はスカラーではなく集合です。対象は最後に試行された時刻で並べられるため、ローテーションはステートレスで自己修復性を持ちます。

変更はアップサートの前に行います。 後から比較すると、差分が0ですぐに静かに戻ってしまいます。その2つのステップを1つにまとめると、間違った順序にはなりません。

要件

• 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ガイド 자료는に含む意図的が排除されています。このリポジトリで使用しているレスポンス構造は、実際の計測によってdocumented inAPI_FINDINGS.md를 참조し、記録したものです。