advanced-circleci MCP Server

CircleCI config review に特化した MCP サーバー。 既存の circleci-mcp-server が持たない Insights（性能・クレジット） と 実 config 取得 を中心に、config review に必要な5次元のデータを束ねたツールを提供する。

ツール一覧

ツール	問い	内部 API
get_config	何をレビューするか（実 config の取得）	GET /pipeline/{id}/config
validate_config	変更案は妥当か（compile & validate）	POST /compile-config-with-defaults
get_bottlenecks	どこが遅い・高い（job 別 p95・クレジット集中）	Insights: workflows + jobs
get_workflow_health	workflow の健全性（duration/flaky/test metrics）	Insights: summary + test-metrics + flaky-tests
get_dag	依存関係と実 resource_class（DAG 分析）	Pipeline/Workflow/Job + job detail

get_config

最新 pipeline の config（source YAML と orb 展開後の compiled YAML）を取得。

{ "project_slug": "gh/org/repo" }
{ "pipeline_id": "uuid", "branch": "main" }

validate_config

任意の YAML を CircleCI に送って検証・展開。変更案を提案する前に必ず通す。

{ "config_yaml": "version: 2.1\n...", "owner_id": "org-uuid" }

get_bottlenecks

全 workflow × 全 job の Insights を取得し、クレジット消費順にソートして返す。

{ "project_slug": "gh/org/repo", "reporting_window": "last-30-days" }
{ "project_slug": "gh/org/repo", "reporting_window": "last-7-days", "all_branches": true }

get_workflow_health

workflow サマリ＋テストメトリクス（slowest/most-failed）＋flaky test を束ねて返す。 total_test_runs: 0 の場合は store_test_results 未設定を意味する。

{ "project_slug": "gh/org/repo", "workflow_name": "build-and-test" }

get_dag

pipeline または workflow の job 依存グラフ（requires/dependencies）と実 resource_class を返す。

{ "pipeline_id": "uuid" }
{ "pipeline_id": "uuid", "include_resource_class": false }
{ "workflow_id": "uuid" }

設計方針（既存 MCP との住み分け）

次元	既存 circleci-mcp-server	このサーバー
A Config	config_helper（validate/推奨）	get_config（実 config 取得）・validate_config
B Discovery	get_latest_pipeline_status など	get_dag（resource_class 取得を補完）
C Insights（性能）	なし	get_bottlenecks・get_workflow_health（主目的）
D テスト健全性	find_flaky_tests・get_job_test_results	get_workflow_health（集約 test-metrics を補完）
E Usage（コスト）	download_usage_api_data + find_underused_resource_classes（完備）	実装しない

セットアップ

必要環境変数

CIRCLE_TOKEN=<Personal Access Token>

ビルド

npm install
npm run build

Claude Desktop / Claude Code への登録

{
  "mcpServers": {
    "advanced-circleci": {
      "command": "/path/to/advanced-circleci/build/index.js",
      "env": { "CIRCLE_TOKEN": "your-token" }
    }
  }
}

デバッグ

npm run inspector

Insights の制約（ツールレスポンスにも注記あり）

• 集計ウィンドウ: 最大90日。既定はデフォルトブランチのみ（all_branches: true で全ブランチ）。
• on-hold / tag トリガーの実行は集計対象外。
• データは日次更新。直近24時間は反映されないことがある。
• クレジットは概算。正確な課金額は Plan Overview で確認。
• job 別メトリクスは必ず workflow 名が要る（プロジェクト横断の一括 job エンドポイントは存在しない）。