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).