Metadata-Version: 2.5
Name: atomno-mcp-sudact
Version: 0.2.0
Summary: Court practice and FAS case cards via hosted API. Coverage depends on the connected service.
Project-URL: Homepage, https://github.com/atomno-mcp/mcp-sudact
Project-URL: Repository, https://github.com/atomno-mcp/mcp-sudact
Project-URL: Issues, https://github.com/atomno-mcp/mcp-sudact/issues
Project-URL: Changelog, https://github.com/atomno-mcp/mcp-sudact/blob/main/CHANGELOG.md
Project-URL: Documentation, https://atomno-mcp.ru/mcp/sudact
Author-email: atomno-mcp <hello@atomno-mcp.ru>
License: MIT
License-File: LICENSE
Keywords: atomno,court-practice,kad,legal,mcp,model-context-protocol,russia,sudact
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Legal Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Russian
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastmcp<4.0.0,>=3.4.2
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: pydantic<3.0.0,>=2.6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<2,>=1.0; extra == 'dev'
Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.0; extra == 'dev'
Requires-Dist: respx<1,>=0.21.1; extra == 'dev'
Requires-Dist: ruff<1,>=0.15; extra == 'dev'
Provides-Extra: release
Requires-Dist: build<2,>=1.2.0; extra == 'release'
Requires-Dist: twine<8,>=7; extra == 'release'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.atomno-mcp/mcp-sudact -->

# atomno-mcp-sudact

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

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

```sh
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).

```json
{"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` | `instance` |
|---|---|---|---|
| `arbitr` | `case_number`, `court`, `judge` | судебный округ | `any` |
| `soyu` | `case_number`, `court`, `judge` | субъект РФ | `any`, `first`, `appeal`, `cassation`, `supervision` |
| `vs` | `case_number`, `judge` | не поддерживается | `any` |

`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.

## Разработка

```sh
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 распространяется на клиентский код; условия источников и услуги определяются отдельно.

[Документация](https://atomno-mcp.ru/mcp/sudact) · [Ошибки](https://github.com/atomno-mcp/mcp-sudact/issues) · [Изменения](CHANGELOG.md)
