PRRO.cloud

Server MCP hanya-baca untuk PRRO.cloud: mesin kasir fiskal Ukraina, shift, tugas fiskal, penagihan, dan webhook.

Dokumentasi

prro-mcp

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

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

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

Токен

Випустіть окремий машинний токен для асистента в кабінеті, у розділі токенів:

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

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

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

Claude Desktop — завантажте prro-mcp.mcpb з останнього релізу, відкрийте його двічі клацнувши і вставте токен у налаштуваннях розширення. Пакет містить збірки для macOS і Windows.

Готовий бінарник — архів для Linux, macOS або Windows (amd64/arm64) з релізів; розпакуйте prro-mcp у каталог із PATH.

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

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

Docker:

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

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

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

Claude Code

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

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

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

Claude Desktop

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

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

Cursor

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

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

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

{
  "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.»

Розробка

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

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

Випуск

Перенести зміни з [Unreleased] у розділ версії в CHANGELOG.md.
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.
Покласти server.json із релізу в корінь репозиторію і закомітити.

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

Ліцензія

Apache 2.0