エージェント統合 (MCP)

dowse はコーディングエージェントを第一の消費者として設計されています。人間向けの表やレポートより先に、MCP サーバとプラグインが用意されています。

なぜエージェント優先なのか

CodeScene が設計された時代の前提は「テックリードがダッシュボードを見る」でした。いまは Claude Code のようなエージェントがリファクタ対象を決めて実行します。

エージェントは「このファイルは複雑です」という警告を必要としません。必要なのは根拠のある優先順位です。dowse はそれを構造化データで返します。

Claude Code に繋ぐ

claude mcp add dowse -- npx -y dowse mcp

これだけです。以降、セッション内で自然に聞けます。

このリポジトリで次に直すべきところは？

packages/ui を変更するけど、影響範囲は？

この 500 行のファイル、リファクタする価値ある？

公開している tool

tool	用途
dowse_findings	複数指標が重なった「まず見るべき場所」。起点はここ
dowse_hotspots	hotspot 上位。件数とパッケージで絞り込み可能
dowse_hidden_coupling	依存関係がないのに同時変更されるパッケージ対
dowse_explain_coupling	なぜ一緒に変わるのか（ファイルの組・代表コミット）
dowse_verify_churn	その変更頻度が本物か（AST 比較）
dowse_package_risk	パッケージの hotspot / health / bus factor
dowse_health_breakdown	Code Health の減点内訳（関数名・行番号付き）
dowse_file_metrics	ファイル単位のメトリクス内訳
dowse_refresh	解析キャッシュを破棄して再解析

詳細は MCP リファレンス を参照してください。

応答に必ず添えられるもの

すべての tool は結果に解析条件を添えて返します。

{
  "note": {
    "complexityProxy": "loc",
    "git": {
      "since": "12 months ago",
      "commitCount": 3920,
      "excluded": { "merges": 6, "bots": 0, "formatOnly": 1 },
      "shallowClone": false
    },
    "formulas": "hotspot = rank(change_frequency) × rank(complexity)"
  }
}

エージェントが「255 回変更されています」とだけ報告するのではなく、「直近 12 か月で 255 回（merge と bot を除外済み）」と正確に伝えられるようにするためです。

プラグインとして入れる

MCP 設定と skill をまとめた plugin/ を同梱しています。skill には解釈のガイドラインが書かれており、エージェントが次のような判断をできるようになります。

• 複雑でも score 0 のファイルは提案しない（触られていないので ROI がない）
• hidden coupling は必ず dowse_explain_coupling で裏を取る（重複コードなのか設計上の規約なのかは中身次第）
• churn は額面どおりに受け取らない（effectiveRatio が低ければリネームで水増しされている）
• health は必ず内訳とともに示す（「health 4.9」だけでは行動できない）
• bus factor は人ではなくリスクとして表現する（個人の評価に使わない）

手動で設定する

.mcp.json に直接書く場合:

{
  "mcpServers": {
    "dowse": {
      "command": "npx",
      "args": ["-y", "dowse", "mcp"]
    }
  }
}

解析対象ディレクトリや期間を指定することもできます。

{
  "mcpServers": {
    "dowse": {
      "command": "npx",
      "args": ["-y", "dowse", "mcp", "./packages", "--since", "6 months ago"]
    }
  }
}

初回の解析コスト

MCP サーバは最初の tool 呼び出し時に解析を実行し、以降はキャッシュします。2,000 ファイル規模で 7 秒程度です。大きく変更した後は dowse_refresh で再解析させてください。