MCP Server Codecov

🚀 Codecov的MCP服務器

這是一個模型上下文協議（MCP）服務器，提供了查詢Codecov覆蓋率數據的工具。它支持codecov.io和自託管的Codecov實例，並且可以配置URL端點。

📦 已發佈到npm：mcp-server-codecov

🚀 快速開始

在2分鐘內即可開始使用：

1. 獲取Codecov API令牌

從你的Codecov賬戶創建一個API令牌（不是上傳令牌）：

1. 訪問 codecov.io（或你的自託管URL）
2. 點擊你的頭像 → 設置 → 訪問選項卡
3. 點擊“生成令牌”並將其命名為“MCP服務器API訪問”
4. 複製令牌值

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許可證。