编码代理集成 (MCP)

dowse 的设计把编码代理当作首要使用者。MCP 服务器与插件是先做的，面向人的表格与报告在后。

为什么代理优先

CodeScene 设计时的前提是「技术负责人看仪表盘」。今天，是 Claude Code 这样的代理在决定重构什么，并且动手去做。

代理不需要一条「这个文件很复杂」的告警。它需要的是有依据的优先级顺序。dowse 正是以结构化数据返回这个。

接入 Claude Code

claude mcp add dowse -- npx -y dowse mcp

配置到此为止。之后就可以在会话中直接问：

这个仓库接下来该重构哪里？

我要改 packages/ui，会影响到什么？

这个 500 行的文件值得重构吗？

它暴露的工具

工具	用途
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 参考。

每个响应都会带上什么

每个工具都会附上本次分析所处的条件。

{
  "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 次，已排除合并与 bot 提交」。

作为插件安装

plugin/ 目录把 MCP 配置与一个 skill 打包在一起。skill 里写了解读准则，因此代理会知道：

• 不要推荐分数为 0 的文件，无论它多复杂——没人碰它，修了没有回报
• 隐藏耦合一定要用 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 服务器在第一次工具调用时执行分析，之后缓存。2,000 个文件规模约需 7 秒。大改之后请用 dowse_refresh 让它重新分析。