mcp-sudact

atomno-mcp-sudact

MCP-клиент для поиска судебной практики и карточек дел ФАС через подключённый API ATOMNO. Это тонкий клиент, а не собственная полная база судебных решений. Python >=3.11.

Установка и подключение

pip install atomno-mcp-sudact

atomno-mcp-sudact --help atomno-mcp-sudact --version

Для подключения используйте ключ и адрес активированной услуги из кабинета/инструкции. Ключ задаётся переменной MCP_SUDACT_TOKEN, адрес — MCP_SUDACT_API_BASE. По умолчанию адрес https://api.atomno-mcp.ru/sudact; конкретный доступ и подключённые источники определяет услуга. MCP_SUDACT_TIMEOUT задаёт HTTP-таймаут в секундах (по умолчанию 60).

{"mcpServers":{"sudact":{"command":"atomno-mcp-sudact","env":{"MCP_SUDACT_TOKEN":"YOUR_API_KEY","MCP_SUDACT_API_BASE":"https://api.atomno-mcp.ru/sudact"}}}}

Не сохраняйте настоящий ключ в репозитории. Получение ключа не означает автоматическое подключение всех источников.

Инструменты

• search_cases: текст от 3 символов или отдельный case_number, court_type=any|vs|arbitr|soyu|fas, статьи norms, даты YYYY-MM-DD, limit=1..50. Исходные поля, предупреждения, provenance и сведения о лимитах сохраняются.
• get_search_capabilities: возможности подключённого сервера, разделы, фильтры и доступность пагинации. Требует действующий ключ и не запускает поиск.
• resolve_court_name: кандидаты названий судов из ограниченной выдачи одного раздела. Возвращает карточки, точное совпадение, неоднозначность и границы выборки. Это один обычный учитываемый поиск; возвращённые карточки учитываются как в search_cases.
• search_fas_decisions: карточки ФАС; текст, орган body, закон law (44-ФЗ/223-ФЗ/135-ФЗ/38-ФЗ), вид акта act_type, даты, лимит. Передаётся /v1/search с court_type=fas. Карточка не обязательно содержит полный текст решения.
• get_citation: url или case_id из выдачи, include_full_text, anonymize_level=none|physical_persons|all_persons. Наличие полного текста и результат анонимизации определяет backend.

У search_cases есть соответствующие поля fas_body, fas_law, fas_act_type, допустимые только для any/fas. Виды актов: решение, предписание, постановление, постановление о штрафе, определение, предупреждение, жалоба, уведомление.

Структурированные фильтры требуют один раздел. Они передаются в отдельные поля формы Sudact и проверяются по текущей форме перед поиском. Если источник убрал поле или значение неоднозначно, сервер возвращает ошибку. Фильтры не снимаются при сбое: такой запрос не переключается на другой источник и не дополняется индексами RAS/ФАС.

region принимает точное имя или код из формы выбранного раздела. Один числовой код может означать разные значения в разных разделах; общего справочника кодов нет. court принимает точное имя суда. Наличие поля поиска не означает полный справочник судов.

Пример поиска по реквизитам: search_cases(court_type="arbitr", case_number="А40-12345/2024") — query можно опустить. Номер отправляется отдельным фильтром, не заменяется текстовым запросом.

Для помощника укажите name, один court_type=arbitr|soyu|vs и, по возможности, query или case_number, задающие полезную выборку. Без них текстом поиска становится name. exact означает точное совпадение среди полученных имён; unique_candidate — один частичный кандидат, требующий выбора; ambiguous — несколько; not_found_in_sample — имени нет в этой выборке. Только exact заполняет resolved_name. Ни один статус не доказывает полноту справочника. Доступно не более 50 карточек и пяти поисков страниц источника.

page=1..5 допустим только для одного раздела vs/arbitr/soyu, без фильтров ФАС, при page*limit<=50. Такой запрос не смешивает корпуса и fallback. Обёртка проверки норм на конкретной услуге может отклонить page с 422 — в этом случае запросите без page. Клиент не отключает серверную проверку норм.

source и collegium не являются подтверждёнными фильтрами действующего REST-контракта и не экспортируются. Поле source в ответе — происхождение записи. Выбор раздела или ФАС и установленный клиент не гарантируют права на все источники, полный корпус или свежесть всех данных. Новый MCP-клиент не предлагает неподтверждённый раздел ks. Старые REST-запросы с этим значением получают явный типизированный отказ до обращения к источнику.

Ошибки и учёт

Пустая успешная выдача отличается от ошибки источника. 401/403/429/5xx сохраняются как backend_error со статусом; таймаут/сетевая ошибка — unavailable. Ошибочный/необъектный JSON не становится пустым результатом. Отсутствующий ключ — missing_token, неправильный ключ не называется отсутствующим.

Каждый вызов выполняет одну попытку POST. Автоматического повтора при timeout, 429 или 502–504 нет: повтор может быть новым учитываемым запросом. Таймаут не доказывает, что сервер не учёл обращение; клиент не обещает возврат квоты. Права и учёт определяет действующая услуга.

get_search_capabilities выполняет одну попытку GET. resolve_court_name выполняет одну попытку POST. При недоступности добавочного индекса основной ответ сохраняется, а search_meta.partial_errors и warnings явно отмечают неполную выдачу источников. Ошибка основного источника, CAPTCHA, незавершённый поиск и повреждённая страница не выдаются за отсутствие дел.

Перед каждым поиском с новыми структурированными фильтрами и перед resolve_court_name клиент проверяет контракт сервера одним GET capabilities. Если старый сервер, откат или повреждённый ответ не подтверждает возможности, поисковый POST не отправляется (unsupported_backend). Положительный ответ не кэшируется между вызовами. Обычные текстовые запросы обходятся одним POST и работают с прежним сервером. Выкладка сервера должна атомарно сохранять заявленный контракт во время обработки запроса.

Запуск

По умолчанию — stdio. Поддерживаются --transport/-t stdio|http|sse|streamable-http, --host, --port, --log-level/-l DEBUG|INFO|WARNING|ERROR|CRITICAL, --version/-V. Для HTTP-транспортов по умолчанию используются 127.0.0.1:8000; публичное размещение требует отдельной настройки доступа. Уровень CLI имеет приоритет над MCP_SUDACT_LOG_LEVEL; неправильный уровень — ошибка запуска. Баннер не попадает в stdio.

Разработка

pip install -e ".[dev,release]"

ruff check . pytest --cov=atomno_mcp_sudact --cov-fail-under=85 python -m build python -m twine check dist/*

Тесты используют изолированные HTTP-ответы, а не доказывают работу production или платного клиентского доступа. MIT распространяется на клиентский код; условия источников и услуги определяются отдельно.

Документация · Ошибки · Изменения