# drebedengi-mcp

MCP-сервер для [drebedengi.ru](https://www.drebedengi.ru) («Дребеденьги», домашняя бухгалтерия).
Работает через официальный SOAP API сервиса (`https://www.drebedengi.ru/soap/`), без парсинга сайта.

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

| Инструмент | Что делает |
|---|---|
| `get_balance` | Остатки по счетам по каждой валюте (сейчас или на дату), итоги; долги отдельным списком |
| `list_accounts` | Счета / места хранения |
| `list_categories` | Категории расходов (`kind=expense`) или источники доходов (`kind=income`) |
| `list_tags`, `list_currencies` | Теги, валюты с курсами |
| `get_transactions` | Операции за период: фильтры по типу, счетам, категориям, тегам, сумме, поиск по комментарию |
| `get_report` | Расходы по категориям / доходы по источникам, с усреднением и пересчётом в одну валюту |
| `add_expense`, `add_income` | Добавить расход / доход |
| `add_transfer` | Перевод между счетами |
| `add_currency_exchange` | Обмен валюты |
| `update_transaction` | Изменить расход/доход (сумма, категория, счёт, дата, комментарий) |
| `delete_transaction` | Удалить операцию (у перевода/обмена — обе половины) |
| `create_category` | Создать категорию, источник дохода, счёт или тег |

Суммы везде в рублях (не в копейках). Счета, категории, источники и теги можно указывать по `id` или по названию
(без учёта регистра и эмодзи; «Еда» найдёт «🥪 Еда»). При неоднозначности сервер вернёт список вариантов с id.

## Установка

Нужен Node.js 18+.

```bash
git clone https://github.com/hawk911/drebedengi-mcp.git
cd drebedengi-mcp
npm install
cp .env.example .env
```

Откройте `.env` и впишите логин (e-mail), пароль и API ID. Затем проверьте подключение:

```bash
npm run check
```

**API ID обязателен для личного аккаунта.** Публичный `demo_api` работает только с демо-аккаунтом
(для своего аккаунта сервер ответит `Login failed. API ID 'demo_api' is invalid`). Собственный API ID выдаёт поддержка drebedengi.

`npm run smoke` — проверка всех инструментов чтения на вашем аккаунте (режим только чтения, выводит только количества).

### Нагрузка на сервер

Правила drebedengi: не создавать поток запросов и не перезапрашивать одни и те же данные в большом объёме
(для этого есть `getChangeList`). Поэтому:

- запросы к API идут строго по одному, с паузой не меньше `DREBEDENGI_MIN_INTERVAL_MS` (по умолчанию 1 с);
- справочники (счета, категории, источники, валюты, теги) загружаются один раз; затем не чаще чем раз в 10 минут
  сервер сверяет ревизию (`getCurrentRevision`) и через `getChangeList` перезагружает только изменившиеся списки;
  раз в 6 часов справочники обновляются полностью на случай, если ревизия что-то не отразила;
- если название не найдено в кэше, перезагружается только нужный список (не чаще раза в минуту);
- после добавления/изменения операции подтверждение собирается локально, без повторного чтения.

Первый вызов после запуска — около 7 запросов (≈10 с), следующие — 1–2 запроса.

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

| Переменная | Описание |
|---|---|
| `DREBEDENGI_LOGIN` | E-mail для входа |
| `DREBEDENGI_PASSWORD` | Пароль |
| `DREBEDENGI_API_ID` | API ID от поддержки drebedengi (`demo_api` — только для демо-аккаунта) |
| `DREBEDENGI_MIN_INTERVAL_MS` | Минимальная пауза между запросами к API, мс (по умолчанию 1000) |
| `DREBEDENGI_REF_CHECK_MS` | Как часто сверять ревизию справочников, мс (по умолчанию 600000) |
| `DREBEDENGI_DEFAULT_ACCOUNT` | Счёт по умолчанию для `add_expense` / `add_income` |
| `DREBEDENGI_READONLY` | `1` — только чтение, инструменты записи не регистрируются |
| `DREBEDENGI_ENV_FILE` | Путь к другому `.env` |

Переменные можно задать в `.env` рядом с `package.json` или в конфиге MCP-клиента (`env`).

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

**Claude Code** (укажите свой путь к папке):

```bash
claude mcp add drebedengi -- node /path/to/drebedengi-mcp/src/server.js
```

**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "drebedengi": {
      "command": "node",
      "args": ["C:/path/to/drebedengi-mcp/src/server.js"]
    }
  }
}
```

## Тесты

`npm test` прогоняет все инструменты через MCP-клиент на публичном демо-аккаунте
(`demo@example.com` / `demo`): создаёт тестовые операции и затем удаляет их. На свой аккаунт его не направляйте —
для него есть `npm run smoke` (только чтение).

## Особенности API

- Протокол — SOAP rpc/encoded (PHP), ассоциативные массивы передаются как `ns2:Map`; клиент написан вручную в `src/soap.js`.
- Расход хранится с отрицательной суммой, доход — с положительной. Перевод и обмен — две связанные записи
  (`client_move_id` / `client_change_id`), исходящая половина отрицательная.
- `client_id` при вставке должен быть уникальным: сервер запоминает соответствие client→server.
- Если в аккаунте закрыт период, запись задним числом будет отклонена с сообщением «Период закрыт для изменений».

## Лицензия

[MIT](LICENSE) — код можно свободно копировать, изменять, распространять и использовать в любых целях,
в том числе коммерческих. Единственное условие — сохранять текст лицензии с указанием автора.

Автор и владелец репозитория — Denis B. ([@hawk911](https://github.com/hawk911)).