CodeSentinel

---

問題

デッドコード、循環依存、過度な結合、アーキテクチャの乖離は、日々の作業では見えません。静的解析ツールは、誰も確認しない CI ダッシュボードに大量のノイズを出します。CodeHealth MCP は、Model Context Protocol を介して、開発者が実際に使うツールにこうした知見をもたらします。

---

CodeHealth MCP の機能

あらゆる MCP 対応クライアントで利用できる 7 つの分析ツール：

ツール	検出内容
analyze_dead_code	未使用の関数、クラス、モジュールを、ファイルと行番号、修正案とともに検出
detect_circular_deps	DFS によるモジュールのインポートサイクル検出と影響評価
analyze_coupling	モジュールごとのファンアウト、密結合クラスターの検出、リファクタリングの提案
detect_architectural_drift	レイヤー境界違反（UI→Data、Business→UI など）を検出
full_health_scan	4 種類すべての分析に加え、0～100 の健全性スコアと優先順位付きアクション項目を提示
explain_finding	検出結果を AI で詳細に説明
check_mcp_health	リモート MCP ハンドシェイク（initialize + tools/list）、スキーマの乖離、シークレットスキャンを確認 — HTTP 200 でも健全とは限りません

---

対応環境

クライアント	追加方法
Claude Desktop	claude_desktop_config.json に追加
Cursor / Windsurf	MCP 設定に追加
Slack	Block Kit UI を備えた組み込みの Agent Builder 連携
あらゆる MCP クライアント	標準 MCP サーバー（stdio）またはリモート Streamable HTTP

Claude Desktop の設定（stdio）

{
  "mcpServers": {
    "codehealth": {
      "command": "node",
      "args": ["/path/to/codehealth-mcp/mcp-server/index.js"]
    }
  }
}

リモート Streamable HTTP（Glama／ホスト型）

CodeSentinel を Glama のリモートコネクターとして掲載するには、パブリック HTTPS と streamable-http が必要です。デプロイ環境からホスト名を置き換えてください。架空のホスト名をコミットしないでください。

export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:http

ローカルのデフォルト：http://127.0.0.1:8787/mcp（ヘルスチェック：GET /health）。本番環境では HTTPS が必須です。

{
  "mcpServers": {
    "codesentinel": {
      "type": "streamable-http",
      "url": "https://${MCP_HTTP_HOST}/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_BEARER_TOKEN}"
      }
    }
  }
}

Cursor／Claude のリモートコネクターでは、同じ url と Authorization ヘッダーを使用します。認証なしで /mcp にアクセスすると HTTP 401 が返されます。LLM_API_KEY などのプロバイダーキーはサーバー上に保持され、レスポンスに含まれることはありません。

Vercel へのデプロイ（パブリック HTTPS）

ステートレスな Streamable HTTP（JSON リクエスト／レスポンス）は Vercel Fluid Compute 上で動作します。スティッキーセッションは不要です。架空のホスト名を使わず、Vercel が割り当てた URL を使用してください。

npx vercel          # preview
npx vercel env add MCP_BEARER_TOKEN     # required for /mcp — fail-closed Bearer auth
npx vercel env add LLM_API_KEY          # optional, server-side only
npx vercel env add DAYTONA_API_KEY      # optional, isolated GitHub scans
npx vercel env add GITHUB_TOKEN         # optional, private repo fetch
npx vercel --prod
# GET /health must be 200 even if MCP_BEARER_TOKEN is not set yet.

デプロイ後、MCP エンドポイントは次のとおりです。

https://$VERCEL_PROJECT_PRODUCTION_URL/mcp

（特定のデプロイには VERCEL_URL を使用します）。ヘルスチェック：https://$VERCEL_PROJECT_PRODUCTION_URL/health。

Glama／クライアントが initialize を完了できるよう、本番ホストでは Vercel Deployment Protection をオフにしてください。

Glama コネクターのフィールド（Vercel の URL が利用可能になってから入力）

フィールド	値
種類	コネクター（リモート MCP）
サーバー URL	https://$VERCEL_PROJECT_PRODUCTION_URL/mcp
トランスポート	streamable-http
認証	API Key / Bearer
ヘッダー	Authorization
ヘッダー値	Bearer $MCP_BEARER_TOKEN（Vercel の env と同じシークレット）
所有権の申告	https://$VERCEL_PROJECT_PRODUCTION_URL/.well-known/glama.json（静的な public/ ファイル）

Vercel の env 変数、Fluid Compute に関する注意事項、Docker/Fly の代替手段については、docs/mcp-http.md を参照してください。

---

クイックスタート

git clone https://github.com/icohangar-ops/codesentinel.git
cd codesentinel
npm install
cp .env.sample .env
# Edit .env with your LLM API key (and MCP_BEARER_TOKEN for HTTP mode)
npm start

HTTP MCP（同じツール、Bearer 認証）：

export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:http
npm run mcp:http:smoke

Claude Desktop で使う

Run a full health scan on /path/to/my/repo

Find circular dependencies in the frontend

Check coupling metrics in src/services

Check MCP health on https://example.com/mcp

リモート MCP プロトコルのヘルスチェック（HTTP の稼働時間ではありません）

リモート MCP エンドポイントは、initialize、tools/list、 または SSE ストリームに失敗していても、HTTP 200 を返すことがあります。CodeSentinel はプロトコル自体をプローブします。

• Streamable HTTP / レガシー SSE のハンドシェイクを合成（initialize + tools/list）
• 正規のツールスキーマのハッシュとドリフトアラーム
• 検出レイテンシーのメトリクス
• エージェントのコンテキストに取り込まれる前の、ツールの説明／スキーマのシークレットスキャン

npm test
npm run mcp:health -- https://example.com/mcp

ライブラリ：src/lib/mcp-health。アナライザー：lib/analyzers/mcp-health.js。 詳しい説明：docs/mcp-health.md。

Daytona サンドボックススキャン（任意）

DAYTONA_API_KEY を設定してください（プライベートリポジトリの場合は、必要に応じて GITHUB_TOKEN も設定します）。MCP ツールと Slack 分析は、GitHub URL を Daytona VM に浅くクローンし、デモデータの代わりに最新のインポートグラフ分析結果を返します。

フォールバック動作（正直なデモ）： Daytona を利用できない場合、またはライブスキャンが期限（lib/repo-fetcher.js の SCAN_DEADLINE_MS）に間に合わない場合、lib/analysis-engine.js はリクエストに fallback: true のフラグを付けます。アナライザーはリクエストを未回答のままにせず、決定論的なデモ分析結果を返します。これは意図的に文書化されたフォールバック（lib/analysis-engine.js、lib/repo-fetcher.js）であり、サイレントエラーではありません。ライブスキャンには scanMode: "daytona" のマークが付きます。

full_health_scan repo_path=https://github.com/org/repo

Slack で使う

Slack アプリのマニフェストを追加し、Agent Builder を有効にして、任意のチャンネルで @CodeHealth にメンションしてください。

---

アーキテクチャ

┌──────────────────────────────────────────┐
│          MCP CLIENT (any)                │
│  Claude Desktop, Cursor, Slack, etc.     │
└──────────────────┬───────────────────────┘
                   │ MCP Protocol (stdio or Streamable HTTP)
┌──────────────────▼───────────────────────┐
│         CODEHEALTH MCP SERVER            │
│                                          │
│  🔧 analyze_dead_code                    │
│  🔧 detect_circular_deps                 │
│  🔧 analyze_coupling                     │
│  🔧 detect_architectural_drift           │
│  🔧 full_health_scan                     │
│  🔧 explain_finding                      │
│  🔧 check_mcp_health                     │
│                                          │
│  ┌──────────────────────────────────┐    │
│  │       Analysis Engine            │    │
│  │  dead-code | circular-deps       │    │
│  │  coupling | drift | mcp-health   │    │
│  └──────────────────────────────────┘    │
│                                          │
│  ┌──────────────────────────────────┐    │
│  │       LLM Provider               │    │
│  │  Deepseek / OpenAI / Anthropic   │    │
│  └──────────────────────────────────┘    │
└──────────────────────────────────────────┘

---

Slack 統合

CodeHealth MCP には、次の機能を備えた完全な Slack Agent Builder アプリが付属しています。

• Block Kit UI — 重大度別にコード化された分析結果、ヘルススコア、実行可能な提案
• スレッドベースの会話 — スレッド内でのフォローアップ分析
• おすすめのプロンプト — ワンクリックで分析を開始
• MCP サーバー — 同じツールをどこでも利用可能

デモ用サンドボックス（Devpost の審査員向け）

ライブデモのワークスペースは codehealthdemo.slack.com です。CodeSentinel エージェント（アプリ ID A0BEHRDN5TQ）がインストールされ、認証されています。任意のチャンネルでメンションしてください。

@CodeSentinel run a full health scan on https://github.com/icohangar-ops/codesentinel

サンドボックスの設定：

サンドボックス内のライブエージェント応答 — #general で @CodeSentinel に実際にメンションすると、Daytona のサンドボックス内でリポジトリスキャンが実行されます。

アプリの認証情報とアプリ ID	エージェント機能が有効	Socket Mode が有効

---

カスタムアナライザーの追加

各アナライザーはシンプルなインターフェースに従います。

function analyze(repoInfo) {
  return {
    type: "your_analysis_type",
    findings: [
      {
        type: "finding_type",
        severity: "critical" | "warning" | "info",
        file: "path/to/file.ts",
        line: 42,
        name: "symbol_name",
        reason: "Why this is a problem",
        suggestion: "How to fix it",
      },
    ],
    stats: { /* summary metrics */ },
  };
}

lib/analyzers/ に新しいアナライザーを追加して analysis-engine.js に登録すると、Slack と MCP から自動的に利用できるようになります。

---

ロードマップ

• 実際の AST 分析 — TypeScript には ts-morph、多言語対応には tree-sitter
• GitHub App — PR に対する自動分析とインラインコメント
• 履歴の傾向 — リポジトリごとのヘルススコアの推移を追跡
• カスタムアーキテクチャルール — 設定によるレイヤー境界の定義
• チームダッシュボード — Slack Canvas でヘルス情報を集約

---

伝播マトリックス — Wave C の行

Row 18 — 常に応答するための段階的縮退：採用済み（要約ステップ）

Slack アシスタントのフロー（listeners/assistant/message.js）では、決定論的なスキャン（runAnalysis）を実行した後、AI によるエグゼクティブサマリーを生成します（lib/llm-provider.js）。この変更以前は、要約ステップで LLMUnavailableError が発生するとフロー全体が失敗し、完了済みの決定論的なスキャン結果が破棄され、ユーザーにはエラーが返されていました。現在、要約ステップでは summarizeWithLadder（Row 18 の制限付き段階的処理、FULL → DEGRADED）を実行します。LLM が利用できない場合は明示的に縮退し、ナラティブを付けずに調査結果を返し、インラインで「AI summary unavailable — LLM unreachable. Deterministic findings only」と表示します。それ以外のすべてのケースでは、LLMUnavailableError が型付きエラーとして維持されます。LLM の利用不可以外のエラーは、引き続き大きく報告されます。テスト：test/assistant-degradation.test.js（段階的処理の動作と、lib/block-kit-builder.js における縮退を示すラベルの確認）。

再検討のきっかけ： 分析パス自体がモデルに依存するようになった場合（モデルがスコア付けした調査結果であり、モデルが要約したレポートではない場合）。その場合、段階的処理の対象を要約だけでなく、調査結果の生成にも広げる必要があります。

---

プロジェクト構成

codehealth-mcp/
├── app.js                    # Bolt app entry (Slack)
├── manifest.json             # Slack app manifest
├── lib/
│   ├── analysis-engine.js    # Analysis orchestrator + health score
│   ├── intent-parser.js      # NLP intent classification
│   ├── block-kit-builder.js  # Rich Slack UI
│   ├── llm-provider.js       # Multi-provider LLM
│   └── analyzers/            # dead-code, circular-deps, coupling, drift, mcp-health
├── src/lib/
│   ├── resilience/           # safeFetch / retry
│   └── mcp-health/           # handshake, schema hash, secret scan, CLI
├── mcp-server/
│   ├── index.js              # MCP stdio entry (unchanged tools)
│   ├── http.js               # Streamable HTTP (stateless, Bearer auth)
│   ├── create-server.js      # Shared tool registration
│   └── package.json
├── docs/mcp-http.md          # Remote / Glama / Fly / Railway notes
├── test/                     # handshake / HTTP transport / secret-scan tests
└── functions/                # Slack function definitions

---

コミュニティとレジストリ

CodeHealth MCP は、以下のディレクトリに掲載されています。

• awesome-mcp-servers – MCP サーバーを厳選してまとめたリストです。
• MCP Registry – Model Context Protocol サーバーの公式レジストリです。
• Glama – リモートコネクターは、streamable-http に対応したパブリックな HTTPS で公開する必要があります（docs/mcp-http.md を参照）。

---

ライセンス

MIT。詳細は LICENSE を参照してください。