MCP tools

dowse mcp [dir]

Starts the MCP server over stdio. See Coding agents for setup.

Every tool attaches the analysis conditions — time window, exclusion counts, whether the clone was shallow, and the formulas used — as a note on the result.

---

dowse_findings

Returns the places where several indicators overlap, in priority order. This is where an agent should start.

{ top?: number }   // default 10

{
  "findings": [
    {
      "kind": "hotspot-file",
      "target": "services/api/src/runtime.ts",
      "severity": 0.999,
      "summary": "changed often and complex (255 commits, 857 LoC)",
      "evidence": { "score": 0.999, "commits": 255, "loc": 857, "authors": 3 }
    }
  ]
}

kind is one of hotspot-file, hidden-coupling, hotspot-package, bus-factor, unhealthy-package, unused-dependency.

---

dowse_hotspots

Returns the top hotspots.

{ top?: number, package?: string }   // default 10

Files with a score of 0 — meaning they were never changed — are not included.

---

dowse_hidden_coupling

Returns package pairs that are repeatedly changed together despite having no dependency between them.

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

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

---

dowse_explain_coupling

Explains why two targets change together. Use it to confirm what a pair from dowse_hidden_coupling actually is.

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

It returns the file pairs that actually co-change, the files involved, and representative commits — enough to tell duplicated code apart from a deliberate protocol.

---

dowse_verify_churn

Verifies by AST comparison whether a file's change frequency is real.

{ files: string[], maxRevisions?: number }   // up to 20 files / 40 revisions

{
  "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
      }
    }
  ]
}

An effectiveRatio below 0.8 means that change frequency is inflated by renames or reformatting.

---

dowse_package_risk

Returns hotspot, Code Health, and bus factor for a package together. Useful before touching a package, or when weighing a team change.

{ package?: string, top?: number }   // omit the name to get all packages by risk

---

dowse_health_breakdown

Returns the full smell-by-smell breakdown of a Code Health score.

{
  file: string;
}

{
  "health": {
    "score": 4.9,
    "smells": [
      {
        "kind": "high-cognitive-complexity",
        "penalty": 3.0,
        "value": 50,
        "threshold": 15,
        "severity": 1.0,
        "locations": ["validateEnvironmentConfig (cognitive=50, L3)"],
        "explanation": "nesting and tangled control flow directly raise the cost of understanding"
      }
    ],
    "locBaselineScore": 10.0,
    "baselineDelta": -5.1
  },
  "thresholds": {
    "cyclomatic": 10,
    "cognitive": 15,
    "fileLoc": 400,
    "arguments": 4
  },
  "weights": { "high-cognitive-complexity": 3, "complex-method": 2.5 }
}

If the gap to locBaselineScore is small, that health score is file length in disguise.

---

dowse_file_metrics

Returns the metric breakdown for one file — LoC, cyclomatic, cognitive, churn, and the components of the hotspot score.

{
  file: string;
}

If the file is not found, near matches are returned as didYouMean.

---

dowse_refresh

Drops the analysis cache so the next query re-analyses. Use it after a large change.

{
}