菜单
Real-time structural Code Health via CodeScene MCP — review before edits, verify score deltas after changes, gate commits and PRs. Use when reviewing code quality, refactoring, checking if AI changes degraded a file, or before commit/PR.
| name | codehealth-mcp |
| description | Real-time structural Code Health via CodeScene MCP — review before edits, verify score deltas after changes, gate commits and PRs. Use when reviewing code quality, refactoring, checking if AI changes degraded a file, or before commit/PR. |
| origin | community |
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)
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.
verification-loop, tdd-workflow, or /quality-gate as a structural check (not a replacement for tests/lint)Same triggers as When to Use above — this heading is what ECC uses for skill auto-activation.
Copy the codescene entry from mcp-configs/mcp-servers.json into your harness MCP config.
Claude Code (~/.claude.json → mcpServers):
"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.
| Tool | When 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.
| Range | Meaning | Agent behavior |
|---|---|---|
| 9.0–10.0 | Green — healthy | Safer to extend; still prefer vertical slices |
| 4.0–8.9 | Yellow — debt | Tread carefully; no drive-by refactors |
| 1.0–3.9 | Red — severe debt | Narrow scope only |
Before touching a file
code_health_review on the target path.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
code_health_score on the same file.code_health_review.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).
On pallets/flask, an agent loop using only standalone tools:
code_health_review on a target module (baseline 4.82)code_health_score after each editpre_commit_code_health_safeguard before commitanalyze_change_set before PRResult: Code Health 4.82 → 9.1 (free standalone token only).
Paste into the project AGENTS.md or 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`.
# 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 skill / flow | Code 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.
coding-standards — baseline conventionsplankton-code-quality — write-time lint/format hooksverification-loop — build/test/lint gatetdd-workflow — test-first developmentsecurity-review — security checklistdocumentation-lookup — library docs via Context7 (orthogonal)Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination.
Orchestrate building a brand-new feature end to end — research, plan, TDD implementation, review, and gated commit — by delegating each phase to the matching ECC agent. Use when adding a capability that does not exist yet.
Orchestrate bootstrapping a working MVP from a design or spec document — ingest the doc, plan thin vertical slices, scaffold the first end-to-end slice, then TDD-implement, review, and gated commit. Use to turn an SDD/PRD into a running starting point.
Orchestrate altering an existing, working feature to new desired behavior — update its tests to the new spec, change the implementation to match, review, and gated commit. Use when behavior is not broken but should be different.
Orchestrate fixing a bug — reproduce it as a failing regression test, fix to green, review, and gated commit — by delegating each phase to the matching ECC agent. Use when existing behavior is broken or wrong.
Shared orchestration engine for the orch-* skill family. Defines the gated Research-Plan-TDD-Review-Commit pipeline, the size classifier, the agent map, and the two human gates that the orch-* operation skills delegate to. Not usually invoked directly.