# invoices-mcp

MCP-сервер сервиса выставления счетов и актов: счета, акты, контрагенты, договоры, оплаты,
номенклатура, отчёты, публичные ссылки — для любого MCP-клиента (Claude Desktop, Claude Code,
Cursor, VS Code, собственный агент).

**Версия:** `0.1.3` · **Node.js:** 20+ · **Транспорт:** stdio (по умолчанию) или Streamable HTTP.
Пакет ставится прямо из этого репозитория, без сборки на вашей машине и без публикации в npm.

## Что умеет

- **34 инструмента.** Чтение: организации, контрагенты и их карта взаимоотношений, документы и
  оплаты по ним, договоры, номенклатура, отчёты (сводка, дебиторка, акт сверки, реестр), публичные
  ссылки. Запись: создание контрагента, позиции, черновика счёта или акта, выдача, аннулирование,
  удаление черновика, оплаты, договоры, ссылки. Любая изменяющая операция требует `confirm: true` —
  без него запрос в API вообще не уходит.
- **6 ресурсов-шаблонов** (`invoice://`, `invoice://…/pdf`, `act://`, `contractor://`,
  `organization://`, `contract://`) — карточки для чтения моделью по ссылке.
- **4 промпта** — готовые сценарии: счёт по описанию, сводка по контрагенту, разбор дебиторки,
  акт по счёту.

Права определяет **только токен**: readonly-токен не сможет ничего изменить, и MCP не даёт способа
это обойти.

## Установка

### Через `npx` из git (рекомендуется)

```bash
npx -y github:valderan/invoices-mcp#v0.1.3
```

Первый запуск занимает больше времени: npm скачивает пакет и четыре его зависимости
(`@modelcontextprotocol/*`, `zod`). Дальше они берутся из кеша (`~/.npm/_npx`).

> Указывайте **тег** (`#v0.1.3`), а не `#main`: npm кеширует по коммиту, и без тега легко
> остаться на старой копии.

### Локально

```bash
git clone https://github.com/valderan/invoices-mcp.git
cd invoices-mcp
npm install --omit=dev
INVOICES_API_URL=https://crm.example.ru INVOICES_API_TOKEN=ivs_… node dist/index.js
```

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

```bash
npx -y github:valderan/invoices-mcp#v0.1.3 --version   # invoices-mcp 0.1.3
npx -y github:valderan/invoices-mcp#v0.1.3 --help
```

## Настройка

Только переменные окружения — файлов конфигурации нет.

| Переменная                  | Обязательно | По умолчанию | Что это                                                                                                                                                               |
| --------------------------- | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVOICES_API_URL`          | да          | —            | Базовый адрес API без `/api/v1`, например `https://crm.example.ru`. `http://` допустим только для `localhost`/`127.0.0.1` и для хостов из `INVOICES_ALLOW_HTTP_HOSTS` |
| `INVOICES_ALLOW_HTTP_HOSTS` | нет         | —            | Хосты через запятую, где разрешён `http://` помимо localhost: нужно, когда сервер запускается в контейнере (`host.docker.internal`)                                   |
| `INVOICES_API_TOKEN`        | да          | —            | Сервисный токен `ivs_<kid>_<secret>` из админки, раздел «Токены»                                                                                                      |
| `INVOICES_MCP_TRANSPORT`    | нет         | `stdio`      | `stdio` или `http`                                                                                                                                                    |
| `INVOICES_MCP_PORT`         | нет         | `7331`       | Порт HTTP-транспорта (слушает только `127.0.0.1`)                                                                                                                     |
| `INVOICES_TIMEOUT_MS`       | нет         | `10000`      | Таймаут запроса к API                                                                                                                                                 |
| `INVOICES_LOG_LEVEL`        | нет         | `info`       | `debug`, `info`, `warn`, `error`                                                                                                                                      |

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

Везде одна схема: команда `npx`, аргументы с тегом, токен в `env`.

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "invoices": {
      "command": "npx",
      "args": ["-y", "github:valderan/invoices-mcp#v0.1.3"],
      "env": {
        "INVOICES_API_URL": "https://crm.example.ru",
        "INVOICES_API_TOKEN": "ivs_AbCdEf12_…"
      }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` (или `.cursor/mcp.json` в проекте) — тот же блок `mcpServers`.

### Claude Code

```bash
claude mcp add invoices \
  --env INVOICES_API_URL=https://crm.example.ru \
  --env INVOICES_API_TOKEN=ivs_AbCdEf12_… \
  -- npx -y github:valderan/invoices-mcp#v0.1.3
```

### VS Code

`.vscode/mcp.json` — ключ `servers`:

```json
{
  "servers": {
    "invoices": {
      "command": "npx",
      "args": ["-y", "github:valderan/invoices-mcp#v0.1.3"],
      "env": {
        "INVOICES_API_URL": "https://crm.example.ru",
        "INVOICES_API_TOKEN": "ivs_AbCdEf12_…"
      }
    }
  }
}
```

### HTTP-режим

Если клиент умеет Streamable HTTP, сервер можно держать запущенным отдельно:

```bash
INVOICES_MCP_TRANSPORT=http INVOICES_MCP_PORT=7331 \
INVOICES_API_URL=https://crm.example.ru INVOICES_API_TOKEN=ivs_… \
npx -y github:valderan/invoices-mcp#v0.1.3
```

Клиент подключается к `http://127.0.0.1:7331/mcp`. Сервер слушает **только loopback** и проверяет
`Host`/`Origin` (защита от DNS rebinding): подключиться с другой машины нельзя, для этого нужен
обратный прокси. Плюс режима — токен не лежит в конфиге каждого пользователя.

## Токены и приватность

- Токен даёт ровно те права, что выданы при его создании: `readonly` — только чтение, `full` —
  чтение и запись. MCP не расширяет доступ и не обходит `403`.
- Сервер **отправляет данные в модель**, включая локальные: суммы, названия контрагентов, ИНН,
  номера документов. Если это неприемлемо для ваших клиентов — используйте readonly-токен и
  ограничьте доступ на стороне API.
- Токен хранится в конфиге клиента. Утечка конфига = утечка токена: заводите отдельный токен на
  каждую машину и отзывайте его в админке, раздел «Токены».
- В логах сервера только публичная часть токена (`kid`), суммы и содержимое документов не пишутся.

## Ошибки

| Симптом                                            | Что делать                                                                 |
| -------------------------------------------------- | -------------------------------------------------------------------------- |
| `Токен недействителен, истёк или отозван`          | Создайте новый токен в админке → «Токены»                                  |
| `У токена нет нужного права (не хватает скоупа …)` | Нужен токен с записью (`full`) для этой операции                           |
| `403 IP_NOT_ALLOWED`                               | У токена ограничение по IP — добавьте адрес машины или уберите ограничение |
| `Не найдено или недоступно этому токену`           | Проверьте идентификатор поиском: возможно, объект из другой организации    |
| `Превышен таймаут запроса к API`                   | Увеличьте `INVOICES_TIMEOUT_MS` или проверьте сеть                         |
| `конфигурация не загружена`                        | Не заданы `INVOICES_API_URL` / `INVOICES_API_TOKEN`                        |

Ответ инструмента ограничен 64 КБ: длинные списки сокращаются, в тексте появляется подсказка —
уточните фильтры или передайте `cursor` из предыдущего ответа.

## Версии

Версионирование — [SemVer](https://semver.org/lang/ru/), каждая версия помечена тегом `vX.Y.Z`,
история — в [CHANGELOG.md](CHANGELOG.md). Устанавливайте с тегом: `github:valderan/invoices-mcp#v0.1.3`.

Совместимость: новые инструменты и необязательные поля — minor; исправления поведения — patch;
удаление или переименование инструмента, обязательного аргумента или поля ответа — major.

## Лицензия

Проприетарная: использовать разрешено, копировать, распространять, изменять и встраивать в свои
продукты — нет. Полный текст — в [LICENSE](LICENSE).