Code Health MCP (CodeScene)
AI支援コーディング向けの構造的保守性フィードバック。スタイル/リントスキル（coding-standards、plankton-code-quality）を設計レベルのヘルススコアと退行ゲートで補完します。
上流リポジトリ: codescene-oss/codescene-mcp-server
パッケージ: @codescene/codehealth-mcp（npx 経由の stdio）
セキュリティと境界
オプトイン (ECC): mcp-configs/mcp-servers.json 内の codescene ブロックはテンプレートにすぎません。ECC プラグインインストールはバンドルされた MCP サーバーを自動有効化しません。必要な場合のみエントリを設定にコピーしてください。ECC_DISABLED_MCPS=codescene,... を使用して ECC インストール/同期時に除外することもできます。
認証情報: トークンはバンドルされていません。CS_ACCESS_TOKEN は自分で設定してください（上流リポジトリの getting-a-personal-access-token.md を参照）。トークンをリポジトリにコミットしないでください。
ツールが読み取るもの: 呼び出されると、ツールは指定したローカルリポジトリ内のファイルと git 状態を分析します（渡したパスと、analyze_change_set の場合はブランチコンテキスト）。自動的に実行されることはありません。スタンドアロンモードの場合は、上流のプライバシードキュメント codescene-mcp-server README および CodeScene ポリシー に従ってください。分析対象としたくないシークレット、認証情報、パスにはこのスキルを使用しないでください。
MCP が利用不可の場合（オフライン、トークン不良、サーバークラッシュ）: Code Health スコアを捏造しないでください。チェックがスキップされたことをユーザーに伝えてください。明示的なユーザー承認がある場合のみ続行してください。MCP がダウンしている場合は、ゲートにリント/テスト/検証ループを優先してください。サーバーが接続されたらチェックを再有効化してください。
使用すべきタイミング
- ユーザーがコード品質のレビュー、ファイルのリフアクタリング、またはAI変更による保守性の劣化確認を依頼したとき
- ホットスポット、レガシーモジュール、または不慣れなファイルを編集する前
- 保守性の安全策が必要なコミットまたはプルリクエストの前
- 大規模なエージェント生成差分の後——Code Health が退行していないことを確認
- 構造的チェックとして
verification-loop、tdd-workflow、または/quality-gateと組み合わせる（テスト/リントの代替ではない）
有効化すべきタイミング
上記 使用すべきタイミング と同じトリガー——この見出しは ECC がスキルの自動有効化に使用します。
動作方法
1. MCP サーバーに接続する
mcp-configs/mcp-servers.json から codescene エントリをあなたのハーネス MCP 設定にコピーします。
Claude Code（~/.claude.json → mcpServers）:
"codescene": {
"command": "npx",
"args": ["-y", "@codescene/codehealth-mcp"],
"env": {
"CS_ACCESS_TOKEN": "YOUR_CS_ACCESS_TOKEN_HERE"
}
}
プロジェクトスコープ: 同じブロックをリポジトリルートの .mcp.json にマージします。
トークン設定は上流リポジトリ（上記リンク）に文書化されています。スタンドアロンモードでは、以下にリストされた4つのツールに対して有料の CodeScene プラットフォームアカウントは不要です。スコアに依存する前に、セッションを再起動して codescene サーバーが接続されていることを確認してください。
2. スタンドアロンツールのみ呼び出す
| ツール | 使用すべきタイミング |
|---|---|
code_health_review | ファイルを変更する前の完全構造分析 |
code_health_score | 各変更後のクイックスコア取得（差分チェック） |
pre_commit_code_health_safeguard | Code Health 退行をもたらすコミットをブロック |
analyze_change_set | PRを開く前のブランチレベルチェック |
プラットフォーム専用ツール（例：リポジトリ全体の技術的負債ホットスポットリスト）は呼び出さないでください。delta_analysis も参照しないでください——スタンドアロンでは利用できません。
3. スコアの解釈（1〜10）
| 範囲 | 意味 | エージェントの動作 |
|---|---|---|
| 9.0〜10.0 | 緑——健全 | 拡張しても安全だが、垂直スライスを優先 |
| 4.0〜8.9 | 黄——負債 | 慎重に進める。通りすがりのリファクタリングはしない |
| 1.0〜3.9 | 赤——深刻な負債 | 限定的なスコープのみ |
4. フィードバックループの実行
ファイルに手を付ける前
- 対象パスで
code_health_reviewを実行。 - ベースラインスコアとリストされたコードの臭いを記録。
- タスクに対応する最小の変更を計画。
スコアによるスコープ設定: 5未満——最小限の差分のみ。5〜7——広範なリファクタリングはしない。7以上——リファクタリングはより安全だが、各編集後も確認。
各変更後
- 同じファイルで
code_health_scoreを実行。 code_health_reviewからのベースラインと比較。- スコアが退行したら、続行する前に修正。開始時よりスコアが低いままタスクを完了としない。
すべてのコミット前——リポジトリパスで pre_commit_code_health_safeguard を実行。
PR前——ベースブランチ（例：main）に対して analyze_change_set を実行。
例
例: Flask 保守性改善
pallets/flask で、スタンドアロンツールのみを使用するエージェントループ:
- 対象モジュールで
code_health_review（ベースライン 4.82） - リストされた臭いに対処する的を絞ったリファクタリング
- 各編集後に
code_health_score - コミット前に
pre_commit_code_health_safeguard - PR前に
analyze_change_set
結果: Code Health 4.82 → 9.1（無料スタンドアロントークンのみ）。
例: AGENTS.md 強制ブロック
プロジェクトの AGENTS.md または CLAUDE.md に貼り付ける:
## Code Health (CodeScene MCP)
ファイルを変更する前に: `code_health_review` を実行し、スコアと問題を記録する。
- スコアが5未満: 問題のある範囲——変更範囲を狭くする。
- スコアが5〜7: 警告範囲——広範なリファクタリングはしない。
各変更後: `code_health_score` で差分を確認する。
- スコアが退行した場合: 続行する前に修正し、スコアが低下したままタスク完了としない。
すべてのコミット前: `pre_commit_code_health_safeguard` を実行。
PR前: `analyze_change_set` を実行。
例: アンチパターン vs 正しいループ
# 悪い例: 先に編集、後で確認
[code_health_review なしでの大規模リファクタリング]
# 悪い例: スコア低下を無視
「テストが通った」→ Code Health が低下したままタスク完了
# 悪い例: レッドスコア（5未満）のファイルで広範なリファクタリング
モジュール全体にわたる通りすがりのクリーンアップ
# 良い例: レビュー → 小さな変更 → スコア → コミットガード → analyze_change_set
ECC との連携
| ECC スキル/フロー | Code Health MCP の役割 |
|---|---|
coding-standards | スタイル/命名。Code Health = 構造/複雑性 |
plankton-code-quality | 書き込み時リント/フォーマット。Code Health = 編集前後の構造的ゲート |
verification-loop / /quality-gate | 「完了」前に構造的退行チェックを追加 |
security-review | セキュリティ vs 保守性——関連する場合は両方使用 |
tdd-workflow | テスト合格 ≠ 健全な設計——リファクタリング後にスコアを確認 |
コンテキストのヒント: ECC は MCP の数を少なく保つことを推奨しています。実質的な編集を行うときは codescene を有効にし、不要なときは無効にしてください。
関連スキル
coding-standards— 基本規約plankton-code-quality— 書き込み時リント/フォーマットフックverification-loop— ビルド/テスト/リントゲートtdd-workflow— テスト駆動開発security-review— セキュリティチェックリストdocumentation-lookup— Context7 経由のライブラリドキュメント（直交）