garant-mcp

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

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

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

• сдвиг квантора — частный случай выдаётся за общее правило и наоборот: «никогда не вправе» там, где закон говорит «в случаях, предусмотренных…»;

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

• потеря ограничительной оговорки — норма приводится без условия, которое делает её применимой;

• устаревшая или несуществующая редакция — статья цитируется в том виде, в каком её запомнила модель, а не в том, какой действовал на дату события;

• правдоподобные реквизиты — номер, дата и название акта выглядят верно и не существуют.

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

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

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

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

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

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

Что умеет

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

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

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

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

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

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

Что нужно

• Действующая подписка «Гаранта» — логин и пароль от internet.garant.ru.

• Один из клиентов: Claude Desktop, Claude Code или Codex (агент OpenAI по подписке ChatGPT). Чат ChatGPT локальные MCP-серверы не запускает — для подписки ChatGPT нужен Codex, см. ниже.

• 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

--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/DECISIONS.md.

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

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

git config core.hooksPath hooks

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

Лицензия

Apache License 2.0; обязательные уведомления — в 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.