onbid-mcp

한국어 README

MCP-сервер, который предоставляет данные о корейских публичных торгах (공매) из OpenAPI сервиса 온비드 (KAMCO) LLM-клиентам, таким как Claude Code.

Статус: в разработке. Вехи M0–M3 завершены — сбор, нормализация и загрузка в Supabase работают сквозным образом на живых данных (на 2026-08-23 загружено 6 902 объявления по Сеулу). Геокодирование (M4), слой запросов (M5) и сами инструменты MCP (M6) ещё не построены.

Зачем это нужно

온би딩 публикует объявления о торгах через OpenAPI, но с сырым потоком данных неудобно работать: цены приходят в виде свободного текста, адреса отсутствуют в эндпоинте выдачи списка, завершившиеся объявления просто исчезают из ответов, а дневная квота запросов настолько мала, что наивный краулер никогда не успевает дойти до конца. Этот проект раз и навсегда впитывает эти особенности в пакетном пайплайне, чтобы LLM мог задавать простые вопросы вроде "какие объекты в 강남구 не удалось продать более трёх раз?"

Что уже реализовано

Проектные заметки, которые стоит знать

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

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

Первичный ключ составной. cltrMngNo сам по себе не уникален: один такой номер может содержать до 10 значений pbctCdtnNo. Обращения к деталям и к torгinho-информации требуют оба поля.

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

Ротация раундов происходит по времени последней попытки. Эндпоинт bid-info позволяет выполнять называется 1 000 вызовов в день при 1 088 подходящих лот. Вместо хранения токена возобновления — позиция прогресса это множество, а не простой решитель — цели сортируются по времени последней попытки, что делает ротацию не хранящей состояния и самоизгнавющейся.

Поиск изменений происходит до апсерта. Если сравнивать уже после записи, то различия окажутся проглочены молча, поэтому обе операции объединены в один вызов, порядок частей которого невозможно перепустить.

Требования

• Python 3.11+

• Сервийный ключ 스 shared공공데이터포털 с включёнными API 온dbi

• Проект Supabase (PostgreSQL)

• REST API ключ Kakao Local (нужен начиная с 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

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

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

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

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

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

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

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

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

Ключи хранятся только в .env. API 온бид требует сервисный ключ как параметр запроса, а httpx на уровне INFO логирует полные URL запросов, поэтому core/onbid/client.py при импоте понижает логгер httpx до WARNING — иначе логирование раскрыло бы ключ. Во всех таблицах onbid_* включён RLS, при этом не задано никаких полисов, а грани системы отозванли: доступ возможнее только через service_role, и это подтверждено монтажированием (аноним получает HTTP 401 на всех таблицах).

Лиц. «공.