prro-mcp

# prro-mcp

[![CI](https://github.com/prro-cloud/prro-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/prro-cloud/prro-mcp/actions/workflows/ci.yml)

MCP-сервер для API [PRRO.cloud](https://prro.cloud). Дає ІІ-асистентам
(Claude Code, Claude Desktop, Cursor та іншим клієнтам
[Model Context Protocol](https://modelcontextprotocol.io)) доступ до ваших кас,
змін, фіскальних завдань, білінгу і вебхуків.

Для кого: розробники, які інтегрують ПРРО в магазин чи облікову систему.
Асистент бачить реальний стан кас, завдань і доставок вебхуків і допомагає
писати й налагоджувати інтеграцію: чому чек не пройшов, чи відкрита зміна, чи
тестова вона, що відповів приймач вебхука.

- **Лише читання.** Жоден інструмент не реєструє документів у ДПС, не
  відкриває і не закриває змін, не змінює налаштувань.
- Працює локально через stdio; токен береться зі змінної оточення.
- Побудований на [prro-go](https://github.com/prro-cloud/prro-go) і
  офіційному [Go SDK](https://github.com/modelcontextprotocol/go-sdk) MCP.
- Віддає асистенту контракт API (OpenAPI) — для написання коду інтеграції.

## Токен

Випустіть **окремий** машинний токен для асистента в
[кабінеті](https://app.prro.cloud/), у розділі токенів:

- обмежте його касами, які асистент має бачити (найкраще — тестовою касою);
- білінг, рахунки і вебхуки читає лише токен з доступом до всіх кас;
- відкликати токен можна в кабінеті за ідентифікатором `jti` — його показує
  інструмент `whoami`.

Токен — облікові дані: не комітьте конфігурацію MCP-клієнта з ним у
репозиторій.

## Встановлення

**Claude Desktop** — завантажте `prro-mcp.mcpb` з
[останнього релізу](https://github.com/prro-cloud/prro-mcp/releases/latest),
відкрийте його двічі клацнувши і вставте токен у налаштуваннях розширення.
Пакет містить збірки для macOS і Windows.

**Готовий бінарник** — архів для Linux, macOS або Windows (amd64/arm64) з
[релізів](https://github.com/prro-cloud/prro-mcp/releases); розпакуйте
`prro-mcp` у каталог із `PATH`.

**Go** (потрібен Go 1.27 або новіший):

```sh
go install github.com/prro-cloud/prro-mcp/cmd/prro-mcp@latest
```

**Docker:**

```sh
docker run -i --rm -e PRRO_TOKEN ghcr.io/prro-cloud/prro-mcp
```

Перевірка: `prro-mcp -version`.

## Налаштування клієнтів

### Claude Code

```sh
claude mcp add prro --env PRRO_TOKEN=ваш_токен -- prro-mcp
```

Або для всієї команди — у `.mcp.json` в корені проєкту; токен кожен бере зі
свого оточення, тож файл можна комітити:

```json
{
  "mcpServers": {
    "prro": {
      "command": "prro-mcp",
      "env": { "PRRO_TOKEN": "${PRRO_TOKEN}" }
    }
  }
}
```

### Claude Desktop

Найпростіше — пакет `prro-mcp.mcpb` (див. [Встановлення](#встановлення)).
Вручну — у `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "prro": {
      "command": "/повний/шлях/до/prro-mcp",
      "env": { "PRRO_TOKEN": "ваш_токен" }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` (для всіх проєктів) або `.cursor/mcp.json` у проєкті:

```json
{
  "mcpServers": {
    "prro": {
      "command": "prro-mcp",
      "env": { "PRRO_TOKEN": "${env:PRRO_TOKEN}" }
    }
  }
}
```

### Docker у будь-якому клієнті

```json
{
  "mcpServers": {
    "prro": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "PRRO_TOKEN", "ghcr.io/prro-cloud/prro-mcp"],
      "env": { "PRRO_TOKEN": "ваш_токен" }
    }
  }
}
```

### Змінні оточення

| Змінна | Призначення |
|---|---|
| `PRRO_TOKEN` | Машинний токен API. Обов'язкова. |
| `PRRO_BASE_URL` | Адреса API замість `https://api.prro.cloud` — для локального стенда. |
| `PRRO_LANG` | Мова повідомлень про помилки API: `uk` (типово) або `en`. |
| `PRRO_MCP_LOG_LEVEL` | Рівень журналу: `debug`, `info` (типово), `warn`, `error`. Журнал іде в stderr; на `debug` видно запити до API. Токен у журнал не потрапляє. |

## Інструменти

Усі інструменти лише читають і позначені `readOnlyHint`. Результат —
структуровані дані (`structuredContent` за вихідною схемою) плюс коротке
текстове зведення. Гроші — рядками, як в API: суми чеків і готівки — у
гривнях, суми білінгу — у копійках.

| Інструмент | Що повертає |
|---|---|
| `get_version` | Версія сервісу PRRO.cloud, контракту API, prro-mcp і prro-go. |
| `whoami` | Клієнт, дозволи токена, доступні каси, строк дії. |
| `get_dps_status` | Режим роботи з ДПС (онлайн/офлайн) і телеметрія детектора. |
| `list_cash_registers` | Каси, доступні токену: ідентифікатор, фіскальний номер, режим, стан. |
| `get_cash_register_state` | Стан каси: зміна (зокрема тестова), підсумки зміни, готівка, офлайн-сесія, позначка «потребує уваги». |
| `get_task` | Фіскальне завдання: стан, результат (фіскальний номер, посилання на чек) або опис збою ДПС. |
| `get_billing_usage` | Баланс, поріг блокування, кількість і вартість чеків за період. |
| `list_invoices` | Рахунки за розрахункові періоди. |
| `list_webhooks` | Вебхуки, їхні підписки і ліміт кількості. |
| `list_webhook_deliveries` | Історія доставок вебхука з помилками приймача. |

**Ресурс** `prro://openapi.yaml` — публічний контракт API (OpenAPI 3.1), з
яким зібрано сервер. Асистент читає його, коли пише код інтеграції.

Свідомо **не входять** у v0.1 операції, що пишуть: реєстрація чеків,
відкриття і закриття змін, заява залишку готівки, керування офлайн-сесіями,
зняття позначки уваги, створення, зміна, видалення і повтор вебхуків.

## Приклади запитів

- «Які каси бачить мій токен і чи відкрита на них зміна?»
- «Чому завдання `0199…` завершилося помилкою і що з цим робити?»
- «Покажи невдалі доставки вебхука за останній день і поясни, що не так із
  моїм приймачем.»
- «Скільки чеків ми пробили у вересні і скільки це коштувало?»
- «Напиши обробник вебхука `task.failed` на Go за контрактом API.»

## Розробка

```sh
make test       # тести з -race
make lint       # golangci-lint
make build      # bin/prro-mcp
make sync-spec  # оновити копію контракту з ../prro-go
```

Тест контракту звіряє інструменти з `internal/spec/openapi.yaml`: кожна
операція контракту або обслуговується інструментом, або явно виключена —
нова операція в контракті валить тест.

### Випуск

1. Перенести зміни з `[Unreleased]` у розділ версії в `CHANGELOG.md`.
2. `git tag v0.1.0 && git push origin v0.1.0` — workflow `Release` збере
   архіви, образ `ghcr.io/prro-cloud/prro-mcp`, пакет `prro-mcp.mcpb` і
   `server.json` з SHA-256 пакета, додасть їх до релізу, а workflow
   `MCP Registry` опублікує `server.json` у реєстрі MCP через GitHub OIDC.
   Повторити публікацію для вже випущеного тега:
   `gh workflow run registry.yml -f tag=v0.1.0`.
3. Покласти `server.json` із релізу в корінь репозиторію і закомітити.

Локально без публікації: `make snapshot`, потім `scripts/mcpb.sh 0.0.0`.

## Ліцензія

[Apache 2.0](LICENSE)