MCP 工具

dowse mcp [dir]

以 stdio 启动 MCP 服务器。配置方式见编码代理集成。

每个工具都会把本次分析所处的条件——时间窗口、排除计数、是否浅克隆，以及所用公式——作为 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

分数为 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

解释两个对象为什么一起改动。用它来核实 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 分数按坏味道逐项拆解的完整明细。

{
  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、圈复杂度、认知复杂度、churn，以及 hotspot 分数的构成。

{
  file: string;
}

找不到文件时，会以 didYouMean 返回相近的候选。

---

dowse_refresh

丢弃分析缓存，使下一次查询重新分析。大改之后使用。

{
}