analyze-coverage-mcp

MCP server that bridges LCOV coverage reports to AI agents. It runs locally and gives agents precise, structured visibility into test coverage — which lines are hit, which branches are missed, and where to focus testing efforts.

What is LCOV?

LCOV is a standard text format for code coverage data. It records which lines, functions, and branches were executed during tests. The format is widely supported by test runners (Vitest, Jest, Istanbul, etc.) and is typically written to `lcov.info`. Each record describes coverage for a source file: line hits, branch hits, and function hits.

Tools

The server also watches `lcov.info` for changes (polling every 1 s) and auto-reloads — so coverage stays current while tests run in watch mode.

Requirements

All MCP tools (`get_coverage_overview`, `list_uncovered_regions`, `get_annotated_source`) require these parameters in every call. They identify which coverage report to load and how to resolve source file paths.

Expected project structure

The directory where tests run (the package root) must have this layout:

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

`src/` and `coverage/` must be siblings under the package root. In single projects, pass that directory as `project_root`. In monorepos, `project_root` can be the repo root; the MCP infers the package root from the `lcov_path` location.

If your structure differs, use `source_root` or `additional_roots` (see Path resolution and file locations).

Installation

From npm

Configure MCP

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

From source

Build and install

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

Configure MCP

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

Development

# 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

How it works

1. The agent calls `get_coverage_overview` with `lcov_path` and `project_root` to load the report.

2. The LCOV file is parsed in-memory into a `Map` and cached.

3. Subsequent tool calls reuse the cache (identified by `lcov_path` + `project_root`) or trigger a reload via `refresh_coverage`.

4. Source paths are resolved with fallbacks: `project_root` + path, common prefix stripping (`src/`, `lib/`, etc.), and when lcov is in `coverage/`, the parent directory is used for monorepos. See Path resolution and file locations.

Generating LCOV reports

The MCP server reads `lcov.info` files. Here’s how to generate them with common test runners:

Vitest

Install the coverage provider:

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

Run tests with coverage:

pnpm vitest run --coverage

Output: `./coverage/lcov.info`

Jest

Install Istanbul (used by Jest for coverage):

pnpm add -D jest @types/jest

Configure `jest.config.js` or `package.json`:

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

Run tests with coverage:

pnpm jest --coverage

Output: `./coverage/lcov.info`

Istanbul / nyc

pnpm add -D nyc

Configure `package.json`:

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

Run tests with coverage:

pnpm nyc pnpm test

Output: `./coverage/lcov.info` (or `.nyc_output/lcov.info` depending on config)

Other runners

Most runners support LCOV via plugins or built-in options. Ensure the reporter outputs `lcov` and that the path to `lcov.info` is passed as `lcov_path` to the MCP tools.

Inputs

All tools require:

Typical `lcov_path` values:

• Vitest with `@vitest/coverage-v8`: `/coverage/lcov.info`
• Jest with `--coverage`: `/coverage/lcov.info`
• Istanbul/nyc: `/.nyc_output/lcov.info`

Path resolution and file locations

See Requirements for parameter and structure requirements.

How paths work in LCOV

LCOV records store source file paths relative to the package that ran the tests. For example, if tests run from `apps/app-api`, paths look like `src/core/auth/service.ts`, not `apps/app-api/src/core/auth/service.ts`.

Monorepos

In monorepos, `project_root` is often the repo root (e.g. `/repo`), but LCOV paths are relative to the package root (e.g. `apps/app-api`). The MCP handles this automatically:

• When `lcov_path` is inside a `coverage/` directory (e.g. `apps/app-api/coverage/lcov.info`), the parent of that directory is used as a fallback source root.
• So `project_root` can be the monorepo root; source files under `apps/app-api/src/` are still resolved correctly.

Example: `lcov_path: /repo/apps/app-api/coverage/lcov.info` with `project_root: /repo` → sources resolve under `/repo/apps/app-api/`.

Source path resolution order

For `get_annotated_source`, the MCP resolves LCOV paths to filesystem paths in this order:

1. Absolute path — if the LCOV path is already absolute.

2. `source_root` + path — when `source_root` is provided (optional param).

3. `project_root` + path — e.g. `project_root/src/foo.ts`.

4. Stripped prefixes — if the path contains `src/`, `lib/`, `dist/`, or `app/`, tries `project_root` + the path from that segment onward.

5. `additional_roots` — for each root in this optional array, tries `root + path`.

6. Derived from lcov location — when lcov is in `coverage/`, tries the parent directory of `coverage/` as root.

Flexible overrides (`get_annotated_source`)

When the automatic heuristics fail, use these optional parameters:

Example: `get_annotated_source` with `source_root: "/repo/apps/app-api"` forces resolution under that directory, ignoring `project_root` for that call.

`file_path` matching

For `list_uncovered_regions` and `get_annotated_source`, `file_path` can be:

• The exact path as it appears in the LCOV report (e.g. `src/core/auth/service.ts`).
• A suffix that uniquely identifies the file (e.g. `auth/service.ts` or `service.ts`).
• A filename if it is unique across the report (e.g. `service.ts`).

Use `get_coverage_overview` to list available paths when unsure.

Restrictions and pitfalls

• Source file must exist on disk for `get_annotated_source`. That tool reads the source to annotate it. If resolution fails: *"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` only uses coverage data and does not require the source file.
• Use `source_root` or `additional_roots` when heuristics fail. When the automatic monorepo detection fails, pass `source_root` with the package root (e.g. `apps/app-api`), or use `additional_roots` to add extra search paths.
• Paths are case-sensitive on most systems.

License

MIT