JinDaGe - mcp-server-codecov MCP Details

article

README

🚀 Codecov的MCP服务器

这是一个模型上下文协议（MCP）服务器，提供了查询Codecov覆盖率数据的工具。它支持codecov.io和自托管的Codecov实例，并且可以配置URL端点。

📦 已发布到npm：mcp-server-codecov

🚀 快速开始

在2分钟内即可开始使用：

1. 获取Codecov API令牌

从你的Codecov账户创建一个API令牌（不是上传令牌）：

访问 codecov.io（或你的自托管URL）
点击你的头像 → 设置 → 访问选项卡
点击“生成令牌”并将其命名为“MCP服务器API访问”
复制令牌值

2. 设置环境变量

将以下内容添加到你的shell配置文件（~/.zshrc 或 ~/.bashrc）中：

export CODECOV_TOKEN="your-api-token-here"

然后重新加载配置文件：source ~/.zshrc

3. 安装MCP服务器

claude mcp add --transport stdio codecov \
  --env CODECOV_BASE_URL=https://codecov.io \
  --env CODECOV_TOKEN=${CODECOV_TOKEN} \
  -- npx -y mcp-server-codecov

4. 验证安装

claude mcp get codecov

预期输出：codecov: mcp-server-codecov - ✓ 已连接

就是这么简单！ 现在你可以在Claude Code中使用Codecov工具了。请参阅下面的可用工具。

✨ 主要特性

文件级覆盖率：获取特定文件的详细逐行覆盖率数据
提交覆盖率：检索单个提交的覆盖率统计信息
仓库覆盖率：获取仓库的整体覆盖率指标
可配置URL：可以指向任何Codecov实例（codecov.io或自托管）
令牌认证：支持使用API令牌访问覆盖率数据

令牌类型

⚠️ 重要提示

Codecov有两种不同类型的令牌：

上传令牌：用于在CI/CD期间将覆盖率报告推送到Codecov。可在你的仓库设置 → 常规页面找到。

API令牌：用于通过API从Codecov读取覆盖率数据。在你的Codecov设置 → 访问选项卡中创建。

此MCP服务器需要 API令牌，而不是上传令牌。

💻 使用示例

可用工具

get_file_coverage

获取特定文件的逐行覆盖率数据。

参数：

owner（必需）：仓库所有者（用户名或组织）
repo（必需）：仓库名称
file_path（必需）：仓库内文件的路径（例如，'src/index.ts'）
ref（可选）：Git引用（分支、标签或提交SHA）

示例：

获取owner/repo仓库中main分支上src/index.ts文件的覆盖率

get_commit_coverage

获取特定提交的覆盖率数据。

参数：

owner（必需）：仓库所有者
repo（必需）：仓库名称
commit_sha（必需）：提交SHA

示例：

获取owner/repo仓库中提交abc123的覆盖率

get_repo_coverage

获取仓库的整体覆盖率统计信息。

参数：

owner（必需）：仓库所有者
repo（必需）：仓库名称
branch（可选）：分支名称（默认为仓库的默认分支）

示例：

获取owner/repo仓库中main分支的整体覆盖率

📚 详细文档

验证与故障排除

常见问题

401未授权错误

检查令牌类型：确保你使用的是 API令牌（从设置 → 访问选项卡获取），而不是上传令牌
验证令牌是否有效并有权限访问该仓库
对于自托管实例，确认你使用的是正确的 CODECOV_BASE_URL

环境变量未展开

确保变量已在你的shell中导出（检查 ~/.zshrc 或 ~/.bashrc）
设置环境变量后重启Claude Code
验证变量是否存在：echo $CODECOV_TOKEN

连接失败

重启Claude Code或Claude Desktop
验证环境变量是否正确设置：echo $CODECOV_TOKEN
检查配置：claude mcp get codecov

HTTP与HTTPS

始终使用 https:// 作为 CODECOV_BASE_URL，而不是 http://：

正确：https://your-codecov-instance.com
错误：http://your-codecov-instance.com

高级配置

自托管Codecov

对于自托管的Codecov实例，使用你的实例URL：

claude mcp add --transport stdio codecov \
  --env CODECOV_BASE_URL=https://codecov.your-company.com \
  --env CODECOV_TOKEN=${CODECOV_TOKEN} \
  -- npx -y mcp-server-codecov

Claude Desktop设置

将以下内容添加到你的Claude Desktop配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "mcp-server-codecov"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.io",
        "CODECOV_TOKEN": "your-codecov-token-here"
      }
    }
  }
}

手动配置（Claude Code）

将以下内容添加到 ~/.claude.json 中：

{
  "mcpServers": {
    "codecov": {
      "command": "npx",
      "args": ["-y", "mcp-server-codecov"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.io",
        "CODECOV_TOKEN": "${CODECOV_TOKEN}"
      }
    }
  }
}

注意：

支持使用 ${VAR} 语法展开环境变量
像 ${CODECOV_TOKEN} 这样的变量将从你的shell环境中读取
npx的 -y 标志会自动接受包安装提示

从npm全局安装

npm install -g mcp-server-codecov

优点：

简单的单命令安装
使用 npm update -g mcp-server-codecov 自动更新
无需手动构建步骤
适用于所有项目

验证安装：

npm list -g mcp-server-codecov
which mcp-server-codecov
npm view mcp-server-codecov version

开发安装（从源代码）

仅在你为项目做贡献时使用此方法：

git clone https://github.com/egulatee/mcp-server-codecov.git
cd mcp-server-codecov
npm install
npm run build

然后使用构建后的路径进行配置：

Claude Code CLI：

claude mcp add --transport stdio codecov \
  --env CODECOV_BASE_URL=https://codecov.io \
  --env CODECOV_TOKEN=${CODECOV_TOKEN} \
  -- node /absolute/path/to/codecov-mcp/dist/index.js

手动配置（~/.claude.json）：

{
  "mcpServers": {
    "codecov": {
      "command": "node",
      "args": ["/absolute/path/to/codecov-mcp/dist/index.js"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.io",
        "CODECOV_TOKEN": "${CODECOV_TOKEN}"
      }
    }
  }
}

Claude Desktop：

{
  "mcpServers": {
    "codecov": {
      "command": "node",
      "args": ["/path/to/mcp-server-codecov/dist/index.js"],
      "env": {
        "CODECOV_BASE_URL": "https://codecov.io",
        "CODECOV_TOKEN": "your-codecov-token-here"
      }
    }
  }
}

测试

本项目使用Vitest进行全面的单元测试，保持了97%以上的代码覆盖率。

有关详细的测试文档，包括如何运行测试、覆盖率要求、CI集成和编写测试，请参阅 TESTING.md。

开发

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式下的监听模式
npm run watch

发布流程

本项目通过GitHub Actions使用自动化发布工作流。当你推送版本标签时，会自动将版本发布到npm。

有关详细的发布说明，包括先决条件、创建版本、手动发布和版本编号，请参阅 RELEASE.md。

API兼容性

此服务器使用Codecov的API v2。API端点遵循以下模式：

文件覆盖率：/api/v2/gh/{owner}/repos/{repo}/file_report/{file_path}
提交覆盖率：/api/v2/gh/{owner}/repos/{repo}/commits/{commit_sha}
仓库覆盖率：/api/v2/gh/{owner}/repos/{repo}

目前支持GitHub仓库（gh）。通过修改API路径，可以添加对其他提供商（GitLab、Bitbucket）的支持。

📄 许可证

本项目采用MIT许可证。

mcp-server-codecov