PRRO.cloud

prro-mcp

适用于 PRRO.cloud API 的 MCP 服务。让 AI 助手 （Claude Code、Claude Desktop、Cursor 及其他 Model Context Protocol 客户端）访问您的收银机、 班次、财政任务、账单和 Webhook。

适用对象：将 PRRO 集成到商店或会计系统中的开发者。 助手可以查看收银机、任务和 Webhook 投递的实际状态，并帮助 编写和调试集成：为何收据未能通过、班次是否已开启、是否为 测试班次、Webhook 接收方返回了什么。

• 只读。 所有工具都不会向国家税务局登记文档，不会 开启或关闭班次，也不会更改设置。
• 可通过 stdio 在本地运行（令牌来自环境变量），也可作为 远程服务 https://mcp.prro.cloud/mcp 运行（令牌放在 Authorization 标头中），无需安装任何内容。
• 基于 prro-go 和 MCP 官方 Go SDK 构建。
• 向助手提供 API 契约（OpenAPI），用于编写集成代码。

令牌

在控制台的令牌部分，为助手签发一个单独的 机器令牌：

• 将令牌限制为助手需要查看的收银机（最好是测试收银机）；
• 只有拥有所有收银机访问权限的令牌才能读取账单、发票和 Webhook；
• 可在控制台中通过 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 标头中传递令牌；服务会将其转发到 PRRO.cloud API，且不会在任何地方存储。每个令牌的限额为每分钟 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 的 Web 连接器，以及通过“Add custom connector”添加的 Claude Desktop 连接器，都需要服务不支持的 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	替代 https://api.prro.cloud 的 API 地址——用于本地测试环境。
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