mcp-reportia

Servidor MCP (Model Context Protocol) independiente que envuelve la API HTTP real de Reportia y la expone a través del transporte stdio con JSON-RPC newline-delimited. Pensado para ser consumido por clientes MCP (Claude Desktop, Cursor, Hermes Agent, otros) con un único npx, sin ejecutar código de servidor propio.

Esta capa no contiene lógica de negocio ni secretos propios: actúa como traductor entre el protocolo MCP y los endpoints REST de Reportia. Las credenciales se inyectan desde variables de entorno.

Índice

• Dónde está indexado
• Instalación y uso rápido
• Variables de entorno
• Configuración en clientes MCP
• Flujo de release
• Herramientas disponibles
• Limitaciones conocidas
• Seguridad
• Rutas cubiertas y omitidas
• Desarrollo local
• Pruebas
• Inspección con MCP Inspector
• Arquitectura interna
• Licencia

Dónde está indexado

Este servidor MCP está publicado y discoverable en:

Instalación via skills.sh:

npx skills add javalenciacai/mcp-reportia --skill reportia-mcp-usage

Flujo de release

Este repo publica automáticamente a npm y al MCP Registry oficial cuando se pushea un tag v* a main. La indexación en skills.sh es automática (scrapeo de GitHub).

Configuración inicial (una sola vez)

Opción elegida: npm Trusted Publishing (OIDC)

La configuración vive en la página del paquete (no en /settings/james.valencia/security — esa URL es para tokens tradicionales).

1. Abre https://www.npmjs.com/package/@james.valencia/mcp-reportia/settings (logueado como james.valencia en el navegador).

2. En la sección "Trusted Publisher", click en "Add a trusted publisher" (o "GitHub Actions" según el wording de tu versión de npmjs.com).

3. Completa el formulario con estos valores exactos (la doc oficial los lista así):

   Campo	Valor
   Provider	GitHub Actions
   Organization or user	javalenciacai
   Repository	mcp-reportia
   Workflow filename	publish.yml (solo el nombre, sin la ruta .github/workflows/)
   Environment name	(vacío) — el workflow no usa GitHub Environments
   Allowed actions	npm publish (al menos uno)

4. Click "Add" o "Save". npm NO valida la configuración al guardar, pero el workflow fallará en runtime si los datos no coinciden exactamente.

Subir el workflow a Node 24 (necesario para Trusted Publishing)

Trusted Publishing requiere npm >= 11.5.1, que viene incluido en Node.js 24. El workflow actual usa Node 22 (npm 10.9) — fallará con ENEEDAUTH aunque el publisher esté bien configurado.

Lo que voy a hacer yo cuando confirmes el paso 1: actualizar el workflow a Node 24, hacer commit, re-crear el tag v0.1.2 apuntando al nuevo commit, re-disparar el publish.

Verificación rápida de que está bien

Re-dispara manualmente el workflow y mira el log del job publish-npm:

gh workflow run Publish --ref v0.1.2
gh run watch --exit-status

Si dice OK: @james.valencia/mcp-reportia@0.1.2 publicado en el último step, está funcionando. Si vuelve a fallar, mandame el output del step "Publish" (sin el token).

Estado actual de los requisitos

Plan al terminar tu paso 1

Voy a ejecutar en este orden (no requiere tu input):

1. Cambiar node-version: '22' → '24' en ambos jobs del workflow publish
2. Verificar con npm test && npm run build local
3. Commit + push
4. Re-crear el tag v0.1.2 apuntando al nuevo commit
5. Observar el workflow Publish hasta publish-npm exitoso
6. Reportarte el resultado final (versión en npm + GitHub Release creado)

Hacer un release

# 1. Bump de version (esto actualiza package.json y server.json automaticamente)
cd /c/james/mcp-reportia
npm version patch    # 0.1.1 -> 0.1.2 (o minor/major)

# 2. Push del commit + tag a GitHub
git push origin main --follow-tags
# (npm version ya crea el tag v0.1.2 y lo pushea junto con el commit)

GitHub Actions se dispara automáticamente:

1. Job validate — typecheck + test + build + smoke. Verifica que package.json.version y server.json.version coincidan con el tag.
2. Job publish-npm — publica a npm via OIDC (sin tokens de larga duración).
3. Job publish-mcp-registry — publica server.json al MCP Registry oficial.
4. Job release — crea un GitHub Release con notas auto-generadas.

Publicar manualmente (sin tag)

Si necesitas un release fuera del flujo normal, ve a GitHub → Actions → "Publish" → "Run workflow" y opcionalmente pasa un version override.

Rollback

Si necesitas revertir una versión publicada a npm (dentro de 72h):

npm unpublish @james.valencia/mcp-reportia@0.1.2

Después de 72h no es posible; debes publicar un patch. El MCP Registry no soporta rollback; hay que publicar una versión superior con la corrección.

Instalación y uso rápido

Una vez publicado, el consumo típico es vía npx:

# 1) Construir dist/ localmente (la primera vez, o al actualizar):
npm run build

# 2) Ejecutar el binario MCP directamente:
npx mcp-reportia

Los clientes MCP (Claude Desktop, Cursor, Hermes, etc.) lo invocan por ti como subproceso. No necesitas ejecutarlo a mano salvo para depurar.

Variables de entorno

* Exactamente una de las tres alternativas de auth debe estar presente:

• REPORTIA_TOKEN Bearer, o
• REPORTIA_EMAIL + REPORTIA_PASSWORD sesión cookie (el package hace POST /api/auth/login y captura la cookie), o
• REPORTIA_COOKIE sesión cookie pre-emitida (el package la usa directo, sin re-login).

Si pasás REPORTIA_TOKEN y REPORTIA_COOKIE a la vez, loadConfig lanza ConfigError con el mensaje REPORTIA_TOKEN y REPORTIA_COOKIE son mutuamente excluyentes — usa solo uno. para evitar que un token accidental sobreescriba una sesión per-user.

Precedencia cuando se establece una sola: cookie > bearer > session. cookie gana porque es la que matchea la identidad resuelta upstream; bearer es service-account; session es email+password login (el child se loguea a sí mismo).

Si no se establece ninguna, loadConfig lanza ConfigError al arrancar el servidor.

⚠️ No copies credenciales de C:\james\Reportia\.env a este repositorio. Este proyecto no debe contener secretos. Configúralas en el entorno del cliente MCP que lo invoque.

Revisa .env.example para ver todas las variables.

Configuración en clientes MCP

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)

Añade una entrada dentro de mcpServers:

{
  "mcpServers": {
    "reportia": {
      "command": "npx",
      "args": ["-y", "mcp-reportia"],
      "env": {
        "REPORTIA_BASE_URL": "https://reportia.example.com",
        "REPORTIA_TOKEN": "<tu-token>",
        "REPORTIA_COMPANY_ID": "123"
      }
    }
  }
}

Sustituye mcp-reportia por la ruta local C:\\james\\mcp-reportia durante desarrollo, con args: ["-y", "--prefix", "C:\\james\\mcp-reportia", "mcp-reportia"] o ejecutando npm run start como comando directo.

Cursor (%USERPROFILE%\.cursor\mcp.json)

{
  "mcpServers": {
    "reportia": {
      "command": "npx",
      "args": ["-y", "mcp-reportia"],
      "env": {
        "REPORTIA_BASE_URL": "https://reportia.example.com",
        "REPORTIA_TOKEN": "<tu-token>"
      }
    }
  }
}

Hermes Agent (plugin MCP vía ~/.hermes/config.toml o UI)

Añade un servidor MCP stdio de nombre reportia apuntando a npx mcp-reportia y exporta las variables en env.

Formato típico:

[[mcp_servers]]
name = "reportia"
command = "npx"
args = ["-y", "mcp-reportia"]
[mcp_servers.env]
REPORTIA_BASE_URL = "https://reportia.example.com"
REPORTIA_TOKEN    = "<tu-token>"
REPORTIA_COMPANY_ID = "123"

El nombre exacto del campo varía según la versión de Hermes. Consulta hermes mcp --help.

Caller que ya tiene la sesión del usuario (per-user, recomendado para servidores AI)

Cuando el caller (p.ej. un servidor AI multi-tenant) ya resolvió la sesión de Reportia del usuario activo y quiere que el child autentique como ese mismo usuario — sin re-login y sin service-account — pasale la cookie pre-emitida:

{
  "mcpServers": {
    "reportia": {
      "command": "npx",
      "args": ["-y", "mcp-reportia"],
      "env": {
        "REPORTIA_BASE_URL": "https://reportia.example.com",
        "REPORTIA_COOKIE": "connect.sid=s%3A<session-id-from-resolved-user>",
        "REPORTIA_COMPANY_ID": "123"
      }
    }
  }
}

El child NO va a llamar a /api/auth/login (se salta ese paso), NO va a llamar a /api/auth/logout al cerrar (la sesión es del caller, no del child), y va a hacer todas las requests Reportia con la identidad del usuario resuelto. Si el caller está corriendo detrás de un relay que captura la cookie del usuario en runtime (p.ej. la session-derived path del Cowork server), este es el modo de auth que se alinea con ese flujo.

Herramientas disponibles

El servidor expone 66 herramientas con el prefijo reportia_. Todas devuelven JSON (string con JSON.stringify pretty-print) y validan su input con Zod. Se agrupan por dominio funcional:

Salud y autenticación (src/tools/auth-health.ts)

Empresas (src/tools/companies.ts)

Movimientos contables (src/tools/accounting-movements.ts)

Mapeo de cuentas (src/tools/account-mappings.ts)

Reportes de comisiones (src/tools/commission-reports.ts)

Terceros (src/tools/third-parties.ts)

Vendedor × factura (src/tools/salesperson-invoice.ts)

Mapeos vendedor → factura, opciones de vendedor, listados de facturas, settings de factura y envío de facturas (email individual y masivo).

Línea × centro de costo (src/tools/line-cost-center.ts)

Dominio más extenso: gestiona mapeos línea-grupo, mapeos centro de costo, centros de costo disponibles, y todo el ciclo de vida de los reportes de centro de costo (CRUD + ejecutar + duplicar + exportes).

Operaciones (src/tools/operations.ts) — uploads, colas y SIIGO

Todas las tools de este módulo son read-only: historial/estado de uploads, salud del sistema de colas y de los workers, y herramientas de consulta sobre SIIGO (settings, clientes, corridas, trazas, schedules, historial). No hay tools de mutación, de subida multipart/form-data, ni de control de colas en esta versión.

⚠️ Las tools marcadas como Destructiva requieren el parámetro { "confirm": true } en su input. Si no se envía, el handler valida con assertConfirmed(input, '<tool-name>') (definido en src/tool-base.ts) y devuelve un error con code: "GUARD_REJECTED" antes de cualquier llamada HTTP. El LLM debe pedir confirmación explícita al usuario antes de invocarlas.

companyId puede omitirse si configuraste REPORTIA_COMPANY_ID; en caso contrario, es obligatorio en todas las tools que tocan datos por empresa.

Limitaciones conocidas

• Sin HTTP streaming / SSE: este servidor solo habla stdio. Clientes que solo soporten HTTP no pueden consumirlo directamente.
• Una sola ReportiaClient por proceso: el login es lazy y global; no se admite multi-cuenta simultánea.
• Subida de archivos (multipart/form-data): el cliente HTTP está preparado (FormData desde undici) pero las tools actuales no exponen endpoints de upload (no hay POST/PUT con multipart/form-data). Sí se exponen dos tools read-only sobre el histórico y estado de uploads existentes: reportia_uploads_history_list (GET /api/companies/:companyId/upload-history) y reportia_upload_status_get (GET /api/upload/:uploadId/status). Si Reportia añade en el futuro endpoints de carga, basta con añadir un ToolDefinition que use ctx.client.call(..., { formData }).
• Sin caché persistente: cada invocación vuelve a llamar a la API. El LLM debe sentirse libre de hacer tools/list cuando lo necesite.
• Errores HTTP: se traducen a tipos estructurados (AUTH_ERROR, NOT_FOUND, VALIDATION_ERROR, ROW_LIMIT_EXCEEDED, NETWORK_ERROR, TIMEOUT). El cliente nunca expone secretos en el mensaje.
• Smoke test offline: npm run test:smoke arranca el servidor con REPORTIA_BASE_URL=http://127.0.0.1:9 (puerto cerrado). No hace llamadas reales; solo valida el handshake MCP. Para pruebas integradas reales, usa npm run test:integration apuntando a un servidor Reportia accesible.
• Sin reintentos automáticos: ante 5xx el servidor reporta error; el LLM puede reintentar manualmente.

Seguridad

El servidor está diseñado para minimizar superficie de ataque cuando es invocado por un LLM:

• No hay herramienta HTTP genérica: las tools son curadas por dominio (66 endpoints específicos). El LLM no puede apuntar el cliente a una URL arbitraria ni a una IP interna.
• Validación Zod en cada input: ningún handler llega a la red sin antes pasar por un esquema que rechaza tipos, rangos y formatos inválidos.
• Tools destructivas requieren confirm: true literal: se declaran con destructive: true y verifican con assertConfirmed(...) antes de cualquier llamada HTTP. Si falta confirm, devuelven GUARD_REJECTED sin tocar la API. El LLM debe pedirle al usuario confirmación explícita antes de invocarlas.
• Interpolación segura en URLs: los IDs numéricos (companyId, mappingId, reportId, runId, uploadId) son validados como z.number().int().positive() antes de la interpolación. Los strings de path (NIT, invoiceId, mappingId de líneas/centros) usan encodeURIComponent y/o se restringen a un alfabeto seguro ([A-Za-z0-9-]+ para NITs).
• Cabeceras HTTP saneadas: el User-Agent configurable vía REPORTIA_USER_AGENT se sanitiza contra CRLF (header injection) en src/client.ts:sanitizeUserAgent.
• Sin secretos en logs: los mensajes de error exponen el endpoint y el código HTTP, pero nunca el token, la cookie, la contraseña ni el cuerpo completo del body. La cookie connect.sid se mantiene en memoria del cliente y nunca aparece en respuestas JSON.
• Login con cookie persistente: el modo sesión reutiliza la cookie connect.sid recibida de /api/auth/login y la rota solo si Reportia la renueva; nunca se escribe a disco.
• Tests de regresión de seguridad (tests/security.test.ts): 16 tests que verifican que ninguna tool destructiva omite confirm, que ningún esquema acepta inputs peligrosos, y que el orden de guards (resolveCompanyId → assertConfirmed) prefiere errores informativos sobre GUARD_REJECTED cuando el problema es de configuración.

Rutas cubiertas y omitidas

Cubiertas (tools/)

Omitidas (fuera de alcance de esta versión)

• Login por sesión desde una tool (no se necesita: ya se hace lazy desde ReportiaClient).
• Cualquier endpoint de subida (multipart/form-data) — la superficie se limita a GET /api/companies/:companyId/upload-history y GET /api/upload/:uploadId/status (read-only).
• Endpoints administrativos internos que requieren scopes no documentados públicamente.
• Versionado antiguo (/api/v0/*).

⚠️ Esta tabla refleja la superficie actual de src/tools/*.ts. Antes de añadir rutas nuevas, edita src/tools/<modulo>.ts, re-exporta en src/tools/index.ts y corre npm run typecheck && npm test.

Desarrollo local

Requisitos:

• Node.js ≥ 20
• npm ≥ 9

# 1) Instalar dependencias
npm install

# 2) Compilar TypeScript a dist/
npm run build

# 3) Verificar tipos sin emitir
npm run typecheck

# 4) Ejecutar el servidor (lee dist/server.js, stdio)
npm run start

Los tests no requieren Reportia levantada ni credenciales; usan entorno sintético.

Pruebas

# Suite unitaria (Vitest) — sin red, sin credenciales
npm test

# Smoke de protocolo MCP sobre stdio (sin credenciales reales)
npm run test:smoke

# Smoke de integracion contra un servidor Reportia REAL
# (configura REPORTIA_BASE_URL y REPORTIA_TOKEN en tu entorno antes).
npm run build
REPORTIA_BASE_URL=https://reportia.example.com \
REPORTIA_TOKEN=<tu-token> \
  npm run test:integration

El smoke test (scripts/jsonrpc-smoke.mjs) lanza dist/server.js como subproceso, le envía initialize + tools/list por JSON-RPC newline-delimited y verifica que la respuesta contenga al menos una herramienta. No realiza llamadas HTTP contra Reportia (apunta a 127.0.0.1:9).

El test de integración (scripts/integration-smoke.mjs) sí habla con un servidor Reportia real: hace initialize, tools/list, llama a reportia_health (que hace ping a /api/health) y a reportia_whoami (que debe devolver AUTH_ERROR con un token inválido para validar el manejo de errores). Útil para verificar que la versión desplegada sigue siendo compatible con el backend real.

Si solo quieres validar que la build no está rota:

npm test -- --passWithNoTests

Inspección con MCP Inspector

npm run inspect

Esto ejecuta npx @modelcontextprotocol/inspector node dist/server.js, que abre una UI web para enviar manualmente los métodos del protocolo (initialize, tools/list, tools/call, etc.).

Arquitectura interna

src/
├── server.ts               # Arranca McpServer + StdioServerTransport y registra tools.
├── config.ts               # Carga y valida env vars (Zod). Tres auth modes: bearer / session / cookie.
├── client.ts               # Cliente HTTP sobre undici. Bearer, sesión cookie propia, o cookie pre-emitida.
├── errors.ts               # Jerarquía ReportiaError.
├── tool-base.ts            # Helpers: ToolDefinition, ok/fail, resolveCompanyId, assertConfirmed.
└── tools/
    ├── index.ts            # allTools = union de los modulos.
    ├── auth-health.ts      # reportia_health / whoami / logout.
    ├── companies.ts        # reportia_companies_*.
    ├── accounting-movements.ts  # reportia_movements_*.
    ├── account-mappings.ts # reportia_account_mapping_* y account_codes_search.
    ├── commission-reports.ts # reportia_commission_*.
    └── third-parties.ts    # reportia_third_parties_*.

scripts/
└── jsonrpc-smoke.mjs       # Smoke de protocolo (sin red contra Reportia).

tests/
├── config.test.ts          # loadConfig.
├── resolve-company-id.test.ts # helpers de tool-base.
└── schema-validation.test.ts  # invariantes de allTools y Zod.

Convenciones:

• Cada tool debe usar un esquema Zod (z.object({...})) para validar su input.
• Los handlers deben envolver ctx.client.call(...) en try/catch y usar ok(...)/fail(...) de tool-base.ts.
• Tools mutaciones destructivas deben declarar destructive: true y verificar confirm: true con assertConfirmed(...) o equivalente en su handler.

Licencia

MIT