covdbg

covdbg-mcp

适用于 covdbg 的 MCP 服务：面向 AI Agent 的 Windows C++ 代码覆盖率工具。运行测试、找出未覆盖的代码，并添加针对性测试。无需重新构建。

covdbg 使用已构建的 Windows 二进制文件中的 PDB 调试信息测量覆盖率，支持 x64、ARM64 和 32 位 x86。它的工作方式类似调试器：启动可执行文件、读取 PDB，并在程序运行时放置轻量级探针。从 v1.3.0 开始，MCP 服务已内置于 covdbg 可执行文件中，并通过 covdbg mcp 启动。

此仓库包含 covdbg 的 MCP 注册表元数据（server.json、glama.json）以及 MCP Bundle 清单（manifest.json）。服务本身随 covdbg 一同发布。

Agent 可以做什么

1. 运行覆盖率测试，无需重新构建测试可执行文件。
2. 根据未覆盖行数对文件排序。
3. 读取未覆盖的代码及其周边上下文。
4. 添加针对性测试、重新运行，并确认覆盖缺口已补齐。
5. 使用只读 SQL 查询覆盖率数据库（.covdb），并将其合并，也可跨检出目录和构建进行合并。

要求

• Windows x64，或 Windows on ARM（ARM64）
• covdbg 1.3.0 或更高版本。本文档介绍 covdbg 1.5.0。
• 带有 PDB 调试符号的可执行文件（MSVC 或任何可生成 PDB 的工具链）。x64 covdbg 可测量 x64 和 32 位 x86 程序；ARM64 covdbg 可测量 ARM64 程序（covdbg 1.5 及更高版本）。
• 一次性运行 covdbg login（covdbg 1.4 及更高版本会登录一个团队，且运行时需要该团队的席位），或在 CI 中使用 COVDBG_PROJECT_TOKEN。GitHub Actions 中的公开仓库两者都不需要（covdbg 1.5 及更高版本，参见CI 中的许可）。
• 在目标可执行文件旁放置 .covdbg.yaml，或在调用 run 时传入 config_path（参见配置参考）

安装 covdbg

• 安装程序（推荐）： installer.msi，Windows on ARM 请使用 installer-arm64.msi。程序会安装到 %LocalAppData%\Programs\Liasoft\covdbg，并将该目录添加到用户的 PATH 中。
• 便携版： portable.zip，Windows on ARM 请使用 portable-arm64.zip。将其解压到任意位置，并自行将该目录添加到 PATH 中。请将 Agent DLL 放在 covdbg.exe 旁边：covdbg 只会在该目录中查找它们。

没有单独的 32 位 covdbg。x64 版本附带 libcovdbg32.dll（其 Agent 的 32 位构建版本），并使用同一个 covdbg.exe 测量 32 位程序。

然后打开新的终端并登录：

covdbg --version
covdbg login

登录按团队区分：在浏览器中选择一个团队（个人团队，或你拥有或持有席位的团队），Agent 的运行将由该团队授权。使用 covdbg login --team <slug> 预先选择团队，并使用 covdbg whoami 查看当前启用的团队。

CI 中的许可

在 CI 中，将 COVDBG_PROJECT_TOKEN 设置在服务的环境中；运行将由该令牌所属的团队授权。

GitHub Actions 中的公开仓库无需项目令牌（covdbg 1.5 及更高版本）。为作业授予 permissions: id-token: write：如果既没有 COVDBG_PROJECT_TOKEN，也没有已保存的登录信息，covdbg 会使用 GitHub 签发给作业的令牌，其中包含其运行所在的仓库信息。GitHub 不会向来自复刻仓库的拉取请求签发此类令牌。私有仓库仍需要项目令牌；如果已设置项目令牌，则优先使用该令牌。

客户端配置

该服务使用 stdio 传输方式。请从项目目录启动，或传入 --workspace <dir>。

选项	环境变量	默认值	用途
--workspace <dir>		工作目录	项目目录；也是 discover 的默认根目录
--query-timeout <ms>	COVDBG_MCP_QUERY_TIMEOUT_MS	5000	单条 query 语句的最长运行时间，范围为 1 到 600000 ms（covdbg 1.5 及更高版本）。指定选项时优先于环境变量。

Claude Code

在项目目录中：

claude mcp add covdbg -- covdbg mcp

或者添加项目级 .mcp.json：

{
  "mcpServers": {
    "covdbg": {
      "command": "covdbg",
      "args": ["mcp"]
    }
  }
}

VS Code

.vscode/mcp.json：

{
  "servers": {
    "covdbg": {
      "type": "stdio",
      "command": "covdbg",
      "args": ["mcp", "--workspace", "${workspaceFolder}"]
    }
  }
}

Cursor

.cursor/mcp.json：

{
  "mcpServers": {
    "covdbg": {
      "command": "covdbg",
      "args": ["mcp"]
    }
  }
}

Claude Desktop（MCP Bundle）

1. 从最新版本下载 covdbg.mcpb。
2. 使用 Claude Desktop 打开它，或将它拖到 Settings → Extensions。
3. 设置以下内容：
   • covdbg 可执行文件：covdbg.exe 的路径。默认路径为 MSI 安装位置。
   • **工作区：**项目目录。
   • **项目令牌：**可选。如果已运行 covdbg login，请留空；运行将使用你登录的团队许可证（参见 covdbg whoami）。

此 Bundle 不包含 covdbg 本身。它会启动已安装的 covdbg.exe，因此无需重新安装 Bundle 即可应用 covdbg 更新。

工具

工具	用途	主要输入
guide	工作流和配置指南。首次运行前请调用。	可选的 topic（workflow、config、excludes、baseline、merging、uncovered、children、libraries）
discover	查找可执行文件和覆盖率数据库	可选的 root
run	启动覆盖率运行；立即返回运行会话	target；可选的 target_arguments、config_path、output_path、follow_children
wait_run	短暂等待或收集已完成的结果	session_id；可选的 timeout_seconds
cancel_run	终止运行	session_id
open_coverage	以只读方式打开现有数据库	path
files	根据未覆盖行数对文件排序	session_id；可选的 limit、max_coverage_percent
code	读取包含上下文的未覆盖源代码片段	session_id、file_path
query	在时间限制内运行一条只读 SQL 语句	session_id、sql；可选的 max_rows
merge	合并数据库，也支持来自不同检出版本和构建的数据库	input_paths、output_path
close	释放运行或覆盖率会话	session_id

限制和行为

• 运行会话 ID 以 run- 开头；覆盖率会话 ID 以 covdb- 开头。
• 最多可同时有 8 个运行任务，以及 32 个打开的覆盖率会话。运行任务在其 covdbg 进程存活期间计入；wait_run 确认任务已结束后，该任务不再占用名额。
• wait_run 最多阻塞 30 秒。如果返回 stillRunning，请再次调用。
• 运行结果包括 success、no_functions_to_track、license_failure 或 error。
• covdbg 的退出代码不包含目标程序的退出代码，因此请另行检查测试结果。
• follow_children 用于测量目标程序启动的进程。自身没有调试信息的启动器（例如 ctest.exe 或 cmd.exe）不会被测量，covdbg 会测量其子进程。因此，使用目标 ctest.exe、target_arguments --test-dir build 和 follow_children 调用 run，即可测量 CTest 运行的测试二进制文件。一个二进制文件的所有进程都会将其命中记录写入同一个数据库（covdbg 1.5 及更高版本）。
• query 会在时间限制到达时停止仍在运行的语句（除非 --query-timeout 另有指定，默认是 5000 ms），并返回错误；会话仍保持打开状态。它还会限制语句的大小：SQL 最多 100 KiB，表达式嵌套深度最多 250，一条复合语句中最多 100 个 SELECT，LIKE/GLOB 模式最多 1000 字节，且任一字符串或 blob 最大为 16 MiB（covdbg 1.5 及更高版本）。
• merge 会根据每次运行的 source_root 的相对路径，匹配不同检出目录中记录的源文件；并会将同一模块路径下的不同构建（例如某项测试的 x64 和 ARM64 构建）并列保留（covdbg 1.5 及更高版本）。remappedModules 和 remappedFiles 表示以这种方式匹配的数量。
• covdbg 1.5.0 会写入架构为 8 的覆盖率数据库，并拒绝由更早版本写入的 .covdb 文件。请重新记录覆盖率。

服务器运行期间升级

从 covdbg 1.5.0 开始，即使客户端仍保持 covdbg mcp 打开，安装程序也可以升级或卸载 covdbg，无需重启。正在运行的服务器会继续使用旧版本响应，而它启动的运行任务则会使用新安装的 covdbg.exe。重新连接服务器即可获取新版服务器：在 Claude Code 中，选择 /mcp → covdbg → Reconnect。

环境变量

变量	用途
COVDBG_PROJECT_TOKEN	用于 CI 或无头模式的项目令牌。本地使用依赖 covdbg login，且绑定到一个团队。
COVDBG_OUTPUT	固定的默认输出位置。请避免在一个测试套件的多个运行任务间重复使用同一位置，因为后续运行会覆盖先前的结果。
COVDBG_MCP_QUERY_TIMEOUT_MS	单条 query 语句的时间限制，范围为 1 到 600000 ms（默认 5000）。超出此范围的值会被忽略。两者同时指定时，以 --query-timeout 为准。

文档

• MCP 服务
• AI 快速入门
• CLI 命令参考
• 数据与遥测

发布（维护者）

确保 manifest.json 和 server.json 中的 version，以及 server.json 软件包 URL 中的发布标签保持同步。

1. 构建软件包。.mcpbignore 会将其限制为 manifest.json、icon.png 和 LICENSE：

   npx @anthropic-ai/mcpb validate manifest.json
   npx @anthropic-ai/mcpb pack . covdbg.mcpb
   

2. 创建 GitHub 发布版本 v<version>，并将 covdbg.mcpb 上传为资源。

3. 将软件包的哈希值填入 server.json 中的 fileSha256：

   (Get-FileHash covdbg.mcpb -Algorithm SHA256).Hash.ToLower()
   

4. 发布到 MCP 注册表。com.covdbg/* 命名空间使用 covdbg.com 上的 DNS 身份验证：

   mcp-publisher login dns --domain covdbg.com --private-key <key>
   mcp-publisher publish
   

5. Glama 会从代码仓库获取 glama.json。

许可证

此代码仓库中的元数据依据 Apache License 2.0 授权。covdbg 本身采用单独的许可证，提供 Free、Team 和 Enterprise 计划。请参阅 covdbg.com 和许可常见问题。