Test Coverage MCP

🚀 测试覆盖率MCP

让你的代码编写代理在编码时具备覆盖率感知能力

本项目的 MCP 服务器可以为任何编程语言（基于 LCOV）提供即时、可靠且节省令牌的测试覆盖率数据，解决了 AI 编码代理在缺乏适当覆盖率工具时面临的问题。

🚀 于 2025 年 11 月刚刚发布！这些天我一直在精心打磨这个库。如果你觉得它有价值，给个 ⭐ 星标可以让其他开发者知道这个项目值得关注。

🚀 快速开始

当 AI 编码代理在没有适当覆盖率工具的情况下处理代码时，会面临三个关键问题，而本 MCP 服务器提供了解决方案。你可以通过简单的工具调用检查覆盖率、获取覆盖率摘要，并进行会话进度的基线跟踪。

✨ 主要特性

• 覆盖率感知：代理可以随时通过简单的工具调用检查覆盖率。
• 节省令牌：用少于 100 个令牌获取覆盖率摘要，而非数千个。
• 准确性：采用生产级的 LCOV 解析，处理所有格式变体。
• 基线跟踪：在会话中测量覆盖率进度，无需在内存中保存状态。

📦 安装指南

npm install -g test-coverage-mcp

💻 使用示例

基础用法

1. 查询覆盖率摘要

询问项目的整体覆盖率或特定文件的覆盖率：

// 获取项目整体覆盖率
coverage_summary({ lcovPath: "./coverage/lcov.info" });
// 返回: { linesCoveragePercentage: 87.5, branchesCoveragePercentage: 82.1 }

// 获取特定文件的覆盖率
coverage_file_summary({
  lcovPath: "./coverage/lcov.info",
  filePath: "src/utils/parser.ts",
});
// 返回: { path: "src/utils/parser.ts", linesCoveragePercentage: 92.0, branchesCoveragePercentage: 88.5 }

2. 会话进度的基线跟踪

在会话开始时建立基线，然后测量进度：

// 会话开始时 - 将当前覆盖率记录为基线
start_recording({ lcovPath: "./coverage/lcov.info" });
// 返回: "Recording started"

// ... 代理编写代码和测试 ...

// 检查覆盖率影响
get_diff_since_start({ lcovPath: "./coverage/lcov.info" });
// 返回: { linesPercentageImpact: +2.3, branchesPercentageImpact: +1.8 }

高级用法

示例 1：开始工作前检查覆盖率

代理: "在开始工作前，让我检查一下当前的测试覆盖率"
[使用 coverage_summary 工具]
代理: "当前的覆盖率是 87.5% 的行覆盖率和 82.1% 的分支覆盖率。我会努力保持或提高这个水平。"

示例 2：开发过程中跟踪覆盖率影响

代理: "我先记录基线覆盖率"
[使用 start_recording 工具]

代理: "现在我将添加新的身份验证功能并编写测试"
[编写代码和测试]

代理: "让我检查一下覆盖率的影响"
[使用 get_diff_since_start 工具]
代理: "太棒了！行覆盖率提高了 2.3%，分支覆盖率提高了 1.8%。"

示例 3：验证特定文件的覆盖率

代理: "让我检查一下我刚刚修改的文件的覆盖率"
[使用 coverage_file_summary 工具，filePath: "src/auth/validator.ts"]
代理: "validator.ts 文件现在的行覆盖率为 95%，分支覆盖率为 92%。"

📚 详细文档

可用工具

coverage_summary

从 LCOV 文件中获取项目的整体覆盖率。 输入：

{
  lcovPath?: string  // 可选。默认为 "./coverage/lcov.info"
}

输出：

{
  linesCoveragePercentage: number,      // 0 - 100
  branchesCoveragePercentage: number    // 0 - 100
}

示例：

coverage_summary({ lcovPath: "./coverage/lcov.info" });
// { linesCoveragePercentage: 87.5, branchesCoveragePercentage: 82.1 }

coverage_file_summary

获取特定文件的覆盖率。 输入：

{
  lcovPath?: string,  // 可选。默认为 "./coverage/lcov.info"
  filePath: string    // 必需。文件路径
}

输出：

{
  path: string,
  linesCoveragePercentage: number,      // 0 - 100
  branchesCoveragePercentage: number    // 0 - 100
}

示例：

coverage_file_summary({
  lcovPath: "./coverage/lcov.info",
  filePath: "src/utils/parser.ts",
});
// { path: "src/utils/parser.ts", linesCoveragePercentage: 92.0, branchesCoveragePercentage: 88.5 }

start_recording

将当前覆盖率记录为基线，以便后续比较。 输入：

{
  lcovPath: string; // 必需。要记录的 LCOV 文件的路径
}

输出：

"Recording started";

示例：

start_recording({ lcovPath: "./coverage/lcov.info" });
// "Recording started"

get_diff_since_start

将当前覆盖率与记录的基线进行比较。 输入：

{
  lcovPath: string; // 必需。当前 LCOV 文件的路径
}

输出：

{
  linesPercentageImpact: number,      // 正数 = 改进，负数 = 下降
  branchesPercentageImpact: number    // 正数 = 改进，负数 = 下降
}

示例：

get_diff_since_start({ lcovPath: "./coverage/lcov.info" });
// { linesPercentageImpact: +2.3, branchesPercentageImpact: +1.8 }

配置

将此 MCP 服务器添加到你的 AI 编码工具的配置中：

Claude Desktop (Claude Code)

macOS：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json Windows：编辑 %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "test-coverage": {
      "command": "npx",
      "args": ["-y", "test-coverage-mcp"]
    }
  }
}

更新后，重启 Claude Desktop。

Cursor IDE

在项目根目录下创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "test-coverage": {
      "command": "npx",
      "args": ["-y", "test-coverage-mcp"]
    }
  }
}

GitHub Copilot (VS Code)

在工作区中创建或编辑 .vscode/mcp.json：

{
  "servers": {
    "test-coverage": {
      "command": "npx",
      "args": ["-y", "test-coverage-mcp"]
    }
  }
}

需要 VS Code 1.99+ 或 Visual Studio 17.14+。企业用户需要启用 "MCP servers in Copilot" 策略。

Windsurf (Codeium IDE)

macOS：编辑 ~/.codeium/windsurf/mcp_config.json Windows：编辑 %APPDATA%\Codeium\Windsurf\mcp_config.json Linux：编辑 ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "test-coverage": {
      "command": "npx",
      "args": ["-y", "test-coverage-mcp"]
    }
  }
}

或者使用图形界面：设置 → 高级设置 → 级联 → 添加服务器

🔧 技术细节

工作原理

本 MCP 服务器：

1. 解析 LCOV 文件：使用生产级解析器处理所有 LCOV 格式变体。
2. 计算覆盖率：计算项目整体或单个文件的覆盖率百分比。
3. 存储基线：在临时目录中存储基线，用于基于会话的跟踪。
4. 返回紧凑 JSON：返回占用最少令牌的紧凑 JSON 响应。

LCOV 格式支持

本服务器支持所有标准 LCOV 文件格式，包括：

• 包含摘要部分的文件（SF:，end_of_record）
• 仅包含逐行数据的文件（DA: 条目）
• 包含分支覆盖率数据的文件（BRDA:，BRF:，BRH:）
• 同一文件中的混合格式

📄 许可证

MIT © Yoni Goldberg

🔗 链接

• GitHub 仓库
• npm 包
• MCP 文档
• 报告问题

💡 改进建议

• coverage_file_summary 返回的嵌套属性也以扁平形式声明。
• 开始记录会覆盖其他会话文件。
• 改进记录命名 - setSessionBaseline，getDiffSinceBaseline。

⚠️ 故障排除

"LCOV 文件未找到"

• 确保你已启用覆盖率运行测试套件。
• 检查你的 LCOV 文件路径是否正确（相对路径从当前工作目录解析）。
• 默认路径是 ./coverage/lcov.info。

"未找到文件的覆盖率数据"

• 验证文件路径与 LCOV 文件中显示的路径完全匹配。
• 一些测试框架使用绝对路径，而其他框架使用相对路径。

"未找到基线记录"

• 必须在调用 get_diff_since_start 之前调用 start_recording。
• 基线存储在临时存储中，系统重启时会清除。

🛠️ 开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试（包含覆盖率！）
npm test

# 运行代码检查器
npm run lint

# 使用 MCP 检查器进行测试
npm run inspect

🤝 贡献

欢迎贡献！请随时提交拉取请求。