PRRO.cloud

prro-mcp

[CI]

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": "ваш_токен" }    }  }}

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

Інструменти

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

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

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

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

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

Розробка

make test       # тести з -racemake lint       # golangci-lintmake build      # bin/prro-mcpmake 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