analyze-coverage-mcp

Servidor MCP que conecta relatórios de cobertura LCOV a agentes de IA.

Documentação

analyze-coverage-mcp

Servidor MCP que conecta relatórios de cobertura LCOV a agentes de IA. Ele roda localmente e dá aos agentes visibilidade precisa e estruturada sobre a cobertura de testes — quais linhas foram executadas, quais ramificações não foram cobertas e onde concentrar os esforços de teste.

O que é LCOV?

LCOV é um formato de texto padrão para dados de cobertura de código. Ele registra quais linhas, funções e ramificações foram executadas durante os testes. O formato é amplamente suportado por executores de teste (Vitest, Jest, Istanbul, etc.) e normalmente é gravado em lcov.info. Cada registro descreve a cobertura de um arquivo de origem: execuções de linhas, execuções de ramificações e execuções de funções.

Ferramentas

Ferramenta	Descrição
`get_coverage_overview`	Estatísticas de cobertura agregadas e por arquivo (linhas, funções, ramificações %). Suporta filtragem por prefixo de diretório, limite e ordem de classificação.
`list_uncovered_regions`	Linhas não cobertas (mescladas em intervalos) e ramificações não cobertas para um arquivo específico.
`get_annotated_source`	Arquivo de origem completo anotado linha por linha com `[COVERED]`, `[NOT COV]` ou `[NO DATA]`. Suporta janelamento `start_line`/`end_line`.

O servidor também monitora lcov.info em busca de alterações (verificando a cada 1 s) e recarrega automaticamente — para que a cobertura permaneça atualizada enquanto os testes rodam em modo de observação.

Requisitos

Todas as ferramentas MCP (get_coverage_overview, list_uncovered_regions, get_annotated_source) exigem estes parâmetros em cada chamada. Eles identificam qual relatório de cobertura carregar e como resolver os caminhos dos arquivos de origem.

Parâmetro	Requisito
`lcov_path`	Deve ser um caminho absoluto. O arquivo deve existir no disco.
`project_root`	Deve ser um caminho absoluto. Em projetos únicos, use o diretório onde os testes rodam (mesmo que a raiz do pacote abaixo). Em monorepos, você pode usar a raiz do repositório — o MCP deriva a raiz do pacote a partir de `lcov_path`.

Estrutura de projeto esperada

O diretório onde os testes rodam (a raiz do pacote) deve ter esta estrutura:

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

src/ e coverage/ devem ser irmãos sob a raiz do pacote. Em projetos únicos, passe esse diretório como project_root. Em monorepos, project_root pode ser a raiz do repositório; o MCP infere a raiz do pacote a partir da localização de lcov_path.

Se sua estrutura for diferente, use source_root ou additional_roots (veja Resolução de caminhos e localizações de arquivos).

Instalação

A partir do npm

Configurar MCP

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

A partir do código-fonte

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"
    }
  }
}

Desenvolvimento

# 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

Como funciona

O agente chama get_coverage_overview com lcov_path e project_root para carregar o relatório.
O arquivo LCOV é analisado em memória em um Map<filename, FileCoverage> e armazenado em cache.
Chamadas subsequentes de ferramentas reutilizam o cache (identificado por lcov_path + project_root) ou acionam um recarregamento via refresh_coverage.
Os caminhos de origem são resolvidos com alternativas: project_root + caminho, remoção de prefixo comum (src/, lib/, etc.), e quando o lcov está em coverage/, o diretório pai é usado para monorepos. Veja Resolução de caminhos e localizações de arquivos.

Gerando relatórios LCOV

O servidor MCP lê arquivos lcov.info. Veja como gerá-los com executores de teste comuns:

Vitest

Instale o provedor 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',
    },
  },
})

Execute os testes com cobertura:

pnpm vitest run --coverage

Saída: ./coverage/lcov.info

Jest

Instale o Istanbul (usado pelo Jest para cobertura):

pnpm add -D jest @types/jest

Configure jest.config.js ou package.json:

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

Execute os testes com cobertura:

pnpm jest --coverage

Saída: ./coverage/lcov.info

Istanbul / nyc

pnpm add -D nyc

Configure package.json:

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

Execute os testes com cobertura:

pnpm nyc pnpm test

Saída: ./coverage/lcov.info (ou .nyc_output/lcov.info dependendo da configuração)

Outros executores

A maioria dos executores suporta LCOV via plugins ou opções integradas. Garanta que o reporter produza lcov e que o caminho para lcov.info seja passado como lcov_path para as ferramentas MCP.

Entradas

Todas as ferramentas exigem:

Campo	Tipo	Descrição
`lcov_path`	`string`	Caminho absoluto para o arquivo `lcov.info` gerado pelo seu conjunto de testes
`project_root`	`string`	Caminho absoluto para a raiz do projeto sendo analisado

Valores típicos de lcov_path:

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

Resolução de caminhos e localizações de arquivos

Veja Requisitos para requisitos de parâmetros e estrutura.

Como os caminhos funcionam no LCOV

Os registros LCOV armazenam caminhos de arquivos de origem relativos ao pacote que executou os testes. Por exemplo, se os testes rodam a partir de apps/app-api, os caminhos parecem src/core/auth/service.ts, não apps/app-api/src/core/auth/service.ts.

Monorepos

Em monorepos, project_root geralmente é a raiz do repositório (ex.: /repo), mas os caminhos LCOV são relativos à raiz do pacote (ex.: apps/app-api). O MCP lida com isso automaticamente:

Quando lcov_path está dentro de um diretório coverage/ (ex.: apps/app-api/coverage/lcov.info), o pai desse diretório é usado como raiz de origem alternativa.
Então project_root pode ser a raiz do monorepo; arquivos de origem sob apps/app-api/src/ ainda são resolvidos corretamente.

Exemplo: lcov_path: /repo/apps/app-api/coverage/lcov.info com project_root: /repo → origens resolvidas sob /repo/apps/app-api/.

Ordem de resolução de caminhos de origem

Para get_annotated_source, o MCP resolve caminhos LCOV para caminhos do sistema de arquivos nesta ordem:

Caminho absoluto — se o caminho LCOV já for absoluto.
source_root + caminho — quando source_root é fornecido (parâmetro opcional).
project_root + caminho — ex.: project_root/src/foo.ts.
Prefixos removidos — se o caminho contém src/, lib/, dist/ ou app/, tenta project_root + o caminho a partir desse segmento em diante.
additional_roots — para cada raiz neste array opcional, tenta root + path.
Derivado da localização do lcov — quando o lcov está em coverage/, tenta o diretório pai de coverage/ como raiz.

Substituições flexíveis (`get_annotated_source`)

Quando as heurísticas automáticas falham, use estes parâmetros opcionais:

Parâmetro	Descrição
`source_root`	Substitui a raiz para resolver arquivos de origem. Tentado antes de `project_root`. Use quando você souber a raiz do pacote (ex.: `apps/app-api`).
`additional_roots`	Array de raízes extras para tentar. Para cada uma, `resolve(root, file_path)` é tentado. Útil quando as origens vivem em múltiplos diretórios.

Exemplo: get_annotated_source com source_root: "/repo/apps/app-api" força a resolução sob esse diretório, ignorando project_root para essa chamada.

Correspondência de `file_path`

Para list_uncovered_regions e get_annotated_source, file_path pode ser:

O caminho exato como aparece no relatório LCOV (ex.: src/core/auth/service.ts).
Um sufixo que identifica exclusivamente o arquivo (ex.: auth/service.ts ou service.ts).
Um nome de arquivo se for único no relatório (ex.: service.ts).

Use get_coverage_overview para listar caminhos disponíveis quando estiver em dúvida.

Restrições e armadilhas

O arquivo de origem deve existir no disco para get_annotated_source. Essa ferramenta lê a origem para anotá-la. Se a resolução falhar: "Source file not found on disk. Try setting project_root, source_root, or additional_roots to the directory containing your source files." list_uncovered_regions usa apenas dados de cobertura e não exige o arquivo de origem.
Use source_root ou additional_roots quando as heurísticas falharem. Quando a detecção automática de monorepo falhar, passe source_root com a raiz do pacote (ex.: apps/app-api), ou use additional_roots para adicionar caminhos de busca extras.
Os caminhos diferenciam maiúsculas de minúsculas na maioria dos sistemas.

Licença

MIT

analyze-coverage-mcp

Documentação