# pbu-fsbu-mcp

[![ci](https://github.com/MihasikPro/pbu-fsbu-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MihasikPro/pbu-fsbu-mcp/actions/workflows/ci.yml)

MCP-сервер с текстами российских стандартов бухгалтерского учёта — все 29 ПБУ и ФСБУ
из реестра Минфина, с точностью до пункта, с учётом даты и с проекцией на объекты
конфигурации «1С:Бухгалтерия предприятия 3.0».

Отвечает на вопросы вида «что ФСБУ 6/2020 требует по ликвидационной стоимости»
и на обратные — «какая норма стоит за регистром `ПараметрыАмортизацииОС`».

## Быстрый старт

```bash
git clone https://github.com/MihasikPro/pbu-fsbu-mcp.git
cd pbu-fsbu-mcp
docker compose -f deploy/compose.local.yml up --build
```

```bash
curl http://127.0.0.1:18010/healthz
```

Ожидается `{"status":"ok"}`. MCP-эндпоинт — `http://127.0.0.1:18010/mcp`.

Корпус в git не хранится: он собирается из YAML-исходников на этапе `docker build`
и там же проверяется валидатором, поэтому невалидный корпус роняет сборку вместо
того, чтобы уехать в рантайм. Ничего доустанавливать перед первым запуском не нужно —
ни Python, ни Tesseract.

## Инструменты

| Инструмент | Отвечает на вопрос |
|---|---|
| `list_standards` | Какие стандарты существуют, какие действуют на дату |
| `get_standard` | Метаданные и оглавление одного стандарта |
| `get_clause` | Точный текст пункта с реквизитами приказа и номером редакции |
| `search_clauses` | Какой пункт отвечает на вопрос, заданный обычными словами |
| `get_1c_mapping` | Какими объектами БП 3.0 реализован пункт |
| `find_by_1c_object` | Какая норма стоит за объектом конфигурации |
| `get_its_references` | Какие статьи ИТС разбирают этот пункт |

Ресурс `pbu-fsbu://registry` — компактная таблица всех стандартов, которую клиент
может загрузить один раз в начало сессии вместо повторных вызовов `list_standards`.

## Что внутри

**29 стандартов, 1768 пунктов.** Весь реестр Минфина: действующие и утратившие силу
ПБУ и ФСБУ, по одной редакции каждый.

**Ответ всегда дан на дату.** Каждый инструмент принимает `on_date` и возвращает
статус стандарта на эту дату. Это не украшение: ПБУ 9/99 и 10/99 утрачивают силу
01.01.2027, ФСБУ 9/2025 и 10/2026 вступают в силу тогда же, и ответ без даты
на этом горизонте будет неверным.

**Проекция на 1С — вычитанная.** ФСБУ 6/2020 связан с объектами БП 3.0: 18 связок
по 17 пунктам, каждая с оценкой уверенности и объяснением, *как именно* объект
реализует норму. Все записи имеют `verified: true` — их проверил человек, а не
только код. Остальные 28 стандартов проекции пока не имеют, и инструменты отвечают
явным сообщением, а не пустым списком.

**Проекция — интерпретация, а не норма.** Она всегда лежит в отдельном поле от
текста пункта и сопровождается дисклеймером. Непроверенные записи дополнительно
поднимают отдельное предупреждение, и оно не исчезает, пока хоть одна такая запись
попадает в ответ.

**Сервер не ходит в сеть.** Ни при старте, ни при обработке запроса. База открыта
строго на чтение, образ иммутабельный.

## Чего он не делает

- Не консультирует и не интерпретирует нормы за пределами точного текста стандарта.
- Не хранит тексты статей ИТС — только идентификаторы, заголовки и краткие выжимки
  своими словами. Полный текст читается по подписке.
- Не заменяет юриста и не принимает учётных решений.

## Подключение клиентов

Клиент подключается к уже запущенному серверу — локальному или на внутреннем сервере.

### Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.pbu_fsbu]
url = "http://127.0.0.1:18010/mcp"
```

### Claude Code

```bash
claude mcp add --transport http pbu-fsbu http://127.0.0.1:18010/mcp
```

### Claude Desktop

Claude Desktop к HTTP-эндпоинту подключиться не может: приложение отклоняет схему
`http://`, а соединение custom connector устанавливается из облака Anthropic, которое
не достучится ни до `localhost`, ни до адреса в локальной сети. Codex CLI и Claude
Code — локальные процессы, у них этой проблемы нет.

Для Claude Desktop сервер запускается локально по stdio, из чекаута с уже собранным
корпусом — `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pbu-fsbu": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\pbu-fsbu-mcp", "run", "pbu-fsbu-mcp"]
    }
  }
}
```

Установка прямо из git-адреса (`uvx --from git+...`) для этого не годится:
`data/build/` не попадает в репозиторий, корпус не соберётся, и сервер откажется
стартовать. Нужен локальный чекаут — см. «Разработка».

## Развёртывание на сервере

`deploy/compose.server.yml` рассчитан на внутренний сервер с доступом только из
локальной сети:

```bash
git clone https://github.com/MihasikPro/pbu-fsbu-mcp.git
cd pbu-fsbu-mcp/deploy
docker compose -f compose.server.yml up -d --build
```

Перед первым запуском замените в файле адрес публикации порта на адрес вашего
сервера. Порт публикуется **на конкретный LAN-адрес**, а не на `0.0.0.0`: если у
хоста появится второй интерфейс — VPN или публичный IP — привязка к `0.0.0.0`
выставила бы сервис туда молча, а такая запись этого не сможет.

TLS и аутентификации нет намеренно: корпус — публичные нормативные тексты без
секретов, сеть закрытая. Выставлять сервис наружу без TLS и авторизации не следует.

`corpus_meta.built_at` фиксируется на момент `docker build`, а не при старте
контейнера. Предупреждение об устаревании корпуса отсчитывает 90 дней от даты
сборки образа; `restart` и `up` без `--build` корпус не обновляют — нужна пересборка.

## Источники

- [Минфин России — Федеральные стандарты бухгалтерского учёта](https://minfin.gov.ru/ru/perfomance/accounting/accounting/standart/positions/)
- [publication.pravo.gov.ru — официальное опубликование правовых актов](http://publication.pravo.gov.ru/Help/Index)

Основной источник текста — собственная страница стандарта на сайте Минфина
(`https://minfin.gov.ru/ru/document?id_4=NNNN`, ссылка есть в реестре): там текст
отдаётся обычным серверным HTML, без сканов и без OCR, и доступен даже для стандартов
старше архива publication.pravo.gov.ru — тот начинается примерно с ноября 2011 года
и потому не содержит 19 из 29 стандартов вовсе.

Исключение — ФСБУ 27/2021: его страница на сайте Минфина не содержит текста, только
`<iframe>` с PDF-вьювером. Для этого единственного стандарта текст получен
распознаванием официального скана приказа (Tesseract 5.x, модель `rus` из
`tessdata_best`) с последующей построчной вычиткой. OCR — документированный резервный
путь, а не основной способ.

Текст выверяется по официальному акту перед переносом файла из `data/drafts/`
в `data/sources/standards/`. Тест `test_html_sourced_standard_reproduces_byte_for_byte`
регенерирует корпус из закоммиченных HTML-снимков и требует побайтового совпадения,
так что корпус воспроизводим по построению, а не на честном слове.

### Что не входит в корпус

Приложения к самому стандарту — образцы форм отчётности и развёрнутые числовые
примеры, оформленные отдельным приложением с собственной нумерацией — в корпус не
входят. Формально они часть акта, но их нумерация («1.», «2.» …) начинается заново
и конфликтует с пунктами стандарта.

Отличие от рабочих примеров *внутри* пунктов — только в разметке источника: у
настоящего приложения есть собственный заголовок «Приложение к Положению по
бухгалтерскому учету «…»». Числовые примеры в пп. 14–15 ПБУ 18/02 такого заголовка
не имеют, они часть текста пункта и в корпусе присутствуют полностью.

| Стандарт | Отрезано |
|---|---|
| ПБУ 8/2010 | 12 010 симв. |
| ПБУ 24/2011 | 4 062 симв. |
| ПБУ 16/02 | 3 814 симв. |
| ПБУ 19/02 | 3 208 симв. |
| ПБУ 7/98 | 2 768 симв. |
| ПБУ 18/02 | 2 372 симв. |
| ПБУ 3/2006 | 1 508 симв. |

## Лицензия

Нормативные правовые акты не являются объектами авторского права (ст. 1259 ГК РФ).
Код — MIT, условия на данные — `data/LICENSE`.

## Обновление корпуса

При выходе нового приказа Минфина:

1. `uv run --group etl python -m etl.watch --live` — сравнивает реестр на сайте
   Минфина с корпусом и показывает расхождения.
2. `uv run --group etl python -m etl.draft_yaml --live` — вытягивает текст пунктов
   и кладёт черновик в `data/drafts/`.
3. Вычитать текст по официальному приказу, перенести в `data/sources/standards/`,
   удалить баннер `# ЧЕРНОВИК`.
4. `uv run python -m etl.build_db && uv run python -m etl.validate`
5. `uv run --group etl pytest`

Раз в неделю то же сравнение выполняет workflow `etl-watch` и при расхождении
открывает pull request с отчётом. Автоматического мёржа нет: новый приказ читает
человек.

Недоступный сайт Минфина — не расхождение: `etl.watch` возвращает для этого
отдельный код возврата (`2` против `1`), workflow повторяет попытку трижды и при
неудаче падает, не открывая pull request. Красный прогон здесь означает «сверка
не выполнена», а не «вышел новый приказ».

Правила добавления связок с 1С и ссылок на ИТС — в [CONTRIBUTING.md](CONTRIBUTING.md).

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

```bash
uv sync --all-groups
uv run python -m etl.build_db
uv run python -m etl.validate
uv run --group etl pytest
```

Источник истины — YAML в `data/sources/`. Файл `data/build/pbu_fsbu.db` собирается
из них и в репозиторий не коммитится.

Сервер можно запустить и без контейнера:

```bash
uv run pbu-fsbu-mcp                                    # stdio
uv run pbu-fsbu-mcp --transport http --port 18010      # HTTP
```

### OCR-тесты и Tesseract

Тесты распознавания (`tests/test_ocr_text.py`) требуют локально установленного
Tesseract 5.x с моделью `rus`. Без него они пропускаются — остальной набор от этого
не зависит. Чтобы они реально выполнялись:

- `TESSERACT_CMD` — путь к `tesseract`, если бинарник не в `PATH`;
- `TESSDATA_PREFIX` — каталог с моделями `*.traineddata`, если он нестандартный.

```powershell
$env:TESSERACT_CMD = "C:\Program Files\Tesseract-OCR\tesseract.exe"
$env:TESSDATA_PREFIX = "C:\Users\<user>\.tessdata"
uv run --group etl pytest
```

В CI Tesseract и модель `rus` ставятся через `apt-get` — см. `.github/workflows/ci.yml`.