MCP tools

dowse mcp [dir]

stdio で MCP サーバを起動します。導入方法は エージェント統合 を参照してください。

すべての tool は結果に解析条件（期間・除外件数・shallow かどうか・使用した式）を note として添えて返します。

---

dowse_findings

複数の指標が重なった「まず見るべき場所」を優先度順に返します。エージェントの起点はここです。

{ top?: number }   // 既定 10

{
  "findings": [
    {
      "kind": "hotspot-file",
      "target": "services/api/src/runtime.ts",
      "severity": 0.999,
      "summary": "頻繁に変更され複雑（255 commits, 857 LoC）",
      "evidence": { "score": 0.999, "commits": 255, "loc": 857, "authors": 3 }
    }
  ]
}

kind は hotspot-file / hidden-coupling / hotspot-package / bus-factor / unhealthy-package / unused-dependency。

---

dowse_hotspots

hotspot 上位を返します。

{ top?: number, package?: string }   // 既定 10

score が 0 のファイル（＝変更されていないファイル）は含まれません。

---

dowse_hidden_coupling

依存関係がないのに繰り返し同時に変更されているパッケージ対を返します。

{ top?: number, includeObvious?: boolean }   // 既定 20 / false

{
  "coupling": [
    {
      "packages": ["@acme/admin-web", "@acme/customer-web"],
      "kind": "hidden",
      "degree": 0.33,
      "sharedCommits": 91,
      "revisions": [228, 328],
      "dependencyDirection": null
    }
  ]
}

---

dowse_explain_coupling

2 つの対象がなぜ一緒に変わるのかを説明します。dowse_hidden_coupling で見つけたペアの裏取りに使います。

{ a: string, b: string, topFiles?: number, topCommits?: number }

実際に共変更しているファイルの組、関与ファイル、代表コミットが返るので、結合の実体（コピーされたコードなのか、設計上の規約なのか）を判別できます。

---

dowse_verify_churn

指定ファイルの変更頻度が「本物」かを AST 比較で検証します。

{ files: string[], maxRevisions?: number }   // 最大 20 ファイル / 既定 40 リビジョン

{
  "verifications": [
    {
      "path": "src/foo.ts",
      "rawCommits": 20,
      "effectiveCommits": 15,
      "effectiveRatio": 0.75,
      "breakdown": {
        "changed": 14,
        "rename-only": 0,
        "format-only": 5,
        "identical": 0,
        "unknown": 0
      }
    }
  ]
}

effectiveRatio が 0.8 を下回るなら、その変更頻度はリネームや整形で水増しされています。

---

dowse_package_risk

パッケージの hotspot / Code Health / bus factor をまとめて返します。あるパッケージを触る前や、担当者の異動を検討するときに使います。

{ package?: string, top?: number }   // 省略時は全パッケージをリスク順

---

dowse_health_breakdown

Code Health が何点引かれているかを smell 単位で完全に分解して返します。

{
  file: string;
}

{
  "health": {
    "score": 4.9,
    "smells": [
      {
        "kind": "high-cognitive-complexity",
        "penalty": 3.0,
        "value": 50,
        "threshold": 15,
        "severity": 1.0,
        "locations": ["validateConfig (cognitive=50, L3)"],
        "explanation": "ネストや制御フローの入り組みが理解コストを直接押し上げる"
      }
    ],
    "locBaselineScore": 10.0,
    "baselineDelta": -5.1
  },
  "thresholds": {
    "cyclomatic": 10,
    "cognitive": 15,
    "fileLoc": 400,
    "arguments": 4
  },
  "weights": { "high-cognitive-complexity": 3, "complex-method": 2.5 }
}

locBaselineScore との差が小さいなら、その health は実質ファイル長の言い換えです。

---

dowse_file_metrics

ファイル単位のメトリクス内訳（LoC / cyclomatic / cognitive / churn / hotspot スコアの構成要素）を返します。

{
  file: string;
}

見つからない場合は部分一致の候補を didYouMean で返します。

---

dowse_refresh

解析キャッシュを破棄し、次回のクエリで再解析させます。大きな変更を加えた後に使います。

{
}