# ychetlab-mcp

MCP-сервер панели [УчётLab](https://ychetlab.ru): дела, операции, счета, контрагенты,
проекты, склад, бюджеты, долги и документы — из Claude Code и других клиентов MCP.

Сервер работает **от имени владельца токена** и ограничен ровно его правами: всё, что
не позволено роли в деле, вернёт отказ. Выдать помощнику больше, чем можете сами,
нельзя. Сузить — можно: токен выпускается на отдельные дела и/или в режиме «только
чтение», и это проверяет сама панель, а не клиент.

## Установка

Одной командой:

```bash
npx ychetlab-mcp@latest setup
```

Установщик спросит адрес панели и токен, проверит связь, спросит дело по умолчанию и
режим доступа, подключит плагин к Claude Code и поднимет сервер для проверки. После
этого останется перезапустить Claude Code.

Токен выпускается в самой панели: **профиль → Интеграции → «Выпустить токен»**.
Значение показывается один раз — скопируйте сразу. В панели остаётся только начало
строки: в базе хранится лишь отпечаток SHA-256, поэтому восстановить токен нельзя ни
из панели, ни из её базы. Потерянный токен отзывают и выпускают новый.

### Другой клиент MCP

Установщик в конце печатает готовую строку запуска с полным путём к серверу — её и
вставляйте:

```bash
npm i -g ychetlab-mcp
ychetlab-mcp status   # покажет путь к dist/index.js
```

Полный путь тут не прихоть: запуск через `npx` разрешается заново при каждом старте, в
чужом окружении. На Windows `npx` — это `.cmd`, и клиент, порождающий процесс без
оболочки, получает `ENOENT`; на холодном кэше первый старт уходит в реестр и не
укладывается в рукопожатие. Плагин Claude Code по той же причине везёт собранный
сервер с собой.

## Команды

| Команда | Что делает |
|---|---|
| `ychetlab-mcp setup` | установка целиком: токен, настройки, плагин |
| `ychetlab-mcp` | запустить сервер MCP (так его вызывает Claude Code) |
| `ychetlab-mcp login` | только сохранить токен доступа |
| `ychetlab-mcp logout` | удалить токен с этой машины |
| `ychetlab-mcp status` | проверить связь с панелью и показать дела |
| `ychetlab-mcp tools` | перечислить доступные инструменты |

У `setup` и `login` есть ключи `--url <адрес>` и `--token <ylab_…>`, если вводить их
отдельно не хочется.

## Переменные окружения

| Переменная | Назначение |
|---|---|
| `YCHETLAB_URL` | Адрес панели. Обычно берётся из сохранённого профиля. |
| `YCHETLAB_TOKEN` | Токен доступа вместо сохранённого файла — для контейнера или сборки. |
| `YCHETLAB_BUSINESS` | Дело по умолчанию: название или идентификатор. |
| `YCHETLAB_READ_ONLY` | Значение `1` оставляет только инструменты чтения. |
| `YCHETLAB_CREDENTIALS` | Другой путь к файлу с сохранённым токеном. |
| `YCHETLAB_TIMEOUT_MS` | Сколько ждать ответ панели. По умолчанию `30000`. |
| `YCHETLAB_INSECURE_TLS` | Значение `1` отключает проверку сертификата — для самоподписанного TLS. |

Окружение главнее сохранённого профиля: им переопределяют настройки в контейнере и на
сборке.

## Инструменты — 49 в двенадцати разделах

| Раздел | Инструменты |
|---|---|
| Справочник | `ychetlab_catalog` |
| Доступ и аккаунт | `ychetlab_login`, `ychetlab_logout`, `ychetlab_whoami`, `account_get`, `account_update` |
| Дела | `businesses_list`, `businesses_get`, `businesses_save`, `businesses_delete`, `members_list` |
| Счета | `accounts_list`, `accounts_save`, `accounts_delete` |
| Операции | `operations_list`, `operations_get`, `operations_save`, `operations_delete`, `operations_confirm`, `operations_settle`, `operations_stats`, `operations_forecast`, `operations_breakdowns`, `operations_comment` |
| Долги | `receivables_summary`, `receivables_counterparty` |
| Контрагенты | `counterparties_list`, `counterparties_save`, `counterparties_delete`, `counterparty_groups` |
| Проекты | `categories_list`, `categories_save`, `categories_delete` |
| Склад | `warehouse_list`, `warehouse_get`, `warehouse_save`, `warehouse_delete`, `warehouse_groups` |
| Бюджеты | `budgets_list`, `budgets_get`, `budgets_save`, `budgets_delete` |
| Документы | `templates_list`, `templates_get`, `documents_list`, `documents_generate`, `documents_send` |
| Уведомления | `notifications_list`, `notifications_read` |

Каждый инструмент помечен как чтение, изменение или опасное действие; клиент MCP
спрашивает подтверждение перед опасными. Удаление дела вдобавок требует ввести его
название дословно — случайная фраза ничего не сотрёт.

В режиме «только чтение» клиенту показывается 28 инструментов вместо 49. Инструменты
входа и выхода остаются: иначе совет «вызовите `ychetlab_login`», которым кончается
любой отказ по доступу, вёл бы к инструменту, которого в списке нет.

## Что стоит знать модели (и вам)

- **Деньги.** Сумма операции всегда в валюте её счёта — своё значение валюты
  передавать не нужно. Сводки (статистика, прогноз, разрезы, долги, бюджеты) считаются
  в рублях по курсу ЦБ. Суммы разных валют складывать нельзя.
- **План и факт.** Плановая операция в остатки и статистику не входит, в прогноз
  входит. Подтверждение — `operations_confirm`, частичная оплата — `operations_settle`.
- **Долг** не заводится отдельной сущностью: это и есть неподтверждённая плановая
  операция с контрагентом.
- **Считается на лету.** Остатки счетов и склада, прогресс бюджетов и долги панель
  вычисляет из операций. Задать их напрямую нельзя — меняют начальные значения или
  сами операции.
- **Проекты** в интерфейсе панели — это `categories` в API. Иерархия одноуровневая: у
  подпроекта своих подпроектов не бывает.
- **Что закрыто всегда.** Смена пароля, двухфакторная аутентификация, список устройств
  и управление самими токенами доступны только из панели. Токеном выпустить или
  отозвать токен нельзя — иначе утёкший ключ выписывал бы себе новые.

## Где лежит токен

На машине клиента — в `~/.ychetlab/credentials.json` с правами `600`. Файл пишется
целиком через временный и переименование, под блокировкой: рядом может работать вторая
сессия Claude Code.

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

```bash
npm install
npm run typecheck
npm run build      # сборка пакета + плагина Claude Code одним файлом
```

Сборка плагина (`plugins/ychetlab-mcp/dist`) намеренно едет в репозиторий: Claude Code
берёт плагин прямо отсюда, и без файла сервера ставить нечего.

## Лицензия

MIT