PRRO.cloud

prro-mcp

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

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

• Лише читання. Жоден інструмент не реєструє документів у ДПС, не відкриває і не закриває змін, не змінює налаштувань.
• Працює локально через stdio (токен — зі змінної оточення) або як віддалений сервер https://mcp.prro.cloud/mcp (токен — у заголовку Authorization), нічого не встановлюючи.
• Побудований на 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.

Віддалений сервер

https://mcp.prro.cloud/mcp — той самий набір інструментів без встановлення. Токен передається в заголовку Authorization: Bearer кожного запиту; сервер пересилає його в API PRRO.cloud і ніде не зберігає. Ліміт — 120 запитів на хвилину з одним токеном.

Claude Code:

claude mcp add --transport http prro https://mcp.prro.cloud/mcp \
  --header "Authorization: Bearer ваш_токен"

Або в .mcp.json проєкту (токен — з оточення кожного розробника):

{
  "mcpServers": {
    "prro": {
      "type": "http",
      "url": "https://mcp.prro.cloud/mcp",
      "headers": { "Authorization": "Bearer ${PRRO_TOKEN}" }
    }
  }
}

Cursor — ~/.cursor/mcp.json або .cursor/mcp.json:

{
  "mcpServers": {
    "prro": {
      "url": "https://mcp.prro.cloud/mcp",
      "headers": { "Authorization": "Bearer ${env:PRRO_TOKEN}" }
    }
  }
}

Веб-конектори claude.ai і ChatGPT, а також Claude Desktop через «Add custom connector» вимагають OAuth, якого сервер не підтримує, — для них лишається локальний сервер.

Налаштування локального сервера

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. Токен у журнал не потрапляє.
PRRO_MCP_RATE_LIMIT	Лише з -http: запитів на хвилину з одним токеном, типово 120; 0 — без ліміту.

Інструменти

Усі інструменти лише читають і позначені 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), з яким зібрано сервер. Асистент читає його, коли пише код інтеграції.

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

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

• «Які каси бачить мій токен і чи відкрита на них зміна?»
• «Чому завдання 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: кожна операція контракту або обслуговується інструментом, або явно виключена — нова операція в контракті валить тест.

Випуск

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.

server.json містить і віддалений сервер (remotes), тож версію з ним публікувати лише тоді, коли https://mcp.prro.cloud/mcp уже працює.

Розгортання віддаленого сервера

З прапорцем -http сервер слухає Streamable HTTP без сесій: MCP на /mcp, перевірка живості на /healthz; токен приходить від клієнта, PRRO_TOKEN у цьому режимі заборонений. Файл Compose, змінні, приклади Caddy і nginx, вимоги до проксі й безпеки — у deploy/.

Ліцензія

Apache 2.0