Codesentinel

CodeSentinel MCP Server

Model Context Protocol（MCP）向けの包括的なコード品質分析サーバーです。CodeSentinel は Claude Code やその他の MCP 互換クライアントと連携し、セキュリティ上の脆弱性、欺瞞的なパターン、不完全なコードを検出し、優れたプラクティスを強調表示します。

CodeSentinel を選ぶ理由

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 sees: valid try-catch block
// CodeSentinel sees: error swallowing that masks failures
try { riskyOperation(); } catch(e) { }

// AST sees: valid function returning boolean
// CodeSentinel sees: fake implementation that always succeeds
function validateUser() { return true; } // TODO: implement

// AST sees: valid fallback expression
// CodeSentinel sees: failure masking - "no data" vs "fetch failed" indistinguishable
const users = response.data || [];

// AST sees: valid return statement
// CodeSentinel sees: silent failure hiding
if (error) { return null; } // error case

それぞれのアプローチで検出できるもの

問題の種類	AST/Tree-sitter	CodeSentinel
構文エラー	はい	いいえ（目的ではありません）
セミコロンの欠落	はい	いいえ
未使用の変数	はい	いいえ
空の catch ブロック	部分的	はい
エラーの暗黙的な返却	いいえ	はい
偽の成功レスポンス	いいえ	はい
TODO／プレースホルダーコード	いいえ	はい
エラーを隠すフォールバック	いいえ	はい
ハードコードされたシークレット	限定的	はい
欺瞞的なコメント	いいえ	はい

本当の問題：エージェントの動作

AI コーディングエージェントは、正しそうに見える一方で、微妙な欺瞞を含むコードを生成します。

1. 「エラーを消す」 - 空の catch、暗黙的な return、例外の握りつぶし
2. プレースホルダー実装 - return true、return []、TODO コメント
3. 誤った安心感を与えるパターン - fetch の失敗を隠す || [] フォールバック
4. 抑制の乱用 - 型エラーを隠すための @ts-ignore、eslint-disable

これらのパターンは、すべてのリンターを通過し、問題なくコンパイルされます。AST ツールには有効な構造として認識されます。コードの背後にある意味的な意図を捉えられるのは、パターンベースの検出だけです。

使い分け

ツール	用途
ESLint/TSLint	スタイルの一貫性、構文ルール、未使用コード
Tree-sitter	構文の強調表示、コードナビゲーション、リファクタリング
TypeScript	型安全性、コンパイル時エラー
CodeSentinel	エージェントが生成する欺瞞、エラーの隠蔽、不完全な実装

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

機能

• セキュリティ分析（16 パターン）：ハードコードされたシークレット、SQL インジェクション、XSS、コマンドインジェクション、安全性の低い暗号化、無効化された SSL など
• 欺瞞的なパターンの検出（17 パターン）：空の catch ブロック、サイレントな失敗、エラーを隠すフォールバック、リンターの抑制
• プレースホルダーの検出（19 パターン）：TODO/FIXME/HACK コメント、lorem ipsum、テストデータ、不完全な実装
• エラーとコードの臭いの検出（18 パターン）：型変換の問題、null 参照、非同期処理のアンチパターン、浮動小数点数の比較
• 長所の認識（23 パターン）：適切な型付け、エラー処理、テストパターン、ドキュメントなど、優れたプラクティスを強調表示します
• HTML レポート：品質スコアと実行可能な提案を含む視覚的なレポート

インストール

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

エンドポイント

エンドポイント	プロトコル	説明
https://code-sentinel-mcp.sharara.dev/mcp	Streamable HTTP	推奨
https://code-sentinel-mcp.sharara.dev/sse	Server-Sent Events	レガシーサポート
https://code-sentinel-mcp.sharara.dev/	HTTP GET	ヘルスチェック／サーバー情報

Cloudflare でのセルフホスト

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

cd cloudflare
npm install
npm run dev      # Local development at localhost:8787
npm run deploy   # Deploy to your Cloudflare account

必要条件：

• 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：Gang of Four パターン（Singleton、Factory、Observer）
  • code：実装イディオム（エラー処理、非同期パターン）
  • all：すべてのレベル（デフォルト）
• query（文字列、任意）：分析対象を絞り込む自然言語での質問（例：「エラー処理はどのように行われていますか？」）

戻り値： 検出されたパターン、不整合、提案、およびそのまま実行できるアクション項目を含む、LLM 向けに最適化された JSON。

analyze_design_patterns

Gang of Four（GoF）のデザインパターンに特化した分析です。OOP の構造を理解するのに最適です。

パラメーター：

• code（文字列、必須）：分析するソースコード
• filename（文字列、必須）：言語検出に使用するファイル名

戻り値： 検出されたデザインパターンと、信頼度、場所、実装の詳細。

使用例

Claude にコードを分析するよう依頼します：

Analyze this code for quality issues:

const API_KEY = "sk-abc123456789";

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

CodeSentinel は次を検出します：

• Critical（CS-SEC003）：ソースコードに OpenAI API キーがハードコードされています
• High（CS-DEC001）：空の catch ブロックがエラーを黙って握りつぶしています
• Low（CS-PH001）：実装が未完了であることを示す TODO コメント

検出カテゴリ

セキュリティ問題（CS-SEC）

ID	パターン
SEC001	ハードコードされたシークレット（API キー、トークン、パスワード）
SEC002	GitHub トークン
SEC003	OpenAI API キー
SEC004	AWS アクセスキー
SEC005-010	SQL インジェクションのパターン
SEC011-015	XSS の脆弱性
SEC016	コマンドインジェクション（eval、exec）

誤解を招くパターン（CS-DEC）

ID	パターン
DEC001-003	空の catch ブロック、またはコメントのみの catch ブロック
DEC010-012	Promise の拒否を黙って無視
DEC020-025	エラーを隠すフォールバック（
DEC030+	リンター抑制、偽の成功レスポンス

プレースホルダー（CS-PH）

ID	パターン
PH001-005	TODO/FIXME/HACK/XXX/NOTE コメント
PH010-015	Lorem ipsum、プレースホルダーテキスト
PH020-025	テスト／ダミーデータ（[email protected]、password123）
PH030+	console.log によるデバッグ、debugger ステートメント

エラーとコードの問題点（CS-ERR）

ID	パターン
ERR001-005	緩い等価比較（==）、型変換の問題
ERR010-015	null 参照のリスク
ERR020-025	非同期処理のアンチパターン
ERR030+	基数を指定しない parseInt、ループ内での配列の変更

強み（CS-STR）

ID	パターン
STR001-005	TypeScript の厳密な型付け
STR010-015	適切なエラー処理パターン
STR020-025	テストカバレッジの指標
STR030+	ドキュメント、入力検証

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

品質スコア（0～100）は次のように計算されます：

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

重大度	減点
Critical	-25 点
High	-15 点
Medium	-5 点
Low	-1 点
Strength	+2 点（ボーナス）

対応言語

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

拡張子	言語
.ts、.tsx	TypeScript
.js、.jsx	JavaScript
.py	Python
.go	Go
.rs	Rust
.java	Java
.kt	Kotlin
.swift	Swift
.cs	C#
.cpp、.c	C/C++
.php	PHP
.vue	Vue
.svelte	Svelte

CodeSentinel の拡張

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

プロジェクト構成

src/
├── patterns/
│   ├── types.ts           # Type definitions for pattern configs
│   ├── builders.ts        # Functions that generate regex from configs
│   ├── compiler.ts        # Compiles definitions to executable patterns
│   └── definitions/
│       ├── security.ts    # Security vulnerability patterns
│       ├── deceptive.ts   # Error-hiding patterns
│       ├── placeholders.ts # Incomplete code patterns
│       ├── errors.ts      # Code smell patterns
│       └── index.ts       # Exports all definitions
├── analyzers/
│   ├── core.ts            # Unified analyzer using compiled patterns
│   ├── security.ts        # Security analyzer (delegates to core)
│   ├── deceptive.ts       # Deceptive analyzer (delegates to core)
│   ├── placeholders.ts    # Placeholder analyzer (delegates to core)
│   ├── errors.ts          # Error analyzer (delegates to core)
│   └── strengths.ts       # Strength analyzer
└── index.ts               # MCP server entry point

新しいパターンの追加

正規表現を手動で記述する代わりに、検出する対象を定義すると、システムが正規表現を生成します：

// Old approach (manual regex)
{
  id: 'CS-DEC001',
  pattern: /catch\s*\([^)]*\)\s*\{\s*\}/g,  // Error-prone
  title: 'Empty Catch Block',
  // ...
}

// New approach (data-driven)
{
  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'
  }
}

利用可能なマッチタイプ

マッチタイプ	説明	設定例
empty_block	空の catch/finally/promise ブロック	{ type: 'empty_block', constructs: ['catch', '.catch'] }
function_call	関数／メソッドの呼び出し	{ type: 'function_call', names: ['eval', 'exec'] }
returns_only	特定の値を返す return 文	{ type: 'returns_only', values: ['null', '[]', '{}'] }
contains_text	コメント／文字列内のテキスト	{ type: 'contains_text', terms: ['TODO', 'FIXME'], context: 'comment' }
fallback_value	フォールバックパターン	{ type: 'fallback_value', operators: ['||'], values: ['[]'] }
catch_handler	catch ブロックの動作	{ type: 'catch_handler', behavior: 'empty' }
promise_catch	Promise の .catch() の動作	{ type: 'promise_catch', behavior: 'returns_silent' }
comment_marker	TODO/FIXME/HACK マーカー	{ type: 'comment_marker', markers: ['TODO', 'FIXME'] }
string_literal	文字列内のパターン	{ type: 'string_literal', patterns: ['password', 'secret'] }
secret_pattern	API キーとトークン	{ type: 'secret_pattern', kind: 'github' }
url_pattern	URL パターン	{ type: 'url_pattern', protocol: 'http', excludeLocalhost: true }
suppression_comment	リンター抑制	{ type: 'suppression_comment', tools: ['ts-ignore', 'eslint-disable'] }
type_cast	型キャスト	{ type: 'type_cast', targets: ['any'] }
comparison	比較演算子	{ type: 'comparison', operators: ['==', '!='] }
loop_pattern	ループパターン	{ type: 'loop_pattern', kind: 'while_true' }
raw_regex	複雑なパターン向けのエスケープハッチ	{ type: 'raw_regex', pattern: 'your-regex', flags: 'gi' }

手順：パターンの追加

1. カテゴリを選択 - security、deceptive、placeholder、または error
2. 定義ファイルを開く - src/patterns/definitions/<category>.ts
3. 適切なマッチタイプを使って新しいパターン定義を追加
4. ビルド - npm run build
5. テスト - MCP インスペクターを使って検出を確認

パターン定義の構造

{
  id: string;              // Unique ID: CS-<CAT><NUM> (e.g., CS-SEC001)
  title: string;           // Short description (displayed in results)
  description: string;     // Detailed explanation of the issue
  severity: Severity;      // 'critical' | 'high' | 'medium' | 'low' | 'info'
  category: Category;      // 'security' | 'deceptive' | 'placeholder' | 'error'
  suggestion?: string;     // How to fix the issue
  match: MatchConfig;      // What to detect (see match types above)
  verification?: {         // Optional: reduce false positives
    status: 'needs_verification' | 'confirmed';
    assumption?: string;
    confirmIf?: string;
    falsePositiveIf?: string;
  }
}

開発

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Test with MCP inspector
npm run inspector

コントリビューション

コントリビューションを歓迎します。以下の手順でお願いします。

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

ライセンス

MIT

リンク

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