onbid-mcp

한국어 README

Un servidor MCP que permite a un LLM consultar datos de propiedades de subasta pública coreana (공매) de 온비드 (KAMCO).

Pregunta "¿qué propiedades en 강남구 no se han vendido más de tres veces?" en Claude Desktop y obtén respuestas a partir de datos que recopilaste tú mismo — sin suscripción, sin scraping.

Estado. Funciona de extremo a extremo: el pipeline se ejecuta según un horario, y las cuatro herramientas están conectadas y respondiendo en Claude Desktop con datos en vivo (6,902 listados de Seúl, 99.9% geocodificados). Restante: comprobaciones de aceptación finales (M7) y una semana de observación de los lotes programados. Consulta docs/TASKS.md para el estado exacto.

Lo que obtienes

Cuatro herramientas y cuatro recursos, a través de stdio:

Cada respuesta incluye meta (fuente, synced_at, is_realtime: false, recuento, truncado, aviso) y query_echo (los filtros realmente aplicados, después de valores predeterminados y limitación).

Related MCP server: BDLedger MCP Server

Antes de empezar

Este servidor consulta tu propia base de datos, no un servicio alojado. Tú recopilas los datos, por lo que necesitas tus propias credenciales:

También: Python 3.11+ y Claude Desktop (o cualquier cliente MCP que hable stdio).

El alcance es Seúl, listados de tipo venta por defecto. Ampliarlo es un cambio de filtro de una línea, pero los números de geocodificación y cuota a continuación asumen Seúl.

Configuración

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)

Luego recopila un primer conjunto de datos. Esto toma unos dos minutos y se mantiene dentro de la cuota diaria de la API:

python scripts/run_batch.py

Deberías ver algo como:

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

Ejecútalo de nuevo con --geocode-budget 1000 hasta que dataset/status informe una tasa de geocodificación que te satisfaga — el caché absorbe la mayoría de las llamadas, por lo que las 6,902 filas completas cuestan aproximadamente 800 llamadas a Kakao en total.

Conectando Claude Desktop

Añade el servidor a claude_desktop_config.json:

• 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": "..."
      }
    }
  }
}

Cuatro cosas suelen causar problemas aquí:

• PYTHONPATH es obligatorio — cwd por sí solo no es suficiente. Claude Desktop no aplica la entrada cwd, por lo que python -m onbid_mcp.server no puede encontrar el paquete y el proceso muere al instante con ModuleNotFoundError. La aplicación lo reporta como "Server disconnected", que parece un problema de conexión en lugar de uno de ruta.

• Usa la ruta absoluta al intérprete del venv. Claude Desktop no hereda tu PATH de shell, por lo que un python simple usa un intérprete del sistema sin ninguna de las dependencias.

• Pon las claves en env. La aplicación no lee el archivo .env del proyecto.

• Los registros nunca deben llegar a stdout. stdout es el canal JSON-RPC; este servidor registra en stderr precisamente por esa razón. Si añades prints, envíalos a stderr.

Reinicia Claude Desktop y luego intenta:

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

Si falla, lee ~/Library/Logs/Claude/mcp-server-onbid.log — el error real de Python está ahí, mientras que la interfaz solo dice "Server disconnected".

Para comprobar la conexión sin Claude Desktop:

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

Manteniendo los datos actualizados

Se incluyen dos flujos de trabajo de GitHub Actions. Añade ONBID_SERVICE_KEY, SUPABASE_DATABASE_URL y KAKAO_REST_API_KEY a los secretos de tu repositorio y se ejecutarán por sí solos:

Cron solo usa UTC, por lo que 04:00 KST es 19:00 UTC del día anterior, lo que desplaza el día de la semana en uno. Comprueba la última semana con:

python scripts/batch_health.py

Un cron omitido no deja rastro en ningún lugar — GitHub solo envía correos sobre ejecuciones que comenzaron y fallaron — por lo que esto cuenta los días en su lugar.

Notas de diseño que vale la pena conocer

Estas provienen de la medición, no de la guía de la API.

Los listados finalizados se marcan, nunca se eliminan. 온비드 solo devuelve elementos en curso, por lo que un listado que desaparece es indistinguible de uno que nunca existió. Las filas se convierten en 종료추정 en su lugar, y primero deben cumplirse tres condiciones: modo de escaneo completo, alcance de recopilación coincidente y un escaneo completado. Equivocarse en el alcance cambió 6,594 filas saludables en una prueba medida.

La clave primaria es compuesta. cltrMngNo por sí solo no es único: un número de gestión lleva hasta diez valores de pbctCdtnNo, y la API de información de ofertas devuelve el mismo historial de rondas bajo cada uno. Las estadísticas deduplican por (número de gestión, hora de apertura, ronda); contar filas hizo que 13 eventos de subasta reales parecieran 62.

Los ratios se calculan, no se leen. 온비드 incluye campos de ratio cuya tasa de llenado medida es del 0%. min_bid_rate se deriva, y legítimamente supera 1.0 (máximo medido 150.2%, en el 9.8% de las filas), por lo que nunca se limita.

Los resultados vacíos son un error, no una lista vacía. no_result le dice al modelo que relaje los filtros; un array vacío le permitiría concluir "no existen tales propiedades".

Las estadísticas de ofertas ganadoras están sesgadas, y eso importa más que los números. Las únicas subastas completadas visibles son las que se ganaron y luego se cayeron — las ventas completadas normalmente nunca aparecen en la API de listados. Cada respuesta lleva esa advertencia.

Desarrollo

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

Las pruebas de base de datos se ejecutan contra el esquema real dentro de transacciones que siempre revierten, por lo que no dejan rastro — verificado comparando los recuentos de tablas antes y después. Las pruebas puras pasan con una cadena de conexión deliberadamente rota.

También hay una API HTTP local (api/main.py) vinculada solo a loopback, útil para explorar los datos con curl. No es necesaria para el uso de MCP.

Documentación

Impulsada por especificaciones; 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 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 equivocadas en varios lugares

Seguridad

Las claves viven en .env (local) o en GitHub Secrets / el bloque env de la configuración MCP (desplegado), nunca en el código. La API de 온비드 requiere la clave de servicio como parámetro de consulta y httpx registra URLs completas de solicitudes a nivel INFO, por lo que el cliente baja el registrador httpx a WARNING al importar — de lo contrario, habilitar el registro filtraría la clave. El objeto de configuración enmascara sus valores en repr por la misma razón.

Todas las tablas onbid_* tienen RLS habilitado sin políticas y con permisos revocados; el acceso es solo service_role, verificado por medición (HTTP 401 para anon en cada tabla). La API HTTP se niega a vincularse a cualquier lugar que no sea loopback.

Límites y no objetivos

• Solo consulta. Sin ranking, puntuación ni recomendación — las herramientas devuelven datos públicos y te dejan el juicio a ti. Esto es deliberado: 공인중개사법 restringe la visualización estilo listado y la publicidad de propiedades.

• Sin corretaje, sin valoración, sin asesoramiento legal o de inversión.

• Seúl, listados de tipo venta, en curso por defecto.

• Las estadísticas de ofertas ganadoras provienen de una muestra sesgada (ver arriba).

Licencia

Aún no elegida. Los documentos de la guía de la API de 온비드 están excluidos intencionalmente de este repositorio; las estructuras de respuesta utilizadas aquí están registradas en docs/API_FINDINGS.md a partir de mediciones en vivo.