# garant-mcp

**Ассистент, который цитирует закон по базе «Гарант», а не по памяти.**
garant-mcp создан для одной задачи: чтобы Claude или Codex при подготовке
юридических документов работали с действующим текстом нормы, нужной
редакцией и реальной практикой — и каждую ссылку отдавали с реквизитами,
по которым её можно сверить.

## Для чего он создан

Языковая модель, отвечающая по памяти, ошибается в праве не грубо,
а правдоподобно, и именно поэтому опасно. Искажения типовые:

* **сдвиг квантора** — частный случай выдаётся за общее правило и наоборот:
  «никогда не вправе» там, где закон говорит «в случаях, предусмотренных…»;
* **смешение полномочий субъектов** — права следователя, дознавателя, органа
  дознания и оперативного сотрудника сливаются в одно «правоохранительный
  орган может»;
* **потеря ограничительной оговорки** — норма приводится без условия,
  которое делает её применимой;
* **устаревшая или несуществующая редакция** — статья цитируется в том виде,
  в каком её запомнила модель, а не в том, какой действовал на дату события;
* **правдоподобные реквизиты** — номер, дата и название акта выглядят верно
  и не существуют.

В исковом заявлении, жалобе или заключении каждое такое искажение — не
погрешность стиля, а довод, который отклонят суд и противная сторона, и повод
усомниться во всём документе.

garant-mcp убирает причину: ассистент перестаёт отвечать по памяти. Норма,
редакция и практика извлекаются из базы «Гарант» в момент запроса, и ответ
строится на извлечённом тексте. Модель рассуждает — база отвечает за факт.

**Пример.** На вопрос о полномочиях оперативного сотрудника при проведении
оперативно-розыскных мероприятий ассистент без базы уверенно ответил, что
назначать исследования и экспертизы он не вправе, — сдвиг квантора: общий
запрет там, где закон разграничивает процессуальную экспертизу
и исследование в рамках оперативно-розыскной деятельности. С подключённым
garant-mcp тот же вопрос привёл ассистента к тексту Федерального закона
«Об оперативно-розыскной деятельности» и УПК РФ в действующих редакциях,
и ответ был построен на нормах — со статьями, редакцией и изменяющими
актами. В практике автора после подключения базы ошибки такого рода
в подготовке процессуальных документов перестали возникать.

## Как меняется работа

Раньше: открыть «Гарант», найти документ, пролистать до статьи, проверить
редакцию, скопировать, вставить, сверить — и так с каждой ссылкой. Теперь
один вопрос ассистенту своими словами: он сам находит документ, открывает
нужную статью, определяет, какая редакция действовала на дату события,
поднимает практику Верховного и Конституционного судов — и текст с редакцией,
датой начала её действия и изменяющим актом уже стоит в вашем документе.

Так готовятся иск, жалоба, заключение, претензия, договор; так же — смета
с обоснованием по нормативам, закупочная документация, кадровый приказ,
ответ контролирующему органу. Везде, где нужна точная ссылка на норму,
ассистент делает её сам и показывает, откуда взял. Сверка цитаты перед
подачей занимает минуту: реквизиты и отпечаток текста приходят вместе
с ответом.

## Что умеет

Восемь инструментов, которыми пользуется ассистент:

| инструмент | что делает |
|---|---|
| `garant_search` | поиск по всей базе — акты, судебные решения, комментарии, формы |
| `garant_document` | текст документа; у длинных актов — первые страницы, о чём ответ предупреждает сам |
| `garant_article` | дословный текст конкретной статьи или пункта |
| `garant_toc` | оглавление документа |
| `garant_revisions` | все редакции акта: периоды действия, изменяющие акты |
| `garant_revision_on_date` | какая редакция действовала на нужную дату |
| `garant_practice` | судебная практика высших судов с фильтрами по виду и периоду |
| `garant_kinds` | дерево видов информации базы |

Текст статьи в нужной редакции берётся по её `id_редакции` из
`garant_revision_on_date` или `garant_revisions` — ассистент делает это сам,
когда речь идёт о событии в прошлом.

## Почему этому можно доверять

К тексту статьи прикладывается блок `provenance`: редакция, дата начала её
действия, изменяющий акт, дата проверки и отпечаток ровно того текста, который
отдан. Цитату с таким блоком **сверяют, а не принимают на веру** — это главное
отличие от «спросить у ИИ про закон». Там, где выдача неполна или требует
сверки, инструмент сообщает об этом сам — в полях `_предупреждение`
и `_нормализация`.

| ключ `provenance` | что означает |
|---|---|
| `doc_id` | идентификатор, по которому взят текст: документа или его редакции |
| `редакция`, `действует_с` | в какой редакции взят текст и с какой даты она действует |
| `изменяющий_акт` | каким актом введена |
| `источник`, `дата_проверки` | откуда и когда получено |
| `hash_текста`, `правило_отпечатка` | отпечаток отданного текста и версия правила его вычисления |
| `оговорки_о_редакции` | появляется только когда есть повод уточнить редакцию — и называет его |

## Доступ — ваша подписка

Работает через **вашу собственную подписку «Гаранта»**: вы один раз входите
в своём браузере, сессия живёт в профиле браузера на вашем компьютере
и продлевается автоматически. Репозиторий не содержит базы, не хранит
и не передаёт учётные данные, ничего не проксирует. Без действующей подписки
сервер работать не будет.

## Что нужно

* Действующая подписка «Гаранта» — логин и пароль от `internet.garant.ru`.
* Один из клиентов: **Claude Desktop**, **Claude Code** или **Codex** (агент
  OpenAI по подписке ChatGPT). Чат ChatGPT локальные MCP-серверы не запускает —
  для подписки ChatGPT нужен Codex, см. [ниже](#codex-подписка-chatgpt).
* **git** — пакет ставится из репозитория. Windows: `winget install --id Git.Git -e`;
  macOS: `brew install git`; Debian/Ubuntu: `sudo apt install git`. После
  установки откройте новое окно консоли.

Python ставить не нужно — установщик поставит сам. Права администратора
не требуются; единственное исключение — включение длинных путей на Windows,
см. «Если не работает».

---

## Установка: три шага

### 1. Одна команда

**Windows** — Win, набрать «PowerShell», открыть, вставить строку целиком:

```
powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm https://raw.githubusercontent.com/semenboss95-design/garant-mcp/main/install.ps1).TrimStart([char]0xFEFF)))"
```

**macOS и Linux** — в Терминале:

```
curl -LsSf https://raw.githubusercontent.com/semenboss95-design/garant-mcp/main/install.sh -o install.sh && sh install.sh
```

Установщик ставит менеджер пакетов `uv`, сам пакет и браузер Chromium,
прописывает сервер в Claude Desktop и Claude Code, открывает окно входа
и заканчивает диагностикой. Каждый шаг печатает результат; в конце — сводка.
Повторный запуск безопасен: ничего не дублируется, вход не сбрасывается.

### 2. Вход в подписку

В открывшемся окне браузера введите логин и пароль «Гаранта», дождитесь
личного кабинета и закройте окно. Если окно закрыли раньше или оно
не открылось — вход делается отдельно:

```
garant login
```

Проверка, что подписка отвечает:

```
garant doctor --живой
```

### 3. Перезапуск клиента

Claude и Codex читают список серверов при старте. Закройте клиент полностью
(на macOS — Cmd+Q) и откройте снова. Спросите: «найди в Гаранте статью 108
УПК РФ» — при первом обращении клиент попросит разрешение на инструмент,
разрешите.

---

## Codex (подписка ChatGPT)

Codex — агент OpenAI (приложение, командная строка и расширение для
редактора), доступный по подписке ChatGPT. В отличие от чата ChatGPT он
запускает локальные MCP-серверы. Регистрация — одной командой после
установки:

```
garant register --codex
```

Команда дописывает в `~/.codex/config.toml` таблицу `[mcp_servers.garant]`
с полным путём к серверу и таймаутом запуска, не трогая остальные настройки
(если файл уже был, рядом остаётся его копия `.bak`). Каталог настроек
переопределяется переменной `CODEX_HOME`. После регистрации перезапустите
Codex. Снять запись — `garant unregister --codex`. Сервер проверен в живом
Codex 09.09.2026 по записи такого вида, вписанной руками.

Другие MCP-клиенты, умеющие запускать локальную программу, работают с записью
вида `{"command": "garant-mcp"}` — её вписывают в конфигурацию клиента руками;
если клиент не видит каталог команд `uv`, вместо имени ставится полный путь
к `garant-mcp`.

---

## Управление: команда `garant`

Одна команда на всех системах:

```
garant doctor          диагностика; --живой добавляет запрос к «Гаранту»
garant status          коротко: демон, сессия, версия, каталог состояния
garant login           войти в подписку
garant setup           повторить установочные шаги
garant start | stop | restart
garant logs [N]        последние N строк журнала демона
garant register        прописать сервер у Claude Desktop и Claude Code;
                       --codex — у Codex; --project ПУТЬ — в .mcp.json проекта
garant unregister      снять запись
garant autostart on    поднимать демона при входе в систему
garant update          обновить пакет и перезапустить демона — вход сохраняется
garant uninstall       снять регистрации, автозапуск и демона; профиль подписки —
                       только с --purge; сам пакет — uv tool uninstall garant-mcp
garant migrate ПУТЬ    перенести профиль из прежней установки
```

`garant` без аргументов печатает полный список. Каждый красный пункт
`garant doctor` сопровождается командой, которой он чинится.

---

## Если не работает

**`garant` не находится как команда.** Откройте новое окно консоли. Если
не помогло — `uv tool update-shell`, затем снова новое окно.

**Claude или Codex не видят инструменты.** `garant register` (для Codex —
`garant register --codex`), затем `garant doctor` и полный перезапуск клиента.

**«Сессия подписки недействительна» (сервер ответил 401 или 403).** Вход
истёк: `garant login`.

**Windows: установка пакета упала с «WinError 206» или установка Chromium —
с ошибкой Python.** Выключены длинные пути. В PowerShell от администратора
один раз:

```
New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name LongPathsEnabled -Value 1 -PropertyType DWord -Force
```

Затем повторите установку в обычном окне.

### Ключи установщика

Для проверки установки без подписки и без записи в конфигурации клиентов
установщик запускается из файла с ключами:

```
irm https://raw.githubusercontent.com/semenboss95-design/garant-mcp/main/install.ps1 -OutFile install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -БезРегистрации -БезВхода
```

```
curl -LsSf https://raw.githubusercontent.com/semenboss95-design/garant-mcp/main/install.sh -o install.sh
sh install.sh --no-register --no-login
```

| ключ | Windows | macOS и Linux |
|---|---|---|
| ставить из своего каталога или адреса | `-Источник ПУТЬ` (`-Source`) | `--source ПУТЬ` |
| не открывать окно входа | `-БезВхода` (`-NoLogin`) | `--no-login` |
| не трогать конфигурации клиентов | `-БезРегистрации` (`-NoRegister`) | `--no-register` |
| сверить, что автозапуск не появился | `-БезАвтозапуска` (`-NoAutostart`) | `--no-autostart` |
| справка | `-Справка` (`-Help`, `-h`) | `--help`, `-h` |

`--source` принимает git-адрес, имя пакета, файл `.whl` или корень
распакованного репозитория. С `--no-register` шаг `garant setup` пропускается
целиком: пакет ставится, но Chromium, регистрация и вход выполняются потом
командами `garant setup` и `garant login`.

---

## Границы

Текст статьи — нормализованный HTML страницы «Гаранта», поэтому редакционные
врезки («Статья … дополнена … с … г.») могут оказаться внутри цитаты; каждый
ответ с текстом несёт оговорку `_нормализация`, и перед подачей документа
цитату сверяют с окном подписки. Судебная практика отдаётся первой страницей
отфильтрованного списка — фильтры «Гаранта» по виду и периоду серверные,
остальные страницы не запрашиваются; уточнение по конкретному суду
делается по заголовку и объявляется в `_предупреждение`; акты кассационных
судов общей юрисдикции лежат в другой базе «Гаранта» и через подписку
недоступны. У `garant_toc`, `garant_kinds`, `garant_revisions`
и `garant_revision_on_date` блока `provenance` нет: они возвращают структуру
и сведения о редакциях, а не текст нормы. Клиент построен по записанному
трафику «Гаранта», публичного API у сервиса нет; при изменении API сервиса
ответы инструментов проверяются и карта эндпоинтов обновляется.

---

## Как устроено

```
Claude / Codex → garant-mcp → HTTP на 127.0.0.1 → garant-daemon → браузер → «Гарант»
```

Демон — единственный владелец профиля браузера; он продлевает сессию
по таймеру независимо от того, открыт ли клиент, слушает только `127.0.0.1`
и поднимается автоматически при первом вызове инструмента. Отпечаток браузера
(User-Agent, локаль и часовой пояс вашей машины плюс фиксированный размер
окна) снимается при первом входе и сохраняется — к нему привязана сессия.
Карта эндпоинтов лежит
в `src/garant_mcp/endpoints.json` отдельно от кода.

Устройство — [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); журнал решений
с обоснованиями — [`docs/DECISIONS.md`](docs/DECISIONS.md).

---

## Разработчикам

Первым делом в свежем клоне включите защиту от утечки секретов:

```
git config core.hooksPath hooks
```

`hooks/pre-commit` проверяет содержимое индекса и не пропустит живую сессию,
токен или путь машины. Что именно проверяется — [`hooks/README.md`](hooks/README.md).
Протокол работы — [`docs/TEAM.md`](docs/TEAM.md), живая приёмка —
[`docs/ACCEPTANCE.md`](docs/ACCEPTANCE.md). CI прогоняет `ruff`, тесты,
сборку пакета и дымовой тест MCP по stdio на Windows и Linux.

---

## Лицензия

[Apache License 2.0](LICENSE); обязательные уведомления — в [`NOTICE`](NOTICE),
при распространении и в форках сохраняются. Лицензия не даёт прав на товарный
знак «Гарант» и описывает права на этот код; допустимость автоматизированного
обращения к сервису определяется его правилами и вашей подпиской.

---

## About `tools/` (English)

`tools/` is a small, service-agnostic pipeline for building an API client for
a web application that has no public API:

```
record_api.py      → record the XHR/fetch traffic of a live session with Playwright (analytics noise filtered out)
build_endpoints.py → derive an endpoint map from those recordings
```

The result is a JSON map — request steps, placeholders, extraction paths — that
a thin client reads at runtime instead of hardcoding URLs. `src/garant_mcp/`
is the reference consumer of such a map (`src/garant_mcp/endpoints.json`).
Recordings are truncated on capture and never committed: they contain a live
authenticated session.