PRRO.cloud

Servidor MCP de solo lectura para PRRO.cloud: registradoras fiscales ucranianas, turnos, tareas fiscales, facturación y webhooks.

GitHub

Documentación

prro-mcp

Servidor MCP para la API de PRRO.cloud. Brinda a los asistentes de IA (Claude Code, Claude Desktop, Cursor y otros clientes de Model Context Protocol) acceso a sus cajas, turnos, tareas fiscales, facturación y webhooks.

Para quién: desarrolladores que integran PRRO en una tienda o sistema contable. El asistente ve el estado real de las cajas, tareas y entregas de webhooks y ayuda a escribir y depurar la integración: por qué no pasó un recibo, si el turno está abierto, si es de prueba, qué respondió el receptor del webhook.

Solo lectura. Ninguna herramienta registra documentos en el Servicio Estatal de Impuestos de Ucrania (SFS), no abre ni cierra turnos, ni cambia configuraciones.
Funciona localmente a través de stdio; el token se toma de una variable de entorno.
Construido sobre prro-go y el Go SDK oficial de MCP.
Entrega al asistente el contrato de API (OpenAPI) — para escribir código de integración.

Token

Emita un token de máquina separado para el asistente en el panel, en la sección de tokens:

limítelo a las cajas que el asistente debe ver (idealmente, una caja de prueba);
la facturación, las facturas y los webhooks solo los lee un token con acceso a todas las cajas;
puede revocar el token en el panel por el identificador jti — lo muestra la herramienta whoami.

El token es una credencial: no confirme la configuración del cliente MCP con él en el repositorio.

Instalación

Claude Desktop — descargue prro-mcp.mcpb desde el último lanzamiento, ábralo con doble clic e inserte el token en la configuración de la extensión. El paquete incluye compilaciones para macOS y Windows.

Binario listo — archivo para Linux, macOS o Windows (amd64/arm64) desde lanzamientos; descomprima prro-mcp en un directorio con PATH.

Go (requiere Go 1.27 o superior):

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

Verificación: prro-mcp -version.

Configuración de clientes

Claude Code

claude mcp add prro --env PRRO_TOKEN=ваш_токен -- prro-mcp

O para todo el equipo — en .mcp.json en la raíz del proyecto; cada uno toma el token de su propio entorno, por lo que el archivo se puede confirmar:

{
  "mcpServers": {
    "prro": {
      "command": "prro-mcp",
      "env": { "PRRO_TOKEN": "${PRRO_TOKEN}" }
    }
  }
}

Claude Desktop

La forma más sencilla — el paquete prro-mcp.mcpb (ver Instalación). Manual — en claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "prro": {
      "command": "/повний/шлях/до/prro-mcp",
      "env": { "PRRO_TOKEN": "ваш_токен" }
    }
  }
}

Cursor

~/.cursor/mcp.json (para todos los proyectos) o .cursor/mcp.json en el proyecto:

{
  "mcpServers": {
    "prro": {
      "command": "prro-mcp",
      "env": { "PRRO_TOKEN": "${env:PRRO_TOKEN}" }
    }
  }
}

Docker en cualquier cliente

{
  "mcpServers": {
    "prro": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "PRRO_TOKEN", "ghcr.io/prro-cloud/prro-mcp"],
      "env": { "PRRO_TOKEN": "ваш_токен" }
    }
  }
}

Variables de entorno

Variable	Propósito
`PRRO_TOKEN`	Token de máquina de la API. Obligatoria.
`PRRO_BASE_URL`	Dirección de la API en lugar de `https://api.prro.cloud` — para un entorno local.
`PRRO_LANG`	Idioma de los mensajes de error de la API: `uk` (predeterminado) o `en`.
`PRRO_MCP_LOG_LEVEL`	Nivel de registro: `debug`, `info` (predeterminado), `warn`, `error`. El registro va a stderr; en `debug` se ven las solicitudes a la API. El token no aparece en el registro.

Herramientas

Todas las herramientas son de solo lectura y están marcadas con readOnlyHint. El resultado — datos estructurados (structuredContent según el esquema original) más un breve resumen de texto. El dinero — como cadenas, como en la API: montos de recibos y efectivo — en grivnas, montos de facturación — en kopeks.

Herramienta	Qué devuelve
`get_version`	Versión del servicio PRRO.cloud, del contrato de API, de prro-mcp y de prro-go.
`whoami`	Cliente, permisos del token, cajas disponibles, fecha de vencimiento.
`get_dps_status`	Modo de operación con el SFS (en línea/fuera de línea) y telemetría del detector.
`list_cash_registers`	Cajas disponibles para el token: identificador, número fiscal, modo, estado.
`get_cash_register_state`	Estado de la caja: turno (incluido el de prueba), resúmenes del turno, efectivo, sesión fuera de línea, marca de «requiere atención».
`get_task`	Tarea fiscal: estado, resultado (número fiscal, enlace al recibo) o descripción de la falla del SFS.
`get_billing_usage`	Saldo, umbral de bloqueo, cantidad y costo de recibos por período.
`list_invoices`	Facturas por períodos de facturación.
`list_webhooks`	Webhooks, sus suscripciones y el límite de cantidad.
`list_webhook_deliveries`	Historial de entregas de webhooks con errores del receptor.

Recurso prro://openapi.yaml — contrato público de API (OpenAPI 3.1), con el que se compiló el servidor. El asistente lo lee cuando escribe código de integración.

Conscientemente no se incluyen en v0.1 operaciones de escritura: registro de recibos, apertura y cierre de turnos, declaración de saldo de efectivo, gestión de sesiones fuera de línea, eliminación de la marca de atención, creación, modificación, eliminación y reintento de webhooks.

Ejemplos de solicitudes

«¿Qué cajas ve mi token y hay un turno abierto en ellas?»
«¿Por qué la tarea 0199… terminó con error y qué hacer al respecto?»
«Muestra las entregas fallidas de webhooks del último día y explica qué está mal con mi receptor.»
«¿Cuántos recibos emitimos en septiembre y cuánto costó?»
«Escribe un manejador de webhook task.failed en Go según el contrato de API.»

Desarrollo

make test       # тести з -race
make lint       # golangci-lint
make build      # bin/prro-mcp
make sync-spec  # оновити копію контракту з ../prro-go

La prueba de contrato compara las herramientas con internal/spec/openapi.yaml: cada operación del contrato o está atendida por una herramienta, o está explícitamente excluida — una nueva operación en el contrato hace fallar la prueba.

Lanzamiento

Mover los cambios de [Unreleased] a la sección de versión en CHANGELOG.md.
git tag v0.1.0 && git push origin v0.1.0 — el workflow Release compilará los archivos, la imagen ghcr.io/prro-cloud/prro-mcp, el paquete prro-mcp.mcpb y server.json con SHA-256 del paquete, los agregará al lanzamiento, y el workflow MCP Registry publicará server.json en el registro de MCP a través de GitHub OIDC. Repetir la publicación para una etiqueta ya lanzada: gh workflow run registry.yml -f tag=v0.1.0.
Colocar server.json del lanzamiento en la raíz del repositorio y confirmarlo.

Localmente sin publicación: make snapshot, luego scripts/mcpb.sh 0.0.0.

Licencia

Apache 2.0