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 に転送し、どこにも保存しません。制限は 1 つのトークンにつき 1 分あたり 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 のウェブコネクタ、および「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 使用時のみ有効です。1 つのトークンにつき 1 分あたりのリクエスト数です。デフォルトは 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