MCPunk

MCPunk 🤖

LLM ツールを使用してコードをインテリジェントに検索することで、埋め込みなしでコードベースとチャットできます。

MCPunk は、会話を通してコードベースを探索し、理解することを可能にします。その仕組みは以下のとおりです。

1. ファイルを論理的なチャンク（関数、クラス、マークダウンセクション）に分割する
2. LLMにこれらのチャンクを検索およびクエリするツールを提供する
3. LLMが質問に答えるために必要な特定のコードを見つけられるようにする

埋め込みや複雑な設定は一切不要。明確で監査可能な検索機能で、操作も分かりやすく、ガイドも簡単です。Claude Desktop やその他のMCPクライアントと連携して動作します。

GitHubリポジトリ

以下の点を念頭に置いて構築

• コンテキストが重要です- LLM は優れたものになり得ますが、適切なコンテキストが提供された場合のみです。
• コンテキストは貴重です- LLMはコンテキストを必要としますが、多すぎると処理できません。これは悲劇です！MCPunkは、LLMにコンテキストヒントを提供することでLLMが関連コンテンツのみに絞り込むことを可能にするRAGです。
• 人間が関与- LLM が検討したデータとそのデータをどのように見つけたかを正確に確認できます。チャットに参加し、好きなように指示することができます。

設定

これらは Claude Desktop に関する手順ですが、MCPunk は MCP が使用されている場所であればどこでも使用できます。

1. uvをインストールする
2. 以下のスニペットをclaude_desktop_config.jsonに挿入します( 場所を含むclaude_desktop_config.jsonの詳細)
3. Claude Desktopを再起動すると、下のスクリーンショットのように、少し遅れて利用可能なツールが表示されます。
4. チャットで: 「ねえ、~/git/mcpunk プロジェクトを設定して、Python ファイルがどのようにチャンク化されるか教えてくれませんか」

( "command": "uvx",機能しない可能性があり、例えば"command": "/Users/michael/.local/bin/uvx",を使用する必要があるかもしれません)

使用例

コードベースに関する質問に答える

• **[ユーザー]**ちょっと、~/git/mcpunk リポジトリを設定してくれませんか。それから、mcpunk のユーザーが、mcpunk で設定したリポジトリ内の現在チェックアウトされているブランチの git diff を取得する方法を教えてください。
• [クロード] configure_projectを呼び出す
• [クロード] list_all_files_in_projectを呼び出す
• [クロード] find_files_by_chunk_contentを呼び出す
• [クロード] ... MCPunk で合計 21 回のツール呼び出しを行います。
• [クロード] mcpunk の git diff 機能の仕組みが分かりました。現在チェックアウトされているブランチの git diff を取得する方法をまとめます。mcpunk が設定されたリポジトリで、現在チェックアウトされているブランチの git diff を取得するには、以下の手順を実行します。
  1. まず、ユーザーはconfigure_projectツールを使用して、プロジェクトで動作するようにmcpunkを設定する必要があります。
  2. 最近チェックアウトされたブランチを確認する（何と比較するかを識別するため）
  3. 次に、現在のブランチ（HEAD）と参照ブランチの差分を取得します。これにより、現在のブランチ（HEAD）と指定した参照ブランチの差分が表示されます。refパラメータには、比較対象となるベースブランチの名前（「main」や「develop」など）を指定します。
• **[ユーザー]**素晴らしい仕事だよ！

PRレビュー

• **[ユーザー]**ねえ、~/git/mcpunk リポジトリを設定して、現在のブランチとscratch/1.5比較してもらえませんか?
• [Claude] ~/git/mcpunk をセットアップし、 scratch/1.5のdiff_with_refを呼び出します。
• **[Claude]**いくつかの変更が加えられ、主に新しいテスト ファイルtests/test_git_analysis.pyが追加されました...
• **[ユーザー]**これはコードベースの残りの部分にどのように適合するのでしょうか?
• **[クロード]**チャンクごとにファイルをリストし、チャンクをリストし、チャンクの詳細を取得するための 5 つのツール呼び出しを実行します。
• **[クロード]**なるほど。このコードはgit reflogの出力を解析して、最近チェックアウトされたブランチを追跡しているんですね。メイン関数のget_recent_branchesはリポジトリパスを受け取り、チェックアウトされた最後のN個のブランチを返します。その際に、_branches_from_reflogをヘルパーとして使い、生のreflog出力を解析しています。
• **[ユーザー]**もし急いでいて、誰かにこの作品をレビューするよう指示しなければならない場合、何を見るように指示しますか？ 作業内容の概要を具体的に教えてください。
• [クロード]
  • _branches_from_reflog のsplit("to ")[-1]脆弱に見える
  • テスト データには単純なブランチ名のみが表示されますが、スペースや特殊文字はどうなりますか?
  • example_reflog は実際の git reflog 出力を表していますか?
  • 実際の git の動作に対してテストしていますか?
• **[ユーザー]**君は最高だよ！

複数のコードベースで作業する

LLMに複数のプロジェクトを設定するよう指示するだけで、LLMはそれらのプロジェクト間を自由にクエリできます。あるプロジェクトが別のプロジェクトに依存していて、それらが異なるリポジトリにある場合に便利です。この場合、LLMはインポートを通じてこれを認識するはずです。

MCPunkとその他の背景とは

MCPunkは、ツールを提供するMCPサーバーです。

• プロジェクト（ファイルのディレクトリ）を設定します。設定すると、ファイルは論理的なチャンクに分割されます。MCPunkはコード用に構築されていますが、実際にはあらゆるドキュメント、さらには必要に応じて画像にも適用できます。
• プロジェクト内の特定のテキストを含むファイルを検索する
• 特定のテキストを含むファイル内のチャンクを検索する
• 特定のチャンクの完全な内容を表示する

これに加えて、いくつかのチャンカーが組み込まれています。最も成熟しているのは Python チャンカーです。

MCPunkは会話に使う必要はありません。例えば、CIパイプラインのコードレビューの一部として使うこともできます。まさに汎用的なRAGです。

ローミングRAGクラッシュコース

見る

• https://arcturus-labs.com/blog/2024/11/21/roaming-rag--make-*the-model*-find-the-answers/
• https://simonwillison.net/2024/Dec/6/roaming-rag/

ローミングRAGの要点は

1. コンテンツ（コードベース、PDFファイルなど）を「チャンク」に分割します。各チャンクは、関数、マークダウンドキュメントのセクション、コードファイル内のすべてのインポートなど、論理的に「小さな」項目です。
2. チャンクを検索するためのLLMツールを提供します。MCPunkは、特定のテキストを含むチャンクを含むファイルを検索し、特定のチャンクの完全な内容を一覧表示するツールを提供することでこれを実現します。

従来の「ベクトル検索」RAG と比較すると、次のようになります。

• LLM はチャンクを見つけるためにドリルダウンする必要があり、当然ながらチャンクのより広いコンテキスト（どのファイルにあるかなど）を認識しています。
• チャンクは常に一貫性を保たなければなりません。完全な関数のように。
• LLM が何を検索しているかを正確に把握でき、検索がうまくいかない場合はそれが一般的に明らかであり、改善された検索用語を提案することで LLM を支援できます。
• 正確な検索一致が必要です。MCPunk はあいまい検索を一切提供していません。

チャンク

チャンクとはファイルのサブセクションです。例えば、

• 単一のPython関数
• マークダウンセクション
• Pythonファイルからのすべてのインポート

チャンクはチャンカーによってファイルから作成され、MCPunk にはいくつかのチャンクが組み込まれています。

MCPunkでプロジェクトがセットアップされると、すべてのファイルを調べ、最初に適用可能なチャンカーを適用します。LLMはツールを使用して、(1) 特定のテキストを含むチャンクを含むファイルのクエリ、(2) 特定のファイル内のすべてのチャンクのクエリ、(3) チャンクの完全な内容の取得を行うことができます。

この基本的な基盤により、claude は、関連するファイルの広範な検索から始めて関連する領域を絞り込むことで、比較的大規模なコードベースを効果的にナビゲートできるようになります。

組み込みチャンカー:

• PythonChunker 、クラス、関数、ファイルレベルのインポート、ファイルレベルのステートメント（例：グローバル）に分割します.pyで終わるファイルに適用できます。
• VueChunker 、「テンプレート」、「スクリプト」、「スタイル」、あるいはトップレベルの<blah>....</blah>項目に分割します.vueで終わるファイルに適用可能です。
• MarkdownChunker 、見出しごとにMarkdownセクションに分割します.mdで終わるファイルに適用できます。
• WholeFileChunker 、ファイル全体を単一のチャンクとして作成するフォールバックチャンカーです。任意のファイルに適用できます。

10,000 文字を超えるチャンク (設定可能) は、自動的に複数のチャンクに分割され、名前にpart1 、 part2などの接尾辞が付きます。これにより、コンテキストが無視されることを防ぎながら、チャンクの適切なナビゲーションが可能になります。

カスタムチャンカー

ファイルの種類（例：PythonとC）ごとにカスタムチャンカーが必要です。MCPunkには組み込みのチャンカーが付属しています。特定のチャンカーがファイルに一致しない場合は、ファイル全体を1つのチャンクにまとめるデフォルトのチャンカーが使用されます。

現在推奨されているチャンク追加方法は、このプロジェクトをフォークしてチャンクを追加し、開発ごとにMCPunkを実行することです。チャンカーを追加するには

• BaseChunkerから継承して、 file_chunkers.pyに追加します。
• file_breakdown.pyのALL_CHUNKERSに追加します。

pytest のプラグイン システムのように、MCPunk が使用できるカスタム チャンカーがあることをモジュールに通知するための何らかのプラグイン システムを実装することは可能ですが、現在これを実装する予定はありません (誰かがそれをやりたい場合を除く)。

制限事項

• LLMは検索が苦手な場合があります。例えば、「dependency」を検索すると「dependencies」という用語が見つかりません。検索語を絞り込む余地があります。
• LLM は、重要なコードの特定の部分を見つけようとしますが、見つけられず、コンテキスト認識が限られていることを認識せずに続行することがあります。
• 「大規模」プロジェクトは十分にテストされていません。約1000個のPythonファイルと合計約25万行のコードで構成されるプロジェクトは問題なく動作します。プロジェクトのセットアップには約5秒かかります。コードベースのサイズが大きくなるにつれて、初期のチャンク化にかかる時間が増加し、より高度な検索が必要になる可能性があります。コードは一般的に大規模なコードベースを想定して記述されていません。すべてのデータがメモリに保存され、すべてのデータを反復処理して検索が行われるなど、基本的な最適化が求められる様々な点が見られます。
• 小規模なプロジェクトでは、すべてのコードを連結してコンテキストに組み込む方がおそらく効果的です。MCPunkは、それが現実的でない場合にのみ適しています。
• 場合によっては、LLMがチャンクを一つずつ取り出すよりも、ファイル全体を取得できるようにした方が明らかに良いでしょう。MCPunkにはそのための仕組みがありません。実際には、これが大きな問題になることはありませんでした。

構成

MCPUNK_で始まる環境変数を使って、様々な設定を行うことができます。利用可能なオプションについては、 settings.py を参照してください。これらのオプションは、 Pydantic Settingsを介して環境変数から読み込まれます。

たとえば、 include_chars_in_responseオプションを構成するには、次のようにします。

ロードマップと開発状況

MCPunkはほぼ機能が完成していると考えられています。まだ広く利用されていないため、ユーザーとしてバグや粗い部分に遭遇する可能性があります。バグ報告はhttps://github.com/jurasofish/mcpunk/issuesまで歓迎いたします。

ロードマップのアイデア

• MCPunkの使い方をサポートするプロンプトをいくつか追加してください。「エイリアンにパンケーキの作り方を説明する」といった類のプロンプトがないと、少し物足りなく感じます。
• Python モジュール レベルのステートメントを抽出するときに、モジュール レベルのコメントを含めます。
• 検索のための語幹処理の可能性あり
• 「プロジェクト」の概念全体を変更して、ファイルが実際に存在する必要がないようにします。これにより、プロジェクト内で「仮想」ファイルが許可されるようになります。
  • ファイルのパスをURIに変更することを検討してください。たとえばfile://... / http[s]:// / gitdiff:// / などの任意のURIです。
• Gitの差分をチャンク化します。現在、差分全体を取得するツールがありますが、これは非常に大きくなる可能性があります。代わりに、このツールをadd_diff_to_projectに変更し、 gitdiff:// URIまたは何らかの偽のパスの下にファイルを配置することができます。
• プロジェクトのキャッシュ。MCPクライアントを再起動するたびにすべてのファイルを再解析する必要がなくなります。チャンカー内のコードを変更するとキャッシュが無効になるため、これは難しいかもしれません。私のユースケースではそれほど遅くないので、優先順位は高くないかもしれません。
• ユーザーがチャンクを実行するためのカスタムコードを提供できる機能（おそらくpytestプラグインに似ている）
• ツリーシッターのようなものは、より一般的なチャンカーとして使用できる可能性があります
• 理想的にはチャットで送受信された文字を追跡します。
• チャットによる状態、ログなど

発達

run_mcp_server.pyを参照してください。

claude デスクトップを以下のように設定すると、リポジトリのローカル バージョンから MCPunk を操作するときに、再起動して最新の変更を確認できます。

テスト、リンティング、CI

Makefileと github アクションのワークフローを参照してください。