onbid-mcp

README на корейском

MCP-сервер, который позволяет LLM запрашивать данные о корейских публичных аукционах (공매) недвижимости с 온бид (KAMCO).

Спросите "какие объекты в 강남구 не были проданы более трёх раз?" в Claude Desktop и получите ответы из данных, которые вы собрали сами — без подписки и без скрейпинга.

Статус. Работает от начала до конца — конвейер запускается по расписанию, а четыре инструмента подключены и отвечают в Claude Desktop на живых данных (6 902 объявления по Сеулу, 99,9% геокодировано). Осталось: финальные приёмочные проверки (M7) и неделя наблюдения за запланированными пакетами. Точное состояние см. в docs/TASKS.md.

Что вы получаете

Четыре инструмента и четыре ресурса через stdio:

Каждый ответ содержит meta (источник, synced_at, is_realtime: false, количество, обрезано, уведомление) и query_echo (фактически применённые фильтры после значений по умолчанию и ограничений).

Related MCP server: BDLedger MCP Server

Перед началом

Этот сервер обращается к вашей собственной базе данных, а не к размещённому сервису. Вы собираете данные, поэтому вам нужны свои учётные данные:

Также: Python 3.11+ и Claude Desktop (или любой MCP-клиент, поддерживающий stdio).

По умолчанию область действия — Сеул, объявления о продаже. Расширение — это изменение фильтра в одну строку, но цифры по геокодированию и квотам ниже предполагают Сеул.

Настройка

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)

Затем соберите первый набор данных. Это займёт около двух минут и останется в пределах ежедневной квоты API:

python scripts/run_batch.py

Вы должны увидеть что-то вроде:

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

Запустите снова с --geocode-budget 1000, пока dataset/status не сообщит о доле геокодирования, которая вас устраивает — кэш поглощает большинство вызовов, так что все 6 902 строки обходятся примерно в 800 вызовов Kakao в сумме.

Подключение Claude Desktop

Добавьте сервер в 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": "..."
      }
    }
  }
}

Здесь четыре вещи, на которых люди спотыкаются:

• PYTHONPATH обязателен — одного cwd недостаточно. Claude Desktop не применяет запись cwd, поэтому python -m onbid_mcp.server не может найти пакет, и процесс мгновенно умирает с ModuleNotFoundError. Приложение сообщает об этом как "Server disconnected", что выглядит как проблема соединения, а не пути.

• Используйте абсолютный путь к интерпретатору venv. Claude Desktop не наследует PATH вашей оболочки, поэтому голый python подхватывает системный интерпретатор без зависимостей.

• Поместите ключи в env. Приложение не читает файл .env проекта.

• Логи никогда не должны попадать в stdout. stdout — это канал JSON-RPC; этот сервер пишет логи в stderr именно по этой причине. Если вы добавляете print, отправляйте их в stderr.

Перезапустите Claude Desktop, затем попробуйте:

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

Если не работает, прочитайте ~/Library/Logs/Claude/mcp-server-onbid.log — настоящая ошибка Python находится там, а интерфейс просто говорит "Server disconnected".

Чтобы проверить соединение без Claude Desktop:

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

Поддержание свежести данных

Включены два рабочих процесса GitHub Actions. Добавьте ONBID_SERVICE_KEY, SUPABASE_DATABASE_URL и KAKAO_REST_API_KEY в секреты репозитория, и они будут запускаться сами:

Cron работает только по UTC, поэтому 04:00 KST — это 19:00 UTC предыдущего дня, что сдвигает день недели на один. Проверьте последнюю неделю с помощью:

python scripts/batch_health.py

Пропущенный cron не оставляет следов нигде — GitHub отправляет письма только о запусках, которые начались и завершились с ошибкой, — поэтому вместо этого подсчитываются дни.

Полезные замечания по дизайну

Они получены из измерений, а не из руководства по API.

Завершённые объявления помечаются, а не удаляются. 온бид возвращает только текущие объекты, поэтому исчезнувшее объявление неотличимо от того, которого никогда не существовало. Строки вместо этого становятся 종료추정, и для этого должны выполняться три условия: режим полного сканирования, соответствие области сбора и завершённое сканирование. Ошибка в области действия перевернула 6 594 здоровых строки в измеренном испытании.

Первичный ключ составной. cltrMngNo сам по себе не уникален — один номер управления несёт до десяти значений pbctCdtnNo, и API информации о торгах возвращает одну и ту же историю раундов под каждым из них. Статистика дедуплицируется по (номер управления, время открытия, раунд); подсчёт строк превращал 13 реальных событий аукциона в 62.

Коэффициенты вычисляются, а не считываются. 온бид поставляет поля коэффициентов, измеренная заполненность которых составляет 0%. min_bid_rate вычисляется и легитимно превышает 1,0 (измеренный максимум 150,2% в 9,8% строк), поэтому он никогда не ограничивается.

Пустой результат — это ошибка, а не пустой список. no_result говорит модели ослабить фильтры; пустой массив позволил бы ей заключить, что "таких объектов не существует".

Статистика выигравших ставок смещена, и это важнее самих чисел. Единственные завершённые аукционы, которые видны, — это те, которые были выиграны, а затем сорвались — обычно завершённые продажи никогда не появляются в API объявлений. Каждый ответ несёт эту оговорку.

Разработка

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

Тесты базы данных выполняются на реальной схеме внутри транзакций, которые всегда откатываются, поэтому они не оставляют следов — проверено сравнением количества таблиц до и после. Чистые тесты проходят с намеренно сломанной строкой подключения.

Также есть локальный HTTP API (api/main.py), привязанный только к loopback, полезный для изучения данных с помощью curl. Для использования MCP он не требуется.

Документация

Управляется спецификацией; документы являются источником истины и написаны на корейском.

• docs/SPEC.md — требования, модель данных, контракты MCP-инструментов, открытые вопросы

• docs/PLAN.md — архитектура, этапы, стратегия тестирования, риски

• docs/TASKS.md — панель прогресса и журнал устранения неполадок

• docs/API_FINDINGS.md — измеренное поведение API; имеет приоритет над официальными руководствами, которые в нескольких местах были ошибочными

Безопасность

Ключи хранятся в .env (локально) или в GitHub Secrets / блоке env конфигурации MCP (при развёртывании), никогда в коде. API 온бид требует сервисный ключ как параметр запроса, а httpx логирует полные URL-адреса запросов на уровне INFO, поэтому клиент понижает уровень логгера httpx до WARNING при импорте — иначе включение логирования раскрыло бы ключ. Объект настроек маскирует свои значения в repr по той же причине.

Все таблицы onbid_* имеют включённый RLS без политик и отозванные гранты; доступ только через service_role, что подтверждено измерениями (HTTP 401 для анонима на каждой таблице). HTTP API отказывается привязываться к чему-либо, кроме loopback.

Ограничения и нецели

• Только поиск. Никакого ранжирования, оценки или рекомендаций — инструменты возвращают публичные данные и оставляют суждение вам. Это намеренно: 공인중개사법 ограничивает отображение в стиле списков и рекламу недвижимости.

• Никакого брокериджа, оценки, юридических или инвестиционных советов.

• По умолчанию: Сеул, объявления о продаже, текущие.

• Статистика выигравших ставок получена из смещённой выборки (см. выше).

Лицензия

Пока не выбрана. Документы руководства по API 온бид намеренно исключены из этого репозитория; используемые здесь структуры ответов записаны в docs/API_FINDINGS.md на основе живых измерений.