analyze-coverage-mcp

Servidor MCP que conecta informes de cobertura LCOV con agentes de IA.

Documentación

analyze-coverage-mcp

Servidor MCP que conecta informes de cobertura LCOV con agentes de IA. Se ejecuta localmente y brinda a los agentes una visibilidad precisa y estructurada de la cobertura de pruebas: qué líneas están cubiertas, qué ramas no se ejecutaron y dónde enfocar los esfuerzos de prueba.

¿Qué es LCOV?

LCOV es un formato de texto estándar para datos de cobertura de código. Registra qué líneas, funciones y ramas se ejecutaron durante las pruebas. El formato es ampliamente compatible con ejecutores de pruebas (Vitest, Jest, Istanbul, etc.) y normalmente se escribe en lcov.info. Cada registro describe la cobertura de un archivo fuente: aciertos de líneas, aciertos de ramas y aciertos de funciones.

Herramientas

Herramienta	Descripción
`get_coverage_overview`	Estadísticas de cobertura agregadas y por archivo (líneas, funciones, ramas %). Admite filtrado por prefijo de directorio, umbral y orden de clasificación.
`list_uncovered_regions`	Líneas no cubiertas (fusionadas en rangos) y ramas no cubiertas para un archivo específico.
`get_annotated_source`	Archivo fuente completo anotado línea por línea con `[COVERED]`, `[NOT COV]` o `[NO DATA]`. Admite ventanas de `start_line`/`end_line`.

El servidor también observa lcov.info para detectar cambios (sondeo cada 1 s) y se recarga automáticamente, de modo que la cobertura se mantenga actualizada mientras las pruebas se ejecutan en modo de observación.

Requisitos

Todas las herramientas MCP (get_coverage_overview, list_uncovered_regions, get_annotated_source) requieren estos parámetros en cada llamada. Identifican qué informe de cobertura cargar y cómo resolver las rutas de los archivos fuente.

Parámetro	Requisito
`lcov_path`	Debe ser una ruta absoluta. El archivo debe existir en el disco.
`project_root`	Debe ser una ruta absoluta. En proyectos individuales, use el directorio donde se ejecutan las pruebas (igual que la raíz del paquete a continuación). En monorepos, puede usar la raíz del repositorio: el MCP deriva la raíz del paquete desde `lcov_path`.

Estructura esperada del proyecto

El directorio donde se ejecutan las pruebas (la raíz del paquete) debe tener esta estructura:

<package_root>/          ← same as project_root in single projects; in monorepos, parent of coverage/ (e.g. apps/app-api)
├── coverage/
│   └── lcov.info
└── src/
    └── ...

src/ y coverage/ deben ser hermanos bajo la raíz del paquete. En proyectos individuales, pase ese directorio como project_root. En monorepos, project_root puede ser la raíz del repositorio; el MCP infiere la raíz del paquete desde la ubicación de lcov_path.

Si su estructura difiere, use source_root o additional_roots (consulte Resolución de rutas y ubicaciones de archivos).

Instalación

Desde npm

Configurar MCP

{
  "mcpServers": {
    "analyze-coverage": {
      "command": "npx",
      "args": [
        "-y",
        "@sofia-open-source/analyze-coverage-mcp"
      ]
    }
  }
}

Desde el código fuente

Compilar e instalar

pnpm bundle # generates js bundle in ./analyze-coverage-mcp with shebang node executable
chmod +x ./analyze-coverage-mcp # make it executable
cp ./analyze-coverage-mcp ~/.local/bin/analyze-coverage-mcp # available in $PATH

Configurar MCP

{
  "mcpServers": {
    "analyze-coverage": {
      "command": "analyze-coverage-mcp"
    }
  }
}

Desarrollo

# Install dependencies
pnpm install

# Run in watch mode (no build needed)
pnpm dev

# Type-check and build
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

Cómo funciona

El agente llama a get_coverage_overview con lcov_path y project_root para cargar el informe.
El archivo LCOV se analiza en memoria en un Map<filename, FileCoverage> y se almacena en caché.
Las llamadas posteriores a las herramientas reutilizan la caché (identificada por lcov_path + project_root) o activan una recarga mediante refresh_coverage.
Las rutas de los archivos fuente se resuelven con alternativas: project_root + ruta, eliminación de prefijos comunes (src/, lib/, etc.), y cuando lcov está en coverage/, se usa el directorio padre para monorepos. Consulte Resolución de rutas y ubicaciones de archivos.

Generación de informes LCOV

El servidor MCP lee archivos lcov.info. Así es como generarlos con ejecutores de pruebas comunes:

Vitest

Instale el proveedor de cobertura:

pnpm add -D @vitest/coverage-v8

Configure vitest.config.ts:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
      reportsDirectory: './coverage',
    },
  },
})

Ejecute las pruebas con cobertura:

pnpm vitest run --coverage

Salida: ./coverage/lcov.info

Jest

Instale Istanbul (usado por Jest para cobertura):

pnpm add -D jest @types/jest

Configure jest.config.js o package.json:

{
  "jest": {
    "collectCoverage": true,
    "coverageReporters": ["text", "lcov"],
    "coverageDirectory": "coverage"
  }
}

Ejecute las pruebas con cobertura:

pnpm jest --coverage

Salida: ./coverage/lcov.info

Istanbul / nyc

pnpm add -D nyc

Configure package.json:

{
  "nyc": {
    "reporter": ["text", "lcov"],
    "report-dir": "coverage"
  }
}

Ejecute las pruebas con cobertura:

pnpm nyc pnpm test

Salida: ./coverage/lcov.info (o .nyc_output/lcov.info según la configuración)

Otros ejecutores

La mayoría de los ejecutores admiten LCOV mediante complementos u opciones integradas. Asegúrese de que el reportero genere lcov y que la ruta a lcov.info se pase como lcov_path a las herramientas MCP.

Entradas

Todas las herramientas requieren:

Campo	Tipo	Descripción
`lcov_path`	`string`	Ruta absoluta al archivo `lcov.info` generado por su suite de pruebas
`project_root`	`string`	Ruta absoluta a la raíz del proyecto que se está analizando

Valores típicos de lcov_path:

Vitest con @vitest/coverage-v8: <project>/coverage/lcov.info
Jest con --coverage: <project>/coverage/lcov.info
Istanbul/nyc: <project>/.nyc_output/lcov.info

Resolución de rutas y ubicaciones de archivos

Consulte Requisitos para conocer los requisitos de parámetros y estructura.

Cómo funcionan las rutas en LCOV

Los registros LCOV almacenan rutas de archivos fuente relativas al paquete que ejecutó las pruebas. Por ejemplo, si las pruebas se ejecutan desde apps/app-api, las rutas se ven como src/core/auth/service.ts, no como apps/app-api/src/core/auth/service.ts.

Monorepos

En monorepos, project_root suele ser la raíz del repositorio (p. ej., /repo), pero las rutas LCOV son relativas a la raíz del paquete (p. ej., apps/app-api). El MCP maneja esto automáticamente:

Cuando lcov_path está dentro de un directorio coverage/ (p. ej., apps/app-api/coverage/lcov.info), el padre de ese directorio se usa como raíz fuente alternativa.
Por lo tanto, project_root puede ser la raíz del monorepo; los archivos fuente bajo apps/app-api/src/ aún se resuelven correctamente.

Ejemplo: lcov_path: /repo/apps/app-api/coverage/lcov.info con project_root: /repo → las fuentes se resuelven bajo /repo/apps/app-api/.

Orden de resolución de rutas fuente

Para get_annotated_source, el MCP resuelve las rutas LCOV a rutas del sistema de archivos en este orden:

Ruta absoluta — si la ruta LCOV ya es absoluta.
source_root + ruta — cuando se proporciona source_root (parámetro opcional).
project_root + ruta — p. ej., project_root/src/foo.ts.
Prefijos eliminados — si la ruta contiene src/, lib/, dist/ o app/, intenta project_root + la ruta desde ese segmento en adelante.
additional_roots — para cada raíz en esta matriz opcional, intenta root + path.
Derivado de la ubicación de lcov — cuando lcov está en coverage/, intenta el directorio padre de coverage/ como raíz.

Anulaciones flexibles (`get_annotated_source`)

Cuando las heurísticas automáticas fallan, use estos parámetros opcionales:

Parámetro	Descripción
`source_root`	Anula la raíz para resolver archivos fuente. Se intenta antes de `project_root`. Úselo cuando conozca la raíz del paquete (p. ej., `apps/app-api`).
`additional_roots`	Matriz de raíces adicionales para intentar. Para cada una, se intenta `resolve(root, file_path)`. Útil cuando las fuentes viven en múltiples directorios.

Ejemplo: get_annotated_source con source_root: "/repo/apps/app-api" fuerza la resolución bajo ese directorio, ignorando project_root para esa llamada.

Coincidencia de `file_path`

Para list_uncovered_regions y get_annotated_source, file_path puede ser:

La ruta exacta tal como aparece en el informe LCOV (p. ej., src/core/auth/service.ts).
Un sufijo que identifique de manera única el archivo (p. ej., auth/service.ts o service.ts).
Un nombre de archivo si es único en todo el informe (p. ej., service.ts).

Use get_coverage_overview para listar las rutas disponibles cuando no esté seguro.

Restricciones y dificultades

El archivo fuente debe existir en el disco para get_annotated_source. Esa herramienta lee el fuente para anotarlo. Si la resolución falla: "Archivo fuente no encontrado en el disco. Intente establecer project_root, source_root o additional_roots en el directorio que contiene sus archivos fuente." list_uncovered_regions solo usa datos de cobertura y no requiere el archivo fuente.
Use source_root o additional_roots cuando las heurísticas fallen. Cuando la detección automática de monorepos falla, pase source_root con la raíz del paquete (p. ej., apps/app-api), o use additional_roots para agregar rutas de búsqueda adicionales.
Las rutas distinguen entre mayúsculas y minúsculas en la mayoría de los sistemas.

Licencia

MIT

analyze-coverage-mcp

Documentación