# 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）を取得。

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

### validate_config

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

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

### get_bottlenecks

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

```json
{ "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` 未設定を意味する。

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

### get_dag

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

```json
{ "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>
```

### ビルド

```bash
npm install
npm run build
```

### Claude Desktop / Claude Code への登録

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

### デバッグ

```bash
npm run inspector
```

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

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