Code Explainer MCP

コード解説 MCP

ソースコードを解説する Cloudflare Worker です。コードスニペットと言語を指定すると、ASCII アーキテクチャ図、主要な機能の概要、主なクラスと関数の詳細を含む Markdown レポートを返します。

解析は正規表現とパターンマッチングを使って Worker 内で完結します。LLM の呼び出しも、外部のランタイム依存関係もありません。すべてのロジックは単一ファイル src/index.ts にあります。

機能

• アーキテクチャ図：継承関係のあるクラス、独立した関数、呼び出し関係、インポートした依存関係を示す ASCII 図を生成します。
• 主要機能の分析：重み付けしたパターンマッチングに基づいて、コードの主な目的と副次的な目的（ネットワーク、UI、データ処理、データベース、認証、テスト、アルゴリズム、ファイルシステム）を推定します。
• コンポーネントの詳細：主なクラスと関数を、それぞれ短い説明とともに一覧表示します。
• 複数言語のサポート：JavaScript、TypeScript、Python、Java、C# 向けに調整したクラス、関数、インポートのパターンを用意し、その他の言語には汎用のフォールバックを使用します。
• ドキュメントの抽出：コンポーネントの説明には、既存の JSDoc、Python の docstring、行コメントを再利用します。
• Bearer トークン認証：POST エンドポイントは共有シークレットで保護されています。

仕組み

explainCode(code, language) は 4 つのヘルパーを調整し、その出力を組み立てて Markdown レポートを作成します。

1. generateArchitectureDiagram — 言語固有の正規表現でクラス、関数、インポートを抽出し、inherits／calls の関係を含む ASCII 図を描画します。
2. extractCoreFunctionality — 目的のカテゴリごとに一致数を数え、主な目的と副次的な目的を文章で要約します。
3. extractComponents — 主なクラスと関数を収集します。extractBlock は波括弧の対応（Python の場合はインデント）によって、それぞれの宣言の本体を特定します。
4. generateComponentDescription — 各コンポーネントについて既存のドキュメントコメントを優先し、見つからない場合はコードのパターンから説明を推定します。

「MCP」に関する補足

このプロジェクトは Model Context Protocol にちなんで名付けられており、デプロイパイプラインでも workers-mcp を使用します（workers-mcp docgen は wrangler deploy の前に実行されます）。ただし、現在の src/index.ts は実行時に workers-mcp を使用せず、MCP JSON-RPC ワイヤープロトコルも実装していません。Worker のデフォルトの fetch エクスポートが直接処理する、独自の { method, params } ボディを持つ通常の HTTP JSON エンドポイントを提供します。クライアントは通常の HTTP API として呼び出します（使い方を参照）。

前提条件

• Node.js 22 以降
• Wrangler（devDependencies 経由でローカルにインストール）
• Cloudflare アカウント（デプロイ用）

セットアップ

1. リポジトリをクローンします。

   git clone https://github.com/BillDuke13/code-explainer-mcp.git
   cd code-explainer-mcp
   

2. 依存関係をインストールします。

   npm install
   

3. 共有シークレットを設定します。本番環境では、Worker シークレットとして保存することを推奨します。

   wrangler secret put SHARED_SECRET
   

   wrangler.jsonc の vars.SHARED_SECRET エントリは、プレースホルダーの "YOUR_SECRET_KEY_HERE" にすぎません。実際のシークレットをここにコミットしないでください。Worker はフェイルクローズで動作します。シークレットが未設定、またはプレースホルダーのままの場合、すべての POST リクエストに 503 を返します。そのため、エンドポイントを利用可能にするには、実際のシークレットを設定する必要があります。ローカル開発では、代わりに .dev.vars（Git で無視されます）にシークレットを記述してください。ローカル開発を参照してください。

4. Cloudflare Workers にデプロイします。

   npm run deploy
   

使い方

エンドポイント

Worker の URL に、JSON ボディを指定して POST リクエストを送信します。

{
	"method": "explainCode",
	"params": ["your code here", "programming language"]
}

Authorization ヘッダーに Bearer トークンを含めます。

Authorization: Bearer <SHARED_SECRET>

同じ URL への GET リクエストでは、解析は実行されず、簡単な HTML 情報ページが返されます。

レスポンス

成功すると、result フィールドに Markdown レポートを含む JSON オブジェクトが返されます。

{
	"result": "# Code Analysis for javascript Code\n\n## Architecture Diagram\n...\n\n## Core Functionality\n..."
}

ステータスコード

ステータス	場合	本文
200	有効な POST、または GET／HEAD	{ "result": "<markdown>" } / HTML
401	Authorization ヘッダーがない、または正しくない POST	Unauthorized
503	SHARED_SECRET が未設定、またはプレースホルダーのままの場合（Worker はフェイルクローズします）	Service not configured: …
400	method が explainCode ではない、params が2つ未満、または params が文字列ではない場合	Invalid method or parameters
413	コード（params[0]）が最大長（100,000文字）を超える場合	Code exceeds the maximum length …
405	POST、GET、HEAD 以外のリクエストメソッド	Method Not Allowed
500	リクエスト本文が有効な JSON ではない場合、またはその他のエラーが発生した場合	Error processing request

例

JavaScript（ブラウザー）

async function explainCode(code, language) {
	const response = await fetch('https://your-worker-url.workers.dev', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: 'Bearer YOUR_SECRET_KEY_HERE',
		},
		body: JSON.stringify({
			method: 'explainCode',
			params: [code, language],
		}),
	});

	if (!response.ok) {
		throw new Error(`HTTP error! status: ${response.status}`);
	}

	const data = await response.json();
	return data.result;
}

const jsCode = `function add(a, b) { return a + b; }`;
explainCode(jsCode, 'javascript')
	.then((explanation) => console.log(explanation))
	.catch((error) => console.error('Error:', error));

Python（requests）

import requests


def explain_code(code, language, api_url, secret_key):
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {secret_key}',
    }
    payload = {
        'method': 'explainCode',
        'params': [code, language],
    }
    response = requests.post(api_url, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()['result']


code = "def hello():\n    print('Hello, world!')"
explanation = explain_code(code, 'python', 'https://your-worker-url.workers.dev', 'YOUR_SECRET_KEY_HERE')
print(explanation)

Node.js（axios）

const axios = require('axios');

async function explainCode(code, language) {
	const response = await axios.post(
		'https://your-worker-url.workers.dev',
		{ method: 'explainCode', params: [code, language] },
		{
			headers: {
				'Content-Type': 'application/json',
				Authorization: 'Bearer YOUR_SECRET_KEY_HERE',
			},
		},
	);
	return response.data.result;
}

ローカル開発

1. まだインストールしていない場合は、依存関係をインストールします（npm install）。

2. ローカルのシークレットを設定します。.dev.vars ファイル（gitignore 対象）を作成し、wrangler dev でシークレットを注入できるようにします。

   SHARED_SECRET=your-local-secret
   

   Worker はフェイルクローズするため、.dev.vars には実際のシークレットを設定する必要があります。wrangler.jsonc のプレースホルダーを使っている場合（またはシークレットがない場合）、すべての POST が 503 を返します。

3. 開発サーバーを起動します（http://localhost:8787）。

   npm run dev
   

4. リクエストを送信します。

   curl -X POST http://localhost:8787 \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-local-secret" \
     -d '{"method":"explainCode","params":["function hello() { return \"Hello World\"; }","javascript"]}'
   

品質チェック

• テスト（@cloudflare/vitest-pool-workers 上の Vitest）：npm test。test/ のテストスイートは SELF.fetch 経由で Worker を実行し、GET 情報ページ、認証エラー、JavaScript と Python の explainCode コントラクト、空の入力、リクエストの検証を確認します。
• Lint（ESLint flat config）：npm run lint、または自動修正する場合は npm run lint:fix。
• 型チェック：npx tsc --noEmit で src/ をチェックします。ルートの tsconfig.json は test/ を除外しているため、テストは npx tsc -p test/tsconfig.json --noEmit で別途型チェックしてください。
• バインディング型の再生成：wrangler.jsonc のバインディングまたは vars を変更した後、npm run cf-typegen を実行して worker-configuration.d.ts を書き換えます。

フォーマットには Prettier（.prettierrc：タブ、シングルクォート、セミコロン、printWidth 140）を使用します。npx prettier --write . を実行してください。

プロジェクト構成

src/index.ts        Worker entry point and all analysis logic
test/index.spec.ts  Vitest suite exercising the HTTP contract
docs/index.html     Browsable HTML documentation
wrangler.jsonc      Worker configuration

ドキュメント

詳細な閲覧用ドキュメントは docs/index.html にあります。ブラウザーで開くと、アーキテクチャの概要、分析パイプライン、API リファレンスの全容、既知の制限事項を確認できます。

セキュリティ

• POST エンドポイントは Authorization: Bearer <SHARED_SECRET> で保護されています。
• Worker はフェイルクローズします。SHARED_SECRET にプレースホルダーではない実際の値が設定されるまで 503 を返し、設定ミスのあるデプロイでは、デフォルトの公開値でリクエストを受け付けずに拒否します。
• 本番環境では wrangler secret put SHARED_SECRET を使ってシークレットを保存し、ローカル開発では .dev.vars に保存してください。実際の値を wrangler.jsonc にコミットしないでください。
• トークンの検証では SHA-256 ダイジェストを一定時間で比較し、応答時間からシークレットの内容も長さも漏えいしないようにします。より高い保証が必要なデプロイでは、Worker の前段にレート制限を追加してください。
• リクエストサイズには上限があります。上限を超える本文は 413 で拒否され（Content-Length 経由）、100,000文字を超えるコードは分析の実行前に拒否されます。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細は LICENSE ファイルを参照してください。