コードサマライザー

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 サーバーのセットアップと統合

コード サマライザーには、Claude Desktop、Cursor AI、Cline などの LLM ツールがコード サマリーとファイル コンテンツにアクセスできるようにする Model Context Protocol (MCP) サーバーが含まれています。

MCPサーバーの起動

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

Claude Desktopとの接続

1. コードサマライザーMCPサーバーを起動する
2. Claude Desktop を開き、Claude メニューをクリックして、「設定...」をクリックします。
3. 「開発者」セクションに移動します
4. ~/.claude/claude_desktop_config.json (macOS/Linux) または%USERPROFILE%\.claude\claude_desktop_config.json (Windows) に次の内容のファイルを作成します。

5. Claudeデスクトップを再起動します
6. 再起動後、Claude にコードベースにアクセスするよう依頼できます。例:「プロジェクト内のファイルを要約する」

Claude Desktop のプロンプトの例:

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

カーソルAIとの接続

1. コードサマライザーMCPサーバーを起動する
2. プロジェクト ディレクトリに.cursor/mcp.jsonファイルを作成します。

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

カーソルのプロンプトの例:

• 「このコードベースの構造を要約してください。」
• 「このプロジェクトの主要な構成要素は何ですか？」
• 「MCP サーバーの実装について詳しく教えてください。」
• 「再試行メカニズムがどのように機能するかを教えてください。」

クラインとのつながり

1. コードサマライザーMCPサーバーを起動する
2. Cline では、次のコマンドで MCP サーバーを追加できます。

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

4. 次に、Cline にコード サマライザーを使用するように依頼します。たとえば、「コード ファイルを要約してください」のように入力します。

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. 認証エラー
   • ヘッダーに正しい API キー ( x-api-key ) を追加したことを確認します。
   • APIキーが有効で、適切な形式になっていることを確認してください
   • 環境変数が正しく設定されていることを確認してください
3. トランスポートエラー
   • 正しいトランスポートタイプが指定されていることを確認する (SSE)
   • URL に正しいエンドポイント ( /sse ) が含まれていることを確認します。
   • クライアントとサーバー間のネットワーク接続を確認する
4. 権限の問題
   • MCP サーバーがコードベースへの読み取りアクセス権を持っていることを確認します。
   • 特定のファイルの要約が失敗した場合は、ファイルの権限を確認してください
5. Claude Desktop が MCP サーバーを見つけられない
   • claude_desktop_config.jsonのパスが正しいことを確認します
   • コマンドと引数が正しい場所を指していることを確認してください
   • Claude Desktop のログで構成エラーがないか確認します
6. レート制限
   • 「リクエストが多すぎます」というエラーが表示された場合は、しばらくしてからもう一度お試しください。
   • サーバーコード内のレート制限設定を調整することを検討してください

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

使用法

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

構成管理

API認証

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

すべてのエンドポイント ( /healthを除く) には認証が必要です。

オプション

• --detail , -d : サマリーの詳細レベルを設定します。オプションは「low」、「medium」、「high」です。デフォルトは「medium」です。
• --max-length , -l : 各サマリーの最大文字数。デフォルトは500です。

セキュリティ機能

APIキー管理

• APIキーは安全に保存され、設定ファイルよりも環境変数が優先されます
• キーは使用前に適切な形式かどうか検証されます
• APIキーはログやエラーメッセージで公開されることはありません
• 環境変数経由で提供された API キーは設定ファイルに保存されません

認証

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

レート制限

• レート制限が組み込まれているため、サービスの不正使用を防止できます。
• デフォルト: IP アドレスごとに 1 分あたり 60 リクエスト
• サーバー設定で構成可能

エラー処理

• 分類による構造化されたエラーシステム
• エラーメッセージでは機密情報が公開されることはありません
• さまざまな障害シナリオに対して適切なエラーコードが返されます

LLMコールレジリエンス

• 一時的な障害に対する指数バックオフによる自動再試行
• 最大再試行回数、遅延、バックオフ係数などの設定可能な再試行設定
• 雷鳴のような群れの問題を防ぐために再試行のタイミングにジッターを追加
• システム全体の問題を追跡するためのリクエストID追跡

サポートされているファイル形式

• TypeScript (.ts、.tsx)
• JavaScript (.js、.jsx)
• Python (.py)
• Java (.java)
• C++ (.cpp)
• C (.c)
• ゴー（.go）
• ルビー（.rb）
• PHP (.php)
• C# (.cs)
• スウィフト（.swift）
• Rust (.rs)
• コトリン (.kt)
• Scala (.scala)
• Vue (.vue)
• HTML (.html)
• CSS (.css、.scss、.less)

仕組み

1. ツールは、 .gitignoreルールに従って、指定されたディレクトリを再帰的にスキャンします。
2. サポートされている拡張子に基づいてファイルをフィルタリングします。
3. サポートされているファイルごとに、その内容を読み取り、プログラミング言語を決定します。
4. 詳細レベルや長さの制約を含む要約を求めるプロンプトとともに、コードを Gemini Flash 2.0 に送信します。
5. 要約が収集され、指定された出力ファイルに書き込まれます。

出力形式

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

プロジェクト構造

• 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 : テスト用のモックコードベース

環境変数

アプリケーションを構成するために、次の環境変数を使用できます。

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

発達

テストの実行

今後の改善

• より多くのファイル形式をサポート
• 代替LLMプロバイダーのサポート
• GUIインターフェースのためのElectronアプリとの統合
• 強化されたMCPサーバー機能
• 高度なトークン使用状況追跡
• OpenTelemetryベースの可観測性
• 強化された監査ログ機能
• シークレットスキャン統合