Code Sentinel

🚀 CodeSentinel MCP Server

CodeSentinelは、Model Context Protocol (MCP) 向けの包括的なコード品質分析サーバーです。Claude Codeやその他のMCP互換クライアントと統合し、セキュリティの脆弱性、誤解を招くパターン、不完全なコードを検出し、良い実践を強調します。

🚀 クイックスタート

AIコーディングアシスタントは、意図せずに微妙な問題を引き起こす可能性があります。例えば、ハードコードされたシークレット、空のcatchブロック、残されたTODOプレースホルダー、またはエラーを隠すパターンなどです。CodeSentinelは品質ゲートとして機能し、問題が本番環境に到達する前に、5つのカテゴリーにまたがる93の異なるパターンを分析します。

✨ 主な機能

• 検証対応型検出：多くのパターンには検証手順が含まれており、誤検出を減らします。
• LLM最適化出力：AIによる消費とアクションに適した構造化されたJSON出力。
• バランスの取れた分析：問題と強みの両方を検出し、公平なコード評価を行います。
• 多言語対応：TypeScript、JavaScript、Python、Go、Rust、Javaなどの多くの言語で動作します。

なぜTree-sitterやASTベースのツールではないのか？

CodeSentinelは意図的にパターンベースのアプローチを採用しており、AST解析ではなく、以下の理由があります。

解決する問題が異なる

従来のリンター（ESLint、tree-sitter）は構文エラーとスタイル違反を検出します。CodeSentinelは意味的に誤解を招くパターンを検出します。つまり、以下のようなコードです。

• 構文的に有効（すべてのリンターを通過）
• 構造的に正しい（有効なAST）
• しかし、AIエージェントが一般的に生成する深刻な問題を隠している

ASTツールが見逃す例

// ASTは: 有効なtry-catchブロックとして見る
// CodeSentinelは: 失敗を隠すエラーの飲み込みとして見る
try { riskyOperation(); } catch(e) { }

// ASTは: ブール値を返す有効な関数として見る
// CodeSentinelは: 常に成功する偽の実装として見る
function validateUser() { return true; } // TODO: implement

// ASTは: 有効なフォールバック式として見る
// CodeSentinelは: 失敗の隠蔽 - "データなし" と "取得失敗" を区別できない
const users = response.data || [];

// ASTは: 有効なreturn文として見る
// CodeSentinelは: サイレントな失敗の隠蔽として見る
if (error) { return null; } // error case

各アプローチが検出する内容

実際の問題: エージェントの振る舞い

AIコーディングエージェントは、見た目は正しいが微妙な欺瞞を含むコードを生成します。

1. "エラーを消す" - 空のcatch、サイレントな返却、飲み込まれた例外
2. プレースホルダー実装 - return true、return []、TODOコメント
3. 誤った信頼パターン - || [] フォールバックで取得失敗を隠す
4. 抑制の乱用 - @ts-ignore、eslint-disable で型エラーを隠す

これらのパターンはすべてのリンターを通過し、正常にコンパイルされます。ASTツールは有効な構造を見ますが、パターンベースの検出のみがコードの背後にある意味的な意図を捉えます。

いつ何を使うか

CodeSentinelはこれらのツールを補完し、それらが構造的に検出できないものを捉えます。

📦 インストール

npmから

npm install -g code-sentinel-mcp

ソースから

git clone https://github.com/salrad22/code-sentinel.git
cd code-sentinel
npm install
npm run build

💻 使用例

Claude Codeとの使用方法

クイックセットアップ

claude mcp add code-sentinel -- npx code-sentinel-mcp

グローバルにインストールされている場合

claude mcp add code-sentinel -- code-sentinel

手動設定

Claude CodeのMCP設定ファイル (~/.claude/claude_desktop_config.json) に追加します。

{
  "mcpServers": {
    "code-sentinel": {
      "command": "npx",
      "args": ["code-sentinel-mcp"]
    }
  }
}

リモートサーバー (Cloudflare Workers)

CodeSentinelは、Cloudflare Workers上のリモートMCPサーバーとしても利用できます。ローカルインストールは必要ありません！

クイック接続 (Claude Code)

claude mcp add-remote code-sentinel https://code-sentinel-mcp.sharara.dev/sse

または、Streamable HTTPエンドポイントを使用します（新しいクライアントに推奨）。

claude mcp add --transport http code-sentinel https://code-sentinel-mcp.sharara.dev/mcp

エンドポイント

Cloudflareでのセルフホスティング

独自のインスタンスをデプロイします。

cd cloudflare
npm install
npm run dev      # ローカル開発はlocalhost:8787
npm run deploy   # あなたのCloudflareアカウントにデプロイ

要件:

• Cloudflareアカウント（無料プランでも可）
• Wrangler CLI (npm install -g wrangler)
• wrangler login で認証

サーバーは持続的なMCP接続にDurable Objectsを使用します。データベースは必要ありません。

利用可能なツール

analyze_code

すべての問題と強みを含む構造化されたJSONを返す完全な分析。プログラムによる処理に最適です。 パラメータ:

• code (文字列、必須): 分析するソースコード
• filename (文字列、必須): 言語検出用のファイル名（例: "app.ts"）

返り値: 問題、強み、および要約統計を含むJSONオブジェクト。

generate_report

視覚的なHTMLレポートを含む完全な分析。人間によるレビューに最適です。 パラメータ:

• code (文字列、必須): 分析するソースコード
• filename (文字列、必須): 言語検出用のファイル名

返り値: Markdown要約と完全なHTMLレポート。

check_security

セキュリティに焦点を当てた分析のみ。具体的に脆弱性を監査したい場合に使用します。 パラメータ:

• code (文字列、必須): チェックするソースコード
• filename (文字列、必須): ファイル名

返り値: セキュリティ問題のリスト、または見つからなかったことの確認。

check_deceptive_patterns

エラーを隠すまたは誤った信頼を生み出すコードパターンをチェックします。 パラメータ:

• code (文字列、必須): チェックするソースコード
• filename (文字列、必須): ファイル名

返り値: 見つかった欺瞞パターンのリスト。

check_placeholders

TODO、ダミーデータ、および不完全な実装を見つけます。 パラメータ:

• code (文字列、必須): チェックするソースコード
• filename (文字列、必須): ファイル名

返り値: 見つかったプレースホルダーコードのリスト。

analyze_patterns

アーキテクチャ、デザイン、および実装パターンについてコードを分析します。パターンの使用、不一致を検出し、実行可能な提案を提供します。 パラメータ:

• code (文字列、必須): 分析するソースコード
• filename (文字列、必須): 言語検出用のファイル名
• level (文字列、オプション): 分析するパターンレベル:
  • architectural: システム構造パターン（レイヤリング、モジュール）
  • design: ギャング・オブ・フォーパターン（シングルトン、ファクトリー、オブザーバー）
  • code: 実装イディオム（エラーハンドリング、非同期パターン）
  • all: すべてのレベル（デフォルト）
• query (文字列、オプション): 分析を絞り込む自然言語クエリ（例: "エラーハンドリングはどのように行われていますか？"）

返り値: 検出されたパターン、不一致、提案、および実行可能なアクションアイテムを含むLLM最適化JSON。

analyze_design_patterns

ギャング・オブ・フォー（GoF）デザインパターンの集中分析。オブジェクト指向プログラミングの構造を理解するのに最適です。 パラメータ:

• code (文字列、必須): 分析するソースコード
• filename (文字列、必須): 言語検出用のファイル名

返り値: 信頼度、位置、および実装詳細を含む検出されたデザインパターン。

具体的な使用例

Claudeにコードを分析させる例を示します。

このコードの品質問題を分析してください:

const API_KEY = "sk-abc123456789";

async function fetchData() {
  try {
    const response = await fetch(url);
    return response.json();
  } catch (e) {
    // TODO: handle error
  }
}

CodeSentinelは以下を検出します。

• 重大 (CS-SEC003): ソースコードにハードコードされたOpenAI APIキー
• 高 (CS-DEC001): エラーをサイレントに飲み込む空のcatchブロック
• 低 (CS-PH001): 不完全な実装を示すTODOコメント

検出カテゴリ

セキュリティ問題 (CS-SEC)

誤解を招くパターン (CS-DEC)

プレースホルダー (CS-PH)

エラーとコードの悪臭 (CS-ERR)

強み (CS-STR)

スコアリングアルゴリズム

品質スコア（0-100）は以下の式で計算されます。

Score = 100 - (critical × 25) - (high × 15) - (medium × 5) - (low × 1) + (strengths × 2)

サポートされる言語

CodeSentinelはファイル拡張子から言語を検出します。

CodeSentinelの拡張

CodeSentinelはデータ駆動型のパターンシステムを使用しており、パターン定義と正規表現の生成を分離しています。これにより、新しいパターンの追加が容易になり、保守性が向上します。

プロジェクト構造

src/
├── patterns/
│   ├── types.ts           # パターン設定の型定義
│   ├── builders.ts        # 設定から正規表現を生成する関数
│   ├── compiler.ts        # 定義を実行可能なパターンにコンパイルする
│   └── definitions/
│       ├── security.ts    # セキュリティ脆弱性パターン
│       ├── deceptive.ts   # エラーを隠すパターン
│       ├── placeholders.ts # 不完全なコードパターン
│       ├── errors.ts      # コードの悪臭パターン
│       └── index.ts       # すべての定義をエクスポートする
├── analyzers/
│   ├── core.ts            # コンパイルされたパターンを使用する統一されたアナライザー
│   ├── security.ts        # セキュリティアナライザー（コアに委任）
│   ├── deceptive.ts       # 欺瞞アナライザー（コアに委任）
│   ├── placeholders.ts    # プレースホルダーアナライザー（コアに委任）
│   ├── errors.ts          # エラーアナライザー（コアに委任）
│   └── strengths.ts       # 強みアナライザー
└── index.ts               # MCPサーバーのエントリーポイント

新しいパターンの追加

手動で正規表現を書く代わりに、検出する内容を定義し、システムが正規表現を生成します。

// 古いアプローチ（手動正規表現）
{
  id: 'CS-DEC001',
  pattern: /catch\s*\([^)]*\)\s*\{\s*\}/g,  // エラーが発生しやすい
  title: 'Empty Catch Block',
  // ...
}

// 新しいアプローチ（データ駆動）
{
  id: 'CS-DEC001',
  title: 'Empty Catch Block',
  description: 'Silently swallowing errors makes debugging impossible.',
  severity: 'high',
  category: 'deceptive',
  suggestion: 'At minimum, log the error. Better: handle it appropriately.',
  match: {
    type: 'catch_handler',
    behavior: 'empty'
  }
}

利用可能なマッチタイプ

パターンを追加する手順

1. カテゴリを選択 - セキュリティ、欺瞞、プレースホルダー、またはエラー
2. 定義ファイルを開く - src/patterns/definitions/<category>.ts
3. 適切なマッチタイプを使用して新しいパターン定義を追加
4. ビルド - npm run build
5. テスト - MCPインスペクターを使用して検出を検証

パターン定義の構造

{
  id: string;              // 一意のID: CS-<CAT><NUM> (例: CS-SEC001)
  title: string;           // 短い説明（結果に表示される）
  description: string;     // 問題の詳細な説明
  severity: Severity;      // 'critical' | 'high' | 'medium' | 'low' | 'info'
  category: Category;      // 'security' | 'deceptive' | 'placeholder' | 'error'
  suggestion?: string;     // 問題を修正する方法
  match: MatchConfig;      // 検出する内容（上記のマッチタイプを参照）
  verification?: {         // オプション: 誤検出を減らす
    status: 'needs_verification' | 'confirmed';
    assumption?: string;
    confirmIf?: string;
    falsePositiveIf?: string;
  }
}

開発

# 依存関係のインストール
npm install

# ビルド
npm run build

# ウォッチモード
npm run watch

# MCPインスペクターでテスト
npm run inspector

コントリビューション

コントリビューションを歓迎します！以下の手順に従ってください。

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 既存の形式に従ってパターンを追加する
4. プルリクエストを送信する

📄 ライセンス

MIT

リンク

• GitHubリポジトリ
• npmパッケージ
• リモートサーバー
• Model Context Protocol
• Claude Code