Coding agents (MCP)

dowse is designed with coding agents as its primary consumer. The MCP server and plugin came before the human-facing tables and reports, not after.

Why agents first

When CodeScene was designed, the assumption was that a tech lead reads a dashboard. Today an agent like Claude Code decides what to refactor and then does it.

An agent does not need a warning that says "this file is complex". It needs a justified priority order. dowse returns exactly that, as structured data.

Connect it to Claude Code

claude mcp add dowse -- npx -y dowse mcp

That is the whole setup. From then on you can just ask, inside a session:

Where should I refactor next in this repo?

I'm about to change packages/ui — what does that touch?

Is this 500-line file worth refactoring?

The tools it exposes

Tool	What it is for
dowse_findings	Places where several indicators overlap. Start here.
dowse_hotspots	Top hotspots, filterable by count and package
dowse_hidden_coupling	Package pairs that change together with no dependency
dowse_explain_coupling	Why they change together — file pairs and representative commits
dowse_verify_churn	Whether that change frequency is real (AST comparison)
dowse_package_risk	Hotspot / health / bus factor for a package
dowse_health_breakdown	Code Health deductions, with function names and line numbers
dowse_file_metrics	Per-file metric breakdown
dowse_refresh	Drop the cache and re-analyse

See the MCP reference for details.

What every response carries

Each tool attaches the conditions the analysis ran under.

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

This exists so that an agent does not report "it was changed 255 times" but "255 times in the last 12 months, excluding merges and bots".

Install it as a plugin

A plugin/ directory bundles the MCP configuration together with a skill. The skill carries interpretation guidance, so an agent knows to:

• Not propose a file whose score is 0, however complex it is — nobody touches it, so there is no return
• Always confirm hidden coupling with dowse_explain_coupling — duplicated code and a deliberate protocol look identical in the numbers
• Not take churn at face value — a low effectiveRatio means renames inflated it
• Always present health with its breakdown — "health 4.9" alone is not actionable
• Frame bus factor as risk, not as a judgement of a person

Configure it by hand

Writing .mcp.json directly:

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

You can also pin the directory and the time window.

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

The cost of the first analysis

The MCP server analyses on the first tool call and caches from then on — around 7 seconds at 2,000 files. After a large change, have it re-analyse with dowse_refresh.