Back to Details

codehealth-mcp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Health MCP (CodeScene)

代码健康度MCP（CodeScene）

Structural maintainability feedback for AI-assisted coding. Complements style/lint skills (
coding-standards
, 
plankton-code-quality
) with design-level health scores and regression gates.
Upstream: codescene-oss/codescene-mcp-server Package: 
@codescene/codehealth-mcp
(stdio via npx)
为AI辅助编码提供结构化可维护性反馈。通过设计层面的健康度评分和回归门禁，补充风格/代码检查技能（
coding-standards
、
plankton-code-quality
）的能力。
上游仓库： codescene-oss/codescene-mcp-server 包： 
@codescene/codehealth-mcp
（通过npx以标准输入输出方式运行）

Security and boundaries

安全与边界

Opt-in (ECC): The 
codescene
block in 
mcp-configs/mcp-servers.json
is a template only. ECC plugin installs do not auto-enable bundled MCP servers. Copy the entry into your config only if you want it. You can exclude it during ECC install/sync with 
ECC_DISABLED_MCPS=codescene,...
.
Credentials: No bundled token. Set 
CS_ACCESS_TOKEN
yourself (see getting-a-personal-access-token.md in the upstream repo). Never commit tokens to the repo.
What the tools read: When invoked, tools analyze files and git state in the local repository you point them at (paths you pass, plus branch context for 
analyze_change_set
). They do not run by themselves. For standalone mode, follow upstream privacy docs: codescene-mcp-server README and CodeScene policies. Do not use this skill for secrets, credentials, or paths you do not want analyzed.
If the MCP is unavailable (offline, bad token, server crash): Do not invent Code Health scores. Tell the user the check was skipped. Continue only with explicit user approval. Prefer lint/tests/verification-loop for gating when MCP is down. Re-enable checks once the server connects.
可选启用（ECC）： 
mcp-configs/mcp-servers.json
中的
codescene
块仅为模板。ECC插件安装不会自动启用捆绑的MCP服务器。仅当你需要时，才将该条目复制到你的配置中。你可以在ECC安装/同步时使用
ECC_DISABLED_MCPS=codescene,...
来排除它。
凭据： 未捆绑令牌。请自行设置
CS_ACCESS_TOKEN
（详见上游仓库中的getting-a-personal-access-token.md）。切勿将令牌提交到代码仓库。
工具读取内容： 调用时，工具会分析你指定的本地仓库中的文件和Git状态（你传入的路径，加上
analyze_change_set
所需的分支上下文）。它们不会自行运行。对于独立模式，请遵循上游隐私文档：codescene-mcp-server README和CodeScene政策。请勿将此技能用于你不希望被分析的机密、凭据或路径。
当MCP不可用时（离线、令牌无效、服务器崩溃）： 不要编造代码健康度分数。告知用户检查已跳过。仅在获得用户明确批准后才可继续。当MCP不可用时，优先使用代码检查/测试/验证循环作为门禁。服务器恢复连接后重新启用检查。

When to Use

适用场景

  • User asks to review code quality, refactor a file, or check if AI changes degraded maintainability
  • Before editing a hotspot, legacy module, or unfamiliar file
  • Before commit or pull request when you need a maintainability safeguard
  • After a large agent-written diff — verify Code Health did not regress
  • Pair with 
    verification-loop
    , 
    tdd-workflow
    , or 
    /quality-gate
    as a structural check (not a replacement for tests/lint)
  • 用户要求审查代码质量、重构文件，或检查AI生成的变更是否降低了可维护性
  • 在编辑热点文件、遗留模块或不熟悉的文件之前
  • 在需要可维护性保障的提交或**拉取请求（PR）**之前
  • 在Agent生成大型差异之后——验证代码健康度是否未出现退化
  • 与
    verification-loop
    、
    tdd-workflow
    或
    /quality-gate
    配合使用，作为结构化检查（不能替代测试/代码检查）

When to Activate

激活时机

Same triggers as When to Use above — this heading is what ECC uses for skill auto-activation.
与上述适用场景相同——此标题是ECC用于技能自动激活的触发条件。

How It Works

工作原理

1. Connect the MCP server

1. 连接MCP服务器

Copy the 
codescene
entry from 
mcp-configs/mcp-servers.json
into your harness MCP config.
Claude Code (
~/.claude.json
→ 
mcpServers
):
json
"codescene": {
  "command": "npx",
  "args": ["-y", "@codescene/codehealth-mcp"],
  "env": {
    "CS_ACCESS_TOKEN": "YOUR_CS_ACCESS_TOKEN_HERE"
  }
}
Project-scoped: merge the same block into 
.mcp.json
at the repo root.
Token setup is documented in the upstream repo (link above). Standalone mode does not require a paid CodeScene platform account for the four tools listed below. Restart the session and confirm the 
codescene
server is connected before relying on scores.
将
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"
  }
}
项目范围配置： 将相同的块合并到仓库根目录下的
.mcp.json
中。
令牌设置文档见上游仓库（上方链接）。独立模式不需要付费的CodeScene平台账户即可使用以下列出的四个工具。在依赖分数之前，请重启会话并确认
codescene
服务器已连接。

2. Call standalone tools only

2. 仅调用独立工具

ToolWhen to use
code_health_review
Full structural analysis before modifying a file
code_health_score
Quick numeric score after each change (delta check)
pre_commit_code_health_safeguard
Block commits that introduce Code Health regressions
analyze_change_set
Branch-level check before opening a PR
Do not call platform-only tools (e.g. repository-wide technical debt hotspot lists). Do not reference 
delta_analysis
— not available on standalone.
工具适用场景
code_health_review
修改文件前进行完整的结构化分析
code_health_score
每次变更后快速获取数值分数（变化量检查）
pre_commit_code_health_safeguard
阻止引入代码健康度退化的提交
analyze_change_set
打开PR前进行分支级检查
请勿调用仅平台可用的工具（例如仓库级技术债务热点列表）。请勿引用
delta_analysis
——独立模式不支持该功能。

3. Interpret scores (1–10)

3. 分数解读（1–10）

RangeMeaningAgent behavior
9.0–10.0Green — healthySafer to extend; still prefer vertical slices
4.0–8.9Yellow — debtTread carefully; no drive-by refactors
1.0–3.9Red — severe debtNarrow scope only
分数范围含义Agent行为
9.0–10.0绿色——健康更适合扩展；仍优先采用垂直切片开发
4.0–8.9黄色——存在债务谨慎操作；禁止即兴重构
1.0–3.9红色——严重债务仅进行窄范围变更

4. Run the feedback loop

4. 运行反馈循环

Before touching a file
  1. Run 
    code_health_review
    on the target path.
  2. Record baseline score and listed code smells.
  3. Plan the smallest change that addresses the task.
Scope by score: below 5 — minimal diff only; 5–7 — no broad refactors; above 7 — safer to refactor, still verify after each edit.
After each change
  1. Run 
    code_health_score
    on the same file.
  2. Compare to the baseline from 
    code_health_review
    .
  3. If the score regressed, fix before continuing. Never mark the task done while the score is lower than when you started.
Before every commit — run 
pre_commit_code_health_safeguard
on the repository path.
Before a PR — run 
analyze_change_set
against the base branch (e.g. 
main
).
修改文件前
  1. 对目标路径运行
    code_health_review
    。
  2. 记录基准分数和列出的代码异味。
  3. 规划最小化的变更以完成任务。
根据分数确定范围：低于5分——仅进行最小差异变更；5–7分——不进行大范围重构；高于7分——重构相对安全，但每次编辑后仍需验证。
每次变更后
  1. 对同一文件运行
    code_health_score
    。
  2. 与
    code_health_review
    得到的基准分数进行比较。
  3. 如果分数出现退化，修复后再继续。分数低于初始值时，切勿标记任务完成。
每次提交前——对仓库路径运行
pre_commit_code_health_safeguard
。
PR前——针对基准分支（例如
main
）运行
analyze_change_set
。

Examples

示例

Example: Flask maintainability improvement

示例：Flask可维护性改进

On 
pallets/flask
, an agent loop using only standalone tools:
  1. code_health_review
    on a target module (baseline 4.82)
  2. Targeted refactor addressing listed smells
  3. code_health_score
    after each edit
  4. pre_commit_code_health_safeguard
    before commit
  5. analyze_change_set
    before PR
Result: Code Health 4.82 → 9.1 (free standalone token only).
在
pallets/flask
项目中，仅使用独立工具的Agent循环：
  1. 对目标模块运行
    code_health_review
    （基准分数4.82）
  2. 针对性重构以解决列出的代码异味
  3. 每次编辑后运行
    code_health_score
  4. 提交前运行
    pre_commit_code_health_safeguard
  5. PR前运行
    analyze_change_set
结果：代码健康度从4.82提升至9.1（仅使用免费独立令牌）。

Example: AGENTS.md enforcement block

示例：AGENTS.md中的规则块

Paste into the project 
AGENTS.md
or 
CLAUDE.md
:
md
undefined
粘贴到项目的
AGENTS.md
或
CLAUDE.md
中：
md
undefined

Code Health (CodeScene MCP)

代码健康度（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
.
undefined
修改任何文件前：运行
code_health_review
，记录分数和问题。
  • 分数低于5：问题范围——窄化变更范围。
  • 分数5–7：警告范围——不进行大范围重构。
每次变更后：运行
code_health_score
验证变化量。
  • 如果分数退化：修复后再继续；分数下降时切勿宣布任务完成。
每次提交前：运行
pre_commit_code_health_safeguard
。
PR前：运行
analyze_change_set
。
undefined

Example: anti-patterns vs correct loop

示例：反模式与正确流程对比

markdown
undefined
markdown
undefined

BAD: Edit first, check later

错误：先编辑，后检查

[large refactor without code_health_review]
[未运行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)

错误：对红色分数文件（低于5分）进行大范围重构

Drive-by cleanup across the module
即兴清理整个模块

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

正确：审查→小变更→评分→提交门禁→analyze_change_set

undefined
undefined

Pairing with ECC

与ECC配合使用

ECC skill / flowCode Health MCP role
coding-standards
Style/naming; Code Health = structure/complexity
plankton-code-quality
Write-time lint/format; Code Health = pre/post edit structural gate
verification-loop
/ 
/quality-gate
Add structural regression check before "done"
security-review
Security vs maintainability — use both when relevant
tdd-workflow
Tests pass ≠ healthy design — check score after refactors
Context tip: ECC recommends keeping MCP count low. Enable 
codescene
when doing substantive edits; disable when not needed.
ECC技能/流程代码健康度MCP的角色
coding-standards
风格/命名规范；代码健康度=结构/复杂度检测
plankton-code-quality
编写时的代码检查/格式化；代码健康度=编辑前后的结构门禁
verification-loop
/ 
/quality-gate
在标记“完成”前添加结构化回归检查
security-review
安全检测 vs 可维护性检测——相关时同时使用两者
tdd-workflow
测试通过≠设计健康——重构后检查分数
上下文提示： ECC建议减少MCP的启用数量。进行实质性编辑时启用
codescene
；不需要时禁用。

Related Skills

相关技能

  • coding-standards
    — baseline conventions
  • plankton-code-quality
    — write-time lint/format hooks
  • verification-loop
    — build/test/lint gate
  • tdd-workflow
    — test-first development
  • security-review
    — security checklist
  • documentation-lookup
    — library docs via Context7 (orthogonal)
  • coding-standards
    ——基础规范
  • plankton-code-quality
    ——编写时的代码检查/格式化钩子
  • verification-loop
    ——构建/测试/代码检查门禁
  • tdd-workflow
    ——测试优先开发
  • security-review
    ——安全检查清单
  • documentation-lookup
    ——通过Context7查询库文档（正交功能）