codehealth-mcp

# Code Health MCP (CodeScene) 面向 AI 辅助编码的结构性可维护性反馈。它补充 style/lint 技能（`coding-standards`、`plankton-code-quality`），提供**设计层面**的健康分数和回归门控。 **上游：** [codescene-oss/codescene-mcp-server](https://github.com/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](https://github.com/codescene-oss/codescene-mcp-server/blob/main/docs/getting-a-personal-access-token.md)）。不要把 tokens 提交到仓库。 **工具读取什么：** 调用时，工具会分析你指向的**本地仓库**中的文件和 git 状态（你传入的路径，以及 `analyze_change_set` 使用的 branch context）。它们不会自行运行。standalone mode 请遵循上游隐私文档：[codescene-mcp-server README](https://github.com/codescene-oss/codescene-mcp-server#frequently-asked-questions) 和 [CodeScene policies](https://codescene.com/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`）： ```json "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`： ```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 正确循环 ```markdown # 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 查库文档（正交）