codehealth-mcp

Code Health MCP (CodeScene)

面向 AI 辅助编码的结构性可维护性反馈。它补充 style/lint 技能（coding-standards、plankton-code-quality），提供设计层面的健康分数和回归门控。

上游： codescene-oss/codescene-mcp-server
包： @codescene/codehealth-mcp（通过 npx stdio）

安全和边界

Opt-in（ECC）： mcp-configs/mcp-servers.json 中的 codescene 块只是模板。ECC 插件安装不会自动启用捆绑 MCP servers。只有你需要时，才把该条目复制到配置中。ECC install/sync 时可用 ECC_DISABLED_MCPS=codescene,... 排除它。

凭据： 不捆绑 token。自行设置 CS_ACCESS_TOKEN（见上游 repo 的 getting-a-personal-access-token.md）。不要把 tokens 提交到仓库。

工具读取什么： 调用时，工具会分析你指向的本地仓库中的文件和 git 状态（你传入的路径，以及 analyze_change_set 使用的 branch context）。它们不会自行运行。standalone mode 请遵循上游隐私文档：codescene-mcp-server README 和 CodeScene policies。不要把此技能用于 secrets、credentials 或你不想被分析的路径。

如果 MCP 不可用（离线、token 错误、server 崩溃）： 不要编造 Code Health 分数。告诉用户检查已跳过。只有用户明确批准后才继续。MCP 挂掉时，优先用 lint/tests/verification-loop 做门控。server 连接后再恢复检查。

何时使用

• 用户要求审查代码质量、重构文件，或检查 AI 变更是否降低可维护性
• 编辑 hotspot、legacy module 或陌生文件前
• commit 或 pull request 前需要可维护性保护
• 大型 agent-written diff 之后——验证 Code Health 没有回退
• 与 verification-loop、tdd-workflow 或 /quality-gate 搭配作为结构性检查（不是 tests/lint 的替代品）

何时激活

同上方 何时使用——这是 ECC 用于 skill auto-activation 的标题。

工作方式

1. 连接 MCP server

把 mcp-configs/mcp-servers.json 中的 codescene 条目复制到你的 harness MCP 配置。

Claude Code（~/.claude.json → mcpServers）：

"codescene": {
  "command": "npx",
  "args": ["-y", "@codescene/codehealth-mcp"],
  "env": {
    "CS_ACCESS_TOKEN": "YOUR_CS_ACCESS_TOKEN_HERE"
  }
}

项目级： 把同一块合并到 repo 根目录的 .mcp.json。

Token 设置见上游 repo（上方链接）。下面列出的四个工具在 standalone mode 下不需要付费 CodeScene platform 账号。重启 session，并在依赖分数前确认 codescene server 已连接。

2. 只调用 standalone tools

工具	何时使用
code_health_review	修改文件前做完整结构分析
code_health_score	每次变更后快速获取数字分数（delta check）
pre_commit_code_health_safeguard	阻止引入 Code Health 回归的 commits
analyze_change_set	开 PR 前做 branch-level 检查

不要调用 platform-only tools（例如仓库级 technical debt hotspot 列表）。不要引用 delta_analysis——standalone 不可用。

3. 解读分数（1–10）

范围	含义	智能体行为
9.0–10.0	Green — 健康	较安全可扩展；仍优先垂直切片
4.0–8.9	Yellow — 有债务	谨慎处理；不要顺手大重构
1.0–3.9	Red — 严重债务	只做窄范围改动

4. 运行反馈循环

改文件前

1. 对目标路径运行 code_health_review。
2. 记录 baseline score 和列出的 code smells。
3. 规划能完成任务的最小变更。

按分数定范围：低于 5——只做最小 diff；5–7——不做宽泛重构；高于 7——较适合重构，但每次编辑后仍要验证。

每次变更后

1. 对同一文件运行 code_health_score。
2. 与 code_health_review 的 baseline 对比。
3. 如果分数回退，继续前先修复。分数低于开始时，不要把任务标记为完成。

每次 commit 前——对 repository path 运行 pre_commit_code_health_safeguard。

PR 前——对 base branch（例如 main）运行 analyze_change_set。

示例

示例：Flask 可维护性改进

在 pallets/flask 上，一个只使用 standalone tools 的 agent loop：

1. 对目标模块运行 code_health_review（baseline 4.82）
2. 针对列出的 smells 做定向重构
3. 每次编辑后运行 code_health_score
4. commit 前运行 pre_commit_code_health_safeguard
5. PR 前运行 analyze_change_set

结果：Code Health 4.82 → 9.1（仅免费 standalone token）。

示例：AGENTS.md enforcement block

粘贴到项目 AGENTS.md 或 CLAUDE.md：

## Code Health (CodeScene MCP)

Before modifying any file: run `code_health_review`, note score and issues.

- Score below 5: problematic range — scope changes narrowly.
- Score 5–7: warning range — no broad refactors.

After each change: run `code_health_score` to verify delta.

- If score regressed: fix before continuing; never declare done if score dropped.

Before every commit: run `pre_commit_code_health_safeguard`.

Before PR: run `analyze_change_set`.

示例：反模式 vs 正确循环

# BAD: Edit first, check later
[large refactor without code_health_review]

# BAD: Ignore score drop
"Tests pass" → mark task done while Code Health decreased

# BAD: Broad refactor on red-score file (below 5)
Drive-by cleanup across the module

# GOOD: review → small change → score → commit safeguard → analyze_change_set

与 ECC 搭配

ECC skill / flow	Code Health MCP 作用
coding-standards	Style/naming；Code Health = structure/complexity
plankton-code-quality	写入时 lint/format；Code Health = 编辑前/后结构门控
verification-loop / /quality-gate	在“done”前加入结构回归检查
security-review	安全 vs 可维护性——相关时两者都用
tdd-workflow	测试通过 ≠ 设计健康——重构后检查分数

Context tip： ECC 建议保持 MCP 数量少。做实质编辑时启用 codescene；不用时禁用。

相关技能

• coding-standards — 基线约定
• plankton-code-quality — 写入时 lint/format hooks
• verification-loop — build/test/lint gate
• tdd-workflow — test-first development
• security-review — 安全检查清单
• documentation-lookup — 通过 Context7 查库文档（正交）