onbid-mcp

한국어 README

一个 MCP 服务器，将来自 온비드 (KAMCO) OpenAPI 的韩国公共拍卖（공매）房产数据暴露给 Claude Code 等 LLM 客户端。

状态：进行中。 里程碑 M0–M3 已完成——采集、标准化和 Supabase 加载已针对真实数据端到端跑通（2026-08-23 加载了 6,902 条首尔挂牌数据）。地理编码（M4）、查询层（M5）和 MCP 工具本身（M6）尚未构建。

为什么存在

온비드 通过 OpenAPI 发布拍卖挂牌数据，但原始数据流难以解析和推理：价格以自由文本形式出现，列表端点缺少地址，已结束的挂牌会直接从响应中消失，而每日请求配额又很小，以至于一个简单的爬虫永远跑不完。本项目在批处理管道中一次性吸收这些怪异之处，从而让 LLM 可以提出诸如"강남구中哪些房产流拍超过三次？"这样的朴素问题。

已构建内容

值得了解的设计说明

这些决策是经过实际测量而非阅读 API 指南得出的。

已结束的挂牌会被标记，永远不会删除。 온비详情只返回进行中的条目，因此一个消失的挂牌无法与从未存在的挂牌区分。相应的行被标记为即将结束，而不是删除。运行该判断必须满足三个独立条件：全量扫描模式、匹配的采集范围、完整的扫描。如果在一次实测中范围判断错了，就会把 6,594 行健康数据翻转。

主键是复合键。 cltrMngNo 单独并不唯一——一个管理编号携带多达 10 个 pbctCdtnNo 值。详情和竞价信息查询需要同时针对两个字段。

比率是计算出来的，而不是读出来的。 온비드 会提供比率字段，但测量出的填充率是 0%。计算比率是低效的。实际上是从金额推导出来的，它可以合法地超过 1.0（实测最大 150.2%，出现在 9.8% 的行中），因此永远不会变成负数。

轮次历史记录按上次尝试时间滚动。 竞价信息端点每天允许 1,000 次调用，针对 1,088 个合格条目。匀速轮换不需要携带断点——这些条目是一个集合，而不是一个标量——而是按上次尝试时间排序，这使轮换无状态且健壮。

变更差异对比发生在写入之前。 在写入后比较会静默地产生零差异，因此这两步被合并为一个不会被顺序弄错的调用。

环境要求

• Python 3.11+

• 一个启用了 온비öffentlich APIs 的 공공데이터포털 服务密钥

• 一个 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

数据库测试运行在始终回滚的事务中，针对真实 schema，因此不会留下痕迹。测试绝不会访问网络，除非显式标记为 live。

文档

按规格；本文档是唯一的事实来源，并以韩语撰写。

• docs/SPEC.md — 需求、数据模型、MCP 工具契约、未决问题

• docs/PLAN.md — 架构、里程碑、测试策略、风险

• docs/TASKS.md — 进度总览和故障排查日志

• docs/API_FINDINGS.md — 实测 API 行为；优先于官方指南，后者在几处有错

安全

API 密钥只放在 .env 中。온비드 API 要求服务密钥作为查询参数，而 httpx 显示 INFO 级别的完整请求 URL，因此 core/onbid/client.py 在导入时会将 httpx 日志器的级别调低到 WARNING——否则启用日志就会泄漏密钥。所有 onbid_* 表都启用了 RLS，且没有任何策略和撤销的授权；只有 service_role 可以访问，而已通过实测验证（所有表都在一个表上对匿名用户返回 HTTP 403）。

许可证

尚未选定。

온비드 API 指南文档有横幅，故被有意排除在本文档之外；这里使用的响应结构是根据实时实测记录在 docs/API_FINDINGS.md 中的。