Code Summarizer

コードサマライザー

Gemini Flash 2.0 を使用して、指定したディレクトリ内のコードファイルを要約するコマンドラインツールです。LLM ツールとの統合に対応した MCP サーバー機能も利用できます。

機能

• ディレクトリ内のコードファイルを再帰的に処理します
• .gitignore のルールに従います
• node_modules、dist などの関連性のないディレクトリをスキップします
• Gemini Flash 2.0 を使用してコードファイルを要約します
• 要約をテキストファイルに出力します
• 詳細度と要約の長さを設定できます
• Claude Desktop やその他の LLM ツールと統合するための MCP サーバー
• 他のアプリケーションに簡単に統合できるモジュール設計
• API キーを安全に管理します
• MCP サーバーのエンドポイントに認証を適用します
• LLM 呼び出しに指数バックオフを使用した再試行メカニズムを備えています
• 不正利用を防ぐためのレート制限

要件

• Node.js 18 以降

インストール

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

   git clone https://github.com/nicobailon/code-summarizer.git
   cd code-summarizer
   

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

   npm install
   

3. Google API キーを設定した .env ファイルを作成します：

   GOOGLE_API_KEY=your_api_key_here
   

4. プロジェクトをビルドします：

   npm run build
   

MCP サーバーのセットアップと統合

コードサマライザーには Model Context Protocol（MCP）サーバーが含まれており、Claude Desktop、Cursor AI、Cline などの LLM ツールからコードの要約やファイルの内容にアクセスできます。

MCP サーバーの起動

# Start the MCP server
npm start -- server

デフォルトでは、サーバーはポート 24312 で実行されます。設定で変更できます：

# Set custom MCP server port
npm start -- config set --port 8080

Claude Desktop との接続

1. code-summarizer MCP サーバーを起動します
2. Claude Desktop を開き、Claude メニューから「Settings...」をクリックします
3. 「Developer」セクションに移動します
4. ~/.claude/claude_desktop_config.json（macOS/Linux）または %USERPROFILE%\.claude\claude_desktop_config.json（Windows）に次の内容のファイルを作成します：

{
  "code-summarizer": {
    "command": "npx",
    "args": ["-y", "your-path-to-code-summarizer/bin/code-summarizer.js", "server"],
    "env": {
      "GOOGLE_API_KEY": "your_api_key_here"
    }
  }
}

5. Claude Desktop を再起動します
6. 再起動後、Claude にコードベースへのアクセスを依頼できます。例：「プロジェクト内のファイルを要約してください」

Claude Desktop でのプロンプト例：

• 「プロジェクト内の JavaScript ファイルをすべて要約してもらえますか？」
• 「コードベースの概要を教えてください。」
• 「ファイル 'src/config/config.ts' の役割を説明してください。」
• 「コード内で認証に関連する関数をすべて見つけてください。」

Cursor AI との接続

1. code-summarizer MCP サーバーを起動します
2. プロジェクトディレクトリに .cursor/mcp.json ファイルを作成します：

{
  "mcpServers": {
    "code-summarizer": {
      "transport": "sse",
      "url": "http://localhost:24312/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

3. Cursor を再起動するか、プロジェクトを再読み込みします
4. コードについて Cursor に質問します。例：「コードベースを要約してもらえますか？」

Cursor でのプロンプト例：

• 「このコードベースの構造を要約してください。」
• 「このプロジェクトの主要なコンポーネントは何ですか？」
• 「MCP サーバーの実装について詳しく説明してください。」
• 「再試行メカニズムの仕組みを教えてください。」

Cline との接続

1. code-summarizer MCP サーバーを起動します
2. Cline で、コマンドを使って MCP サーバーを追加できます：

/mcp add code-summarizer http://localhost:24312/sse

3. 次に、API キーで認証します：

/mcp config code-summarizer headers.x-api-key your_api_key_here

4. その後、Cline に code-summarizer の使用を依頼できます。例：「コードファイルを要約してください」

Cline でのプロンプト例：

• 「プロジェクト内の各ファイルの役割を教えてください。」
• 「TypeScript ファイルをすべて要約してください。」
• 「このコードベースの認証フローを説明してください。」
• 「'summarizer' ディレクトリ内の主な関数は何ですか？」

MCP 統合でできること

MCP 統合を使用すると、次のことができます：

1. ファイルの要約を取得：特定のファイルの役割について、簡潔な説明をリクエストします
2. ディレクトリを探索：コードベースの構造を確認します
3. 一括処理：複数のファイルを一度に要約します
4. 対象を絞ったクエリ：コード内の特定のパターンや機能を見つけます
5. 要約をカスタマイズ：詳細度と要約の長さを調整します
6. 設定を更新：MCP インターフェイスから設定オプションを変更します

MCP サーバーは、コードベースを構造化された形式で LLM ツールに公開します。これにより、コードのスニペットを手動で貼り付けなくても、コードを読み取り、移動し、要約できます。

MCP サーバーの統合の詳細

MCP リソース

• code://file/* - 個々のコードファイルにアクセスします
• code://directory/* - ディレクトリ内のコードファイルを一覧表示します
• summary://file/* - 指定したファイルの要約を取得します
• summary://batch/* - 複数のファイルの要約を取得します

MCP ツール

• summarize_file - オプションを指定して単一ファイルを要約します
• summarize_directory - オプションを指定してディレクトリを要約します
• set_config - 設定オプションを更新します

MCP プロンプト

• code_summary - コード要約用のプロンプトテンプレート
• directory_summary - ディレクトリ全体の要約用のプロンプトテンプレート

トラブルシューティング

よくある MCP 接続の問題

1. 接続が拒否される

   • MCP サーバーが実行中であることを確認します（npm start -- server）
   • 設定でポートが正しいことを確認します
   • 接続をブロックしているファイアウォールの問題がないか確認します

2. 認証エラー

   • ヘッダー（x-api-key）に正しい API キーを追加したことを確認します
   • API キーが有効で、正しい形式であることを確認します
   • 環境変数が正しく設定されていることを確認します

3. トランスポートエラー

   • 正しいトランスポートタイプ（SSE）が指定されていることを確認します
   • URL に正しいエンドポイント（/sse）が含まれていることを確認します
   • クライアントとサーバー間のネットワーク接続を確認します

4. 権限の問題

   • MCP サーバーがコードベースへの読み取りアクセス権を持っていることを確認します
   • 特定のファイルの要約に失敗する場合は、ファイルのアクセス権限を確認します

5. Claude Desktop が MCP サーバーを検出できない

   • claude_desktop_config.json 内のパスが正しいことを確認します
   • コマンドと引数が正しい場所を指していることを確認します
   • Claude Desktop のログで設定エラーがないか確認します

6. レート制限

   • 「リクエストが多すぎます」というエラーが表示された場合は、しばらく待ってから再試行します
   • サーバーコードのレート制限設定を調整することを検討します

その他の問題については、サーバーログを確認するか、GitHub リポジトリでイシューを作成してください。

使用方法

コマンドラインインターフェイス

# Default command (summarize)
npm start -- summarize [directory] [output-file] [options]

# Summarize code in the current directory (output to summaries.txt)
npm start -- summarize

# Summarize code with specific detail level and max length
npm start -- summarize --detail high --max-length 1000

# Show help
npm start -- --help

設定管理

# Set your API key
npm start -- config set --api-key "your-api-key" 

# Set default detail level and max length
npm start -- config set --detail-level high --max-length 1000

# Set MCP server port (default: 24312)
npm start -- config set --port 8080

# Show current configuration
npm start -- config show

# Reset configuration to defaults
npm start -- config reset

API 認証

MCP サーバーに接続する際は、リクエストヘッダーに API キーを含める必要があります。

x-api-key: your_api_key_here

すべてのエンドポイント（/health を除く）で認証が必要です。

オプション

• --detail、-d：要約の詳細レベルを設定します。選択肢は 'low'、'medium'、'high' です。デフォルトは 'medium' です。
• --max-length、-l：各要約の最大文字数です。デフォルトは 500 です。

セキュリティ機能

API キー管理

• API キーは安全に保存され、設定ファイルより環境変数が優先されます
• 使用前にキーの形式が正しいか検証されます
• API キーがログやエラーメッセージに表示されることはありません
• 環境変数で API キーが指定されている場合、設定ファイルには保存されません

認証

• すべての MCP サーバーエンドポイント（ヘルスチェックを除く）で API キーによる認証が必要です
• 安全に送信するため、認証には x-api-key ヘッダーを使用します
• セキュリティ監視のため、認証に失敗した試行はログに記録されます

レート制限

• サービスの悪用を防ぐ組み込みのレート制限
• デフォルト：IP アドレスごとに毎分 60 リクエスト
• サーバー設定で変更可能です

エラー処理

• カテゴリ分けされた構造化エラーシステム
• エラーメッセージに機密情報が表示されることはありません
• さまざまな失敗状況に応じて適切なエラーコードが返されます

LLM 呼び出しの耐障害性

• 一時的な障害に対し、指数バックオフによる自動再試行を行います
• 最大再試行回数、遅延、バックオフ係数などの再試行設定を変更できます
• 再試行のタイミングにジッターを加え、サンダリングハード問題を防ぎます
• システム全体で問題を追跡するためのリクエスト ID トラッキング

対応ファイル形式

• TypeScript（.ts、.tsx）
• JavaScript（.js、.jsx）
• Python（.py）
• Java（.java）
• C++（.cpp）
• C（.c）
• Go（.go）
• Ruby（.rb）
• PHP（.php）
• C#（.cs）
• Swift（.swift）
• Rust（.rs）
• Kotlin（.kt）
• Scala（.scala）
• Vue（.vue）
• HTML（.html）
• CSS（.css、.scss、.less）

仕組み

1. 指定されたディレクトリを再帰的にスキャンし、.gitignore のルールを適用します。
2. 対応する拡張子に基づいてファイルをフィルタリングします。
3. 対応する各ファイルの内容を読み込み、プログラミング言語を判定します。
4. 詳細レベルと長さの制約を含むプロンプトを添えて、コードを Gemini Flash 2.0 に送信し、要約を依頼します。
5. 要約を収集し、指定された出力ファイルに書き込みます。

出力形式

出力ファイルは次の形式になります。

relative/path/to/file
Summary text here

relative/path/to/next/file
Next summary text here

プロジェクト構成

• index.ts：メインの CLI 実装
• src/：ソースコードディレクトリ
  • summarizer/：要約の中核機能
  • mcp/：MCP サーバーの実装
  • config/：設定管理
• bin/：CLI のエントリーポイント
• config.json：デフォルト設定ファイル
• tsconfig.json：TypeScript の設定
• package.json：プロジェクトの依存関係とスクリプト
• .env.example：環境変数を設定するためのテンプレート
• .gitignore：Git で無視するファイルとディレクトリ
• __tests__：単体テストと統合テスト
• __mocks__/mock-codebase：テスト用のモックコードベース

環境変数

次の環境変数を使用して、アプリケーションを設定できます。

変数	説明	デフォルト
GOOGLE_API_KEY	Google Gemini API キー	なし（必須）
PORT	MCP サーバーのポート	24312
ALLOWED_ORIGINS	許可する CORS オリジンのカンマ区切りリスト	http://localhost:3000
LOG_LEVEL	ログレベル（error、warn、info、debug）	info

テンプレートについては、.env.example を参照してください。

開発

テストの実行

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Test MCP server setup
npm run test:setup

今後の改善点

• 対応するファイル形式の拡充
• 代替 LLM プロバイダーへの対応
• GUI インターフェースを実現する Electron アプリとの統合
• MCP サーバー機能の強化
• 高度なトークン使用量の追跡
• OpenTelemetry ベースのオブザーバビリティ
• 監査ログ機能の強化
• シークレットスキャンの統合