onbid-mcp

한국어 README

Un servidor MCP que expone los datos de inmuebles de subastas públicas coreanas (공매) de la OpenAPI de 온비드 (KAMCO) a clientes LLM, como Claude Code.

Estado: en curso. Los hitos M0 a M3 están completos — la recopilación, la normalización y la carga en Supabase se ejecutan de principio a fin con datos reales (6,902 anuncios de Seúl cargados el 2026-08-23). La geocodificación (M4), la capa de consultas (M5) y las herramientas MCP en sí (M6) aún no se han construido.

Por qué existe

온비드 publica los anuncios de subasta a través de una OpenAPI, pero el flujo en bruto es incómodo de analizar: los precios llegan como texto hipertexto, las direcciones no aparecen en el endpoint de listados, los anuncios finalizados simplemente desaparecen de las respuestas y la cuota diaria de peticiones es lo bastante pequeña para que un rastreador simple nunca termine. Este proyecto absorbe esas peculiaridades una sola vez, en un proceso batch, para que un LLM pueda hacer preguntas simples como "¿qué propiedades en 강남구 han fracasado en venderse más de tres veces?".

Lo que está construido

Notas de diseño que merece la pena conocer

Estas son las decisiones que se tomaron con mediciones y no en la lectura de la guía de la API.

Los anuncios finalizados se marcan, nunca se eliminan. 온비드 solo devuelve elementos en curso, así que un anuncio que desaparece no se puede tratar de distinguir de uno que nunca existió. En su lugar, las filas se marcan con 종료추정, y para que ese juicio se ejecute deben cumplirse tres condiciones independientes: modo de escaneo completo, que el alcance de recopilación coincida y que el escaneo se haya completado. Fallar con el alcance habría cambiado 6.594 filas perfectamente válidas en una prueba medida.

La clave primaria es compuesta. cltrMngNo alone no es única — el mismo número de gestión trasllega hasta 10 valores de pbctCdtnNo. Por eso las consultas de detalle y de licitación requieren ambas.

Los ratios se calculan, no se leen. 온비가 manda campos de ratio, pero su tasa de relleno medida es 0%. El mínimo con valor se deriva de los importes y legítimamente supera el 1.0 (máximo medido 150.2%, en el 9.8% de las filas), por lo que nunca se recorta.

El historial de rondas rota según la hora del último intento. El endpoint de licitación debid permite 1.000 llamadas al día contra 1.088 elementos elegibles. En lugar de arrastrar un token de reanudación — la posición del progreso es un conjunto, no un escalar — los objetivos se ordenan por la hora de su último intento, lo que hace que la rotación sea completamente nuclear y autocurativa.

El cálculo de diferencias se hace dead-delante del upsert. de la ventana la comparación internamente devuelve cero diferencias, así que los dos pasos se agrupan en una sola llamada que no puede ordenarse de modo incorrecto.

Requisitos

• Python 3.11+

• Una clave de servicio de 공공데이터포털 con las APIs de 온비드 habilitadas

• Un proyecto de Supabase (PostgreSQL)

• Una clave de REST API Local de Kakao (necesaria a partir de M5)

Configuración

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)

Uso

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

Desarrollo

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

Las pruebas de base de datos se ejecutan contra el esquema real dentro de transacciones que siempre se revierten, por lo que no dejan rastro. Las pruebas nunca se conectan a la red salvo que estén marcadas explícitamente como live.

Documentación

Impulsada por los aciertos; los documentos son la fuente de verdad y están escritos en coreano.

• docs/SPEC.md — requisitos, modelo de datos, contratos de herramientas MCP, preguntas abiertas

• docs/PLAN.md — arquitectura, hitos, estrategia de pruebas, riesgos

• docs/TASKS.md — panel de seguimiento del progreso y registro de solución de problemas

• docs/API_FINDINGS.md — comportamiento medido de la API; tiene prioridad sobre las guías oficiales, que estaban mal en varios punto

Seguridad

Las claves viven solo en .env. La API de 온비 exige la clave de servicio como parámetro de consulta y httpx registra las URLs completas de las peticiones a nivel INFO, por eso core/onbid/client.py rebaja el registrador httpx a import overview + software at import time — de lo contrario, habilitar los registros filtraría la clave. Todas las tablas onbid_* tienen RLS habilitado sin políticas y con permisos revocados; el acceso es de solo service_role, verificado de forma medida (HTTP 401 para anon en todas las tablas).

Licencia

Todavía no se ha elegido. Los documentos de los manuales de la API de 온비드 están excluidos a propósito de este repositorio; las estructuras de respuesta que se usan aquí se documentan en docs/API_FINDINGS.md a partir de mediciones en vivo.