mcp-reportia

# mcp-reportia

[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.javalenciacai%2Fmcp--reportia-blue?logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io)
[![skills.sh](https://img.shields.io/badge/skills.sh-javalenciacai%2Fmcp--reportia-7c3aed?logo=lightning)](https://skills.sh/javalenciacai/mcp-reportia)
[![npm](https://img.shields.io/npm/v/@james.valencia/mcp-reportia?logo=npm)](https://www.npmjs.com/package/@james.valencia/mcp-reportia)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

Servidor **[MCP](https://modelcontextprotocol.io/)** (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](#dónde-está-indexado)
- [Instalación y uso rápido](#instalación-y-uso-rápido)
- [Variables de entorno](#variables-de-entorno)
- [Configuración en clientes MCP](#configuración-en-clientes-mcp)
- [Flujo de release](#flujo-de-release)
- [Herramientas disponibles](#herramientas-disponibles)
- [Limitaciones conocidas](#limitaciones-conocidas)
- [Seguridad](#seguridad)
- [Rutas cubiertas y omitidas](#rutas-cubiertas-y-omitidas)
- [Desarrollo local](#desarrollo-local)
- [Pruebas](#pruebas)
- [Inspección con MCP Inspector](#inspección-con-mcp-inspector)
- [Arquitectura interna](#arquitectura-interna)
- [Licencia](#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`](./server.json) |
| **npm registry** | [`@james.valencia/mcp-reportia`](https://www.npmjs.com/package/@james.valencia/mcp-reportia) | npm package |
| **skills.sh** (Agent Skills Directory) | [`javalenciacai/mcp-reportia`](https://skills.sh/javalenciacai/mcp-reportia) | [`skills/reportia-mcp-usage/SKILL.md`](./skills/reportia-mcp-usage/SKILL.md) |

Instalación via skills.sh:
```bash
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`:
```bash
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

```bash
# 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):

```bash
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`:

```bash
# 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_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 dos alternativas de auth debe estar presente:

- `REPORTIA_TOKEN` Bearer, o
- `REPORTIA_EMAIL` + `REPORTIA_PASSWORD` sesión cookie.

Si no, `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`:

```jsonc
{
  "mcpServers": {
    "reportia": {
      "command": "npx",
      "args": ["-y", "mcp-reportia"],
      "env": {
        "R