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:

Plataforma	URL	Formato
MCP Registry oficial (modelcontextprotocol.io)	io.github.javalenciacai/mcp-reportia	server.json
npm registry	@james.valencia/mcp-reportia	npm package
skills.sh (Agent Skills Directory)	javalenciacai/mcp-reportia	skills/reportia-mcp-usage/SKILL.md

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

Plataforma	Requisito	Estado
npm Trusted Publishing	Configurar publisher en /package/@james.valencia/mcp-reportia/settings con javalenciacai/mcp-reportia + publish.yml	Tu turno
Workflow Node 24	Subir a Node 24 (lo hago yo tras tu confirmación)	Pendiente
MCP Registry	Ninguno — usa github-oidc que firma el workflow automáticamente	Listo
skills.sh	Ninguno — scraping automático	Listo
GitHub Release	Permiso contents: write ya configurado en el workflow	Listo

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

Variable	Obligatoria	Descripción
REPORTIA_BASE_URL	Sí	URL raíz de la API de Reportia, sin barra final (p.ej. https://reportia.example.com).
REPORTIA_TOKEN	Condicional*	Token Bearer. Alternativa al login por sesión.
REPORTIA_COOKIE	Condicional*	Cookie de sesión Reportia pre-emitida (p.ej. connect.sid=s%3A...). Para callers que ya tienen la sesión del usuario resuelta y quieren que el child autentique como ese usuario sin re-login.
REPORTIA_EMAIL	Condicional*	Email para login por sesión (cookie).
REPORTIA_PASSWORD	Condicional*	Contraseña para login por sesión (cookie).
REPORTIA_COMPANY_ID	No	companyId por defecto cuando la tool lo admita. Acepta entero positivo.
REPORTIA_TIMEOUT_MS	No (def. 30000)	Timeout por petición HTTP en ms.
REPORTIA_DOWNLOAD_DIR	No (def. ./downloads)	Carpeta donde se guardan los binarios descargados (Excel/PDF exportados).
REPORTIA_USER_AGENT	No (def. mcp-reportia/0.1.0)	Cabecera User-Agent en cada request.

* 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:

Dominio	Módulo	Cantidad
Salud y autenticación	src/tools/auth-health.ts	3
Empresas	src/tools/companies.ts	5
Movimientos contables	src/tools/accounting-movements.ts	4
Mapeo de cuentas	src/tools/account-mappings.ts	5
Reportes de comisiones	src/tools/commission-reports.ts	2
Terceros	src/tools/third-parties.ts	4
Vendedor × factura	src/tools/salesperson-invoice.ts	11
Línea × centro de costo	src/tools/line-cost-center.ts	22
Operaciones (uploads, colas, SIIGO)	src/tools/operations.ts	10
Total		66

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

Tool	Descripción
reportia_health	Diagnóstico del cliente MCP + ping a GET /api/health.
reportia_whoami	Perfil del usuario autenticado (GET /api/auth/me).
reportia_logout	Cierra la sesión contra Reportia (POST /api/auth/logout).

Empresas (src/tools/companies.ts)

Tool	Tipo	Descripción
reportia_companies_list	Listado	Lista empresas accesibles (GET /api/companies).
reportia_company_get	Detalle	Detalle de una empresa (GET /api/companies/:id).
reportia_company_settings_get	Configuración	Settings de empresa (GET /api/companies/:id/settings).
reportia_company_settings_update	Mutación	Patch de settings (PATCH /api/companies/:id/settings).
reportia_company_activate ⚠️	Destructiva	Activa empresa (POST /api/companies/:id/activate). Requiere confirm:true.

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

Tool	Tipo	Descripción
reportia_movements_list	Listado	Lista movimientos con filtros y paginación.
reportia_movements_export_excel	Descarga binaria	Exporta movimientos a Excel y devuelve ruta local.
reportia_movements_export_pdf	Descarga binaria	Exporta movimientos a PDF y devuelve ruta local.
reportia_movements_delete_all ⚠️	Destructiva	Elimina todos los movimientos de la empresa. Requiere confirm:true.

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

Tool	Tipo	Descripción
reportia_account_mappings_list	Listado	Lista mapeos contables (GET /api/companies/:companyId/account-mappings).
reportia_account_mapping_create	Mutación	Crea un mapeo (POST /api/account-mappings).
reportia_account_mapping_update	Mutación	Actualiza un mapeo (PATCH /api/account-mappings/:mappingId).
reportia_account_mapping_delete ⚠️	Destructiva	Elimina un mapeo (DELETE /api/account-mappings/:mappingId). Requiere confirm:true.
reportia_account_codes_search	Búsqueda	Busca códigos contables para autocompletar (GET /api/companies/:companyId/account-codes/search).

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

Tool	Tipo	Descripción
reportia_commission_list	Listado	Lista cálculos de comisión (GET /api/commission-reports).
reportia_commission_export_excel	Descarga binaria	Exporta reporte de comisiones a Excel.

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

Tool	Tipo	Descripción
reportia_third_parties_list	Listado	Lista terceros (clientes/proveedores).
reportia_third_parties_search	Búsqueda	Búsqueda avanzada de terceros.
reportia_third_parties_get_by_nit	Detalle	Obtiene un tercero por NIT.
reportia_third_parties_portfolio_balance	Resumen	Balance de cartera por tercero.

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

Tool	Tipo	Descripción
reportia_salesperson_mappings_list	Listado	Lista mapeos vendedor × factura de una empresa.
reportia_salesperson_mapping_create	Mutación	Crea un mapeo vendedor × factura.
reportia_salesperson_mapping_update	Mutación	Actualiza un mapeo vendedor × factura.
reportia_salesperson_mapping_delete ⚠️	Destructiva	Elimina un mapeo vendedor × factura. Requiere confirm:true.
reportia_salesperson_options_list	Listado	Lista opciones de vendedor para selección / autocompletar.
reportia_invoices_list	Listado	Lista facturas con filtros.
reportia_invoice_settings_get	Configuración	Lee la configuración de factura de una empresa.
reportia_invoice_settings_create	Mutación	Crea la configuración de factura.
reportia_invoice_settings_update	Mutación	Actualiza la configuración de factura.
reportia_invoice_email_send	Notificación	Envía una factura por email (servidor Reportia dispara el envío).
reportia_invoices_send_multiple	Notificación	Envía varias facturas por email en una sola llamada.

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