Prro MCP Server

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

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

Інструменти

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

Ресурс 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 у цьому режимі заборонений — токен приходить від клієнта. TLS забезпечує зворотний проксі перед сервером.

docker run -d --name prro-mcp --restart unless-stopped --stop-timeout 30 \
  -p 127.0.0.1:8080:8080 ghcr.io/prro-cloud/prro-mcp:0.2.0 -http :8080
curl -fsS http://127.0.0.1:8080/healthz

Наприклад, Caddy (сертифікат випустить сам):

mcp.prro.cloud {
	reverse_proxy 127.0.0.1:8080
}

Відповіді — звичайний JSON, без SSE, тож буферизацію в проксі вимикати не треба. Екземпляри не мають спільного стану і масштабуються горизонтально; ліміт запитів рахується в кожному екземплярі окремо.

Ліміт сервера рахується за токеном, а чи справжній токен, знає лише API: потік запитів із вигаданими токенами він не зупинить. Від цього захищає ліміт за IP на проксі (rate_limit у Caddy, limit_req у nginx). Після SIGTERM сервер чекає на поточні виклики до 25 секунд, тож --stop-timeout має бути більшим.

Ліцензія

Apache 2.0