Jinni: プロジェクトを文脈に沿って考える

Jinniは、大規模言語モデルにプロジェクトのコンテキストを効率的に提供するためのツールです。関連するプロジェクトファイルをメタデータとともに統合的に表示することで、ファイルを個別に読み込む際の制限や非効率性を解消します。

このツールの背景にある考え方は、LLM コンテキスト ウィンドウは大きく、モデルはスマートであり、プロジェクトを直接確認することで、モデルがあらゆる課題に対応できるようにするというものです。

AI ツールとの統合用の MCP (モデル コンテキスト プロトコル) サーバーと、プロジェクトのコンテキストをクリップボードにコピーして必要な場所に貼り付けることができる、手動で使用するためのコマンド ライン ユーティリティ (CLI) があります。

これらのツールは、ほとんどのユースケースですぐに使用できる最適なプロジェクト コンテキストとして何が考慮されるかについて独自の見解を持っており、次のものを自動的に除外します。

必要に応じて、.contextfiles を使用して包含/除外を完全な粒度でカスタマイズできます。これは包含を定義する点を除いて .gitignore と同様に機能します。

MCPサーバーは、必要に応じてプロジェクト全体または一部の情報を提供できます。デフォルトではプロジェクト全体が対象となりますが、モデルは特定のモジュールやマッチングパターンなどを要求することもできます。

MCP クイックスタート

Cursor / Roo / Claude デスクトップ / 選択したクライアント用の MCP サーバー構成:

システムに uv がインストールされていない場合はインストールしてください: https://docs.astral.sh/uv/getting-started/installation/

IDE をリロードすると、エージェントにコンテキスト内で読み取るように要求できるようになります。

これを特定のモジュール/パスに制限したい場合は、「テストのコンテキストを読み取る」などと尋ねてください。

カーソルを使用した動作:

カーソルユーザーへの注意

カーソルは、許可された最大値よりも大きいコンテキストを黙ってドロップする可能性があるため、大規模なプロジェクトがあり、エージェントがツール呼び出しが発生しなかったかのように動作する場合は、取り込むものを減らしてみてください（「xyz のコンテキストを読み取ります」）。

コンポーネント

1. jinni MCP サーバー:
   • Cursor、Cline、Roo、Claude Desktop などの MCP クライアントと統合します。
   • 指定されたプロジェクト ディレクトリから関連するファイル コンテンツの連結文字列を返すread_contextツールを公開します。
2. jinni CLI:
   • プロジェクト コンテキスト ダンプを手動で生成するためのコマンド ライン ツール。
   • コピー＆ペーストやファイル入力でLLMにコンテキストを供給するのに便利です。また、出力を必要な場所にパイプすることもできます。

特徴

• **効率的なコンテキスト収集:**関連するプロジェクト ファイルを 1 回の操作で読み取り、連結します。
• インテリジェント フィルタリング (Gitignore スタイルの包含):
  • .gitignore構文 ( pathspecライブラリのgitwildmatch ) に基づくシステムを使用します。
  • プロジェクトディレクトリ内に配置した.contextfilesを使用した階層的な構成をサポートします。ルールは処理対象のファイル/ディレクトリに基づいて動的に適用されます。
  • マッチング動作:パターンは、処理対象のディレクトリ（または特定のターゲットが指定されていない場合はプロジェクトルート）からの相対パスに対してマッチングされます。例えば、 src/をターゲットとしている場合、 src/.contextfiles内の!app.pyはapp.pyにマッチします。出力パスは元のプロジェクトルートからの相対パスのままです。
  • **オーバーライド：**特定のルールセットを排他的に使用する--overrides (CLI) またはrules (MCP) をサポートします。オーバーライドが有効な場合、組み込みのデフォルトルールと.contextfilesは無視されます。オーバーライドのパスマッチングは、ターゲットディレクトリからの相対パスのままです。
  • **明示的なターゲットの包含：**ターゲットとして明示的に指定されたファイルは常に包含されます（ルールチェックはバイパスされますが、バイナリ/サイズチェックはバイパスされません）。ターゲットとして明示的に指定されたディレクトリは常に含まれ、ルールの検出/マッチングは、そのターゲットディレクトリを基準として実行されます。
• カスタマイズ可能な構成 ( .contextfiles / Overrides):
  • 相対パスに適用される.gitignoreスタイルのパターンを使用して、含めるまたは除外するファイル/ディレクトリを正確に定義します。
  • !で始まるパターンは一致を否定します (除外パターン)。 (以下の設定セクションを参照してください)。
• **大きなコンテキストの処理：**含まれるファイルの合計サイズが設定可能な制限（デフォルト：100MB）を超えると、 DetailedContextSizeErrorで処理を中止します。エラーメッセージには、サイズに寄与する上位10個のファイルのリストが含まれるため、除外する候補を特定するのに役立ちます。コンテキストサイズの管理に関するガイダンスについては、トラブルシューティングのセクションをご覧ください。
• **メタデータ ヘッダー:**出力には、含まれる各ファイルのファイル パス、サイズ、変更時刻が含まれます ( list_onlyで無効にできます)。
• **エンコーディング処理:**複数の一般的なテキスト エンコーディング (UTF-8、Latin-1 など) を試みます。
• **リストのみモード:**含まれるファイルの相対パスのみを、その内容なしでリストするオプション。

使用法

MCP サーバー ( read_contextツール)

1. セットアップ: uvx経由でjinniサーバーを実行するように MCP クライアント (例: Claude Desktop のclaude_desktop_config.json ) を構成します。
2. 呼び出し: MCP クライアントを介して LLM と対話する場合、モデルはread_contextツールを呼び出すことができます。
   • **project_root （文字列、必須）:**プロジェクトのルートディレクトリへの絶対パス。ルールの検出と出力のパスはこのルートからの相対パスとなります。
   • targets （文字列のJSON配列、必須）:処理対象となるproject_root内のファイル/ディレクトリの必須リストを指定します。文字列パスのJSON配列である必要があります（例： ["path/to/file1", "path/to/dir2"] ）。パスは絶対パスまたはCWDからの相対パスで指定できます。すべてのターゲットパスはproject_root内の場所に解決される必要があります。空のリスト[]が指定された場合は、 project_root全体が処理されます。
   • rules （文字列のJSON配列、必須）：インラインフィルタリングルールの必須リスト（ .gitignoreスタイルの構文を使用、例： ["src/**/*.py", "!*.tmp"] ）。特定のルールが必要ない場合は空のリスト[]を指定してください（組み込みのデフォルトが使用されます）。空でない場合は、これらのルールのみが使用され、組み込みのデフォルトと.contextfiles無視されます。
   • list_only (ブール値、オプション): true の場合、コンテンツではなく相対ファイル パスのリストのみを返します。
   • **size_limit_mb (整数、オプション):**コンテキスト サイズの制限を MB 単位で上書きします。
   • **debug_explain (ブール値、オプション):**サーバーのデバッグ ログを有効にします。
   3. **出力:**ツールは、連結されたコンテンツ（ヘッダー付き）またはファイルリストを含む単一の文字列を返します。ヘッダー/リスト内のパスは、指定されたproject_rootからの相対パスです。コンテキストサイズエラーが発生した場合は、最大のファイルの詳細を含むDetailedContextSizeErrorが返されます。

MCPサーバー（ usageツール）

• **呼び出し:**モデルはusageツールを呼び出すことができます (引数は不要)。
• 出力: README.mdファイルの内容を文字列として返します。

(詳細なサーバー設定手順は、MCP クライアントによって異なります。通常は、Jinni サーバーを実行するようにクライアントを構成する必要があります。)

サーバーの実行:

• 推奨される方法: uvxを使用してサーバーのエントリ ポイントを直接実行します ( jinniパッケージが PyPI で公開されているか、 uvxで検索可能である必要があります)。
  uvx jinni-server [OPTIONS]
  MCP クライアント構成の例 (例: claude_desktop_config.json ):
  { "mcpServers": { "jinni": { "command": "uvx jinni-server" // Optionally constrain the server to only read within a tree (recommended for security): // "command": "uvx jinni-server --root /absolute/path/" } } }

正確な設定手順については、ご利用のMCPクライアントのドキュメントを参照してください。uv uv uvxの場合）または適切なPython環境（ python -mの場合）にアクセスできることを確認してください。 usageツールは、 jinni usage CLIコマンドに対応しています。

コマンドラインユーティリティ ( jinni CLI)

• **<PATH...> (オプション):**分析対象となるプロジェクトディレクトリまたはファイルへの1つ以上のパス。指定されていない場合は、現在のディレクトリ ( . ) がデフォルトになります。
• **-r <DIR> / --root <DIR> (オプション):**プロジェクトのルートディレクトリを指定します。指定すると、ルールの検出はここから開始され、出力パスはこのディレクトリを基準とします。省略された場合は、ルートは<PATH...>引数の共通の祖先から推測されます（'.'のみを処理する場合はCWD）。
• **--output <FILE> / -o <FILE> (オプション):**出力を標準出力に印刷する代わりに、 <FILE>に書き込みます。
• **--list-only / -l (オプション):**含めるファイルの相対パスのみをリストします。
• --overrides <FILE> (オプション): .contextfilesを検出する代わりに、 <FILE>からのルールを使用します。
• **--size-limit-mb <MB> / -s <MB> (オプション):**コンテキストの最大サイズを MB 単位で上書きします。
• **--debug-explain (オプション):**詳細な包含/除外理由を stderr とjinni_debug.logに出力します。
• **--root <DIR> / -r <DIR> (オプション):**上記を参照してください。
• **--no-copy (オプション):**標準出力に印刷するときに、出力コンテンツがシステム クリップボードに自動的にコピーされるのを防ぎます (デフォルトではコピーされます)。

インストール

pipまたはuvを使用して Jinni をインストールできます。

pip の使用:

uv の使用:

これにより、お使いの環境でjinni CLIコマンドが使用できるようになります。インストール方法に応じたMCPサーバーの起動方法については、上記の「サーバーの実行」セクションを参照してください。

プラットフォーム固有の注意事項

ウィンドウズ + WSL

Jinni v0.1.7+ は WSL パスを自動変換します。

次のいずれかをproject_root (CLI --rootまたは MCP 引数) として指定します。

ラッパー、マウント、または追加のフラグは必要ありません。Jinni は Windows 上の UNC パス ( \\wsl$\... ) を自動的に解決します。

UNCパス形式： Jinniは、WSLをサポートするすべてのWindowsバージョンとの互換性を最大限に高めるために、常に\\wsl$\<distro>\...を使用します。**ディストリビューション名の扱い：**ディストリビューション名には、スペースとほとんどの特殊文字を使用できます。完全に不正なUNC文字のみが_に置き換えられます。キャッシュ： WSLパスの参照と変換は、パフォーマンス向上のためにキャッシュされます。Jinniの実行中にWSLをインストールする場合は、新しいwslpathを取得するためにJinniを再起動してください。**オプトアウト：**環境変数JINNI_NO_WSL_TRANSLATE=1を設定すると、すべてのWSLパス変換ロジックが無効になります。

wsl+<distro> URI と絶対 POSIX パス ( /で始まる) のみが変換されます。SSH またはコンテナー リモートの場合は、その環境内で Jinni を実行します。

例

• my_project/のコンテキストをコンソールにダンプします。
  jinni ./my_project/ # Process a single directory jinni ./src ./docs/README.md # Process multiple targets jinni # Process current directory (.)
• コンテンツなしでmy_project/に含まれるファイルを一覧表示します。
  jinni -l ./my_project/ jinni --list-only ./src ./docs/README.md
• my_project/のコンテキストをcontext_dump.txtというファイルにダンプします。
  jinni -o context_dump.txt ./my_project/
• .contextfilesの代わりにcustom.rulesからのオーバーライド ルールを使用します。
  jinni --overrides custom.rules ./my_project/
• デバッグ情報を表示します:
  jinni --debug-explain ./src
• ダンプコンテキスト (出力はデフォルトで自動的にクリップボードにコピーされます):
  jinni ./my_project/
• コンテキストをダンプしますが、クリップボードにコピーしません :
  jinni --no-copy ./my_project/

構成（ .contextfilesとオーバーライド）

Jinni は.contextfiles (またはオーバーライド ファイル) を使用して、 .gitignoreスタイルのパターンに基づいて、含めるまたは除外するファイルとディレクトリを決定します。

• **コア原則:**処理中の現在のターゲット ディレクトリを基準にして、トラバーサル中にルールが動的に適用されます。
• 場所 ( .contextfiles ): .contextfilesは任意のディレクトリに配置します。ディレクトリ（初期ターゲットまたはサブディレクトリ）を処理する際、Jinni はそのディレクトリから下に向かって.contextfiles検索します。現在のターゲットディレクトリ外の親ディレクトリのルールは、そのターゲット内で処理する際には無視されます。
• **形式:**プレーンテキスト、UTF-8 エンコード、1 行につき 1 つのパターン。
• **構文:**標準の.gitignoreパターン構文 (具体的にはpathspecのgitwildmatch実装) を使用します。
  • コメント: #で始まる行は無視されます。
  • **包含パターン:**包含するファイル/ディレクトリを指定します (例: src/**/*.py 、 *.md 、 /config.yaml )。
  • 除外パターン: !で始まる行は、一致するファイルを除外する必要があることを示します (パターンを否定します)。
  • **アンカー:**先頭の/は、パターンを.contextfilesを含むディレクトリにアンカーします。
  • **ディレクトリ マッチング:**末尾の/はディレクトリのみに一致します。
  • ワイルドカード: * 、 ** 、 ?は.gitignoreと同じように機能します。
• ルール適用ロジック:
  1. ターゲットの決定: Jinni はターゲット ディレクトリ (明示的に指定されたディレクトリまたはプロジェクト ルート) を識別します。
  2. オーバーライドチェック: --overrides (CLI) またはrules (MCP) が指定されている場合、これらのルールのみが優先されます。.contextfiles .contextfiles組み込みのデフォルトはすべて無視されます。パスのマッチングはターゲットディレクトリからの相対パスで行われます。
  3. **動的コンテキスト ルール (オーバーライドなし):**ターゲット ディレクトリ内のファイルまたはサブディレクトリを処理する場合:
     • Jinni は、ターゲット ディレクトリから現在のアイテムのディレクトリまでのすべての.contextfiles検索します。
     • 検出された.contextfilesのルールを組み込みのデフォルト ルールと組み合わせます。
     • これらの結合されたルールを仕様 ( PathSpec ) にコンパイルします。
     • ターゲット ディレクトリを基準として計算された現在のファイル/サブディレクトリ パスをこの仕様と照合します。
  4. マッチング:複合ルールセット内で、アイテムの相対パスに一致する最後のパターンが、そのアイテムの運命を決定します。 !は一致を否定します。ユーザー定義のパターンに一致しない場合、組み込みのデフォルトの除外（ !.*など）に一致しない限り、アイテムは含まれます。
  5. **ターゲット処理：**明示的にターゲット指定されたファイルはルールチェックをバイパスします。明示的にターゲット指定されたディレクトリは、その内容のルール検出とマッチングのルートになります。出力パスは常に元のproject_rootからの相対パスになります。

例 ( .contextfiles )

例1: Pythonソースとルート設定を含める

my_project/.contextfilesにあります:

例2: サブディレクトリでの上書き

my_project/src/.contextfilesにあります:

発達

• デザイン詳細: DESIGN.md
• **ローカルでのサーバーの実行:**開発中 ( uv pip install -e .または同様のコマンドでインストールした後)、サーバー モジュールを直接実行できます。
  python -m jinni.server [OPTIONS]
  ローカル開発用の MCP クライアント構成の例:
  { "mcpServers": { "jinni": { // Adjust python path if needed, or ensure the correct environment is active "command": "python -m jinni.server" // Optionally constrain the server to only read within a tree (recommended for security): // "command": "python -m jinni.server --root /absolute/path/to/repo" } } }

トラブルシューティング

コンテキスト サイズ エラー ( DetailedContextSizeError )

コンテキストサイズ制限を超えたことを示すエラーが発生した場合、Jinni は対象としようとしたファイルのサイズが大きい順に 10 個のリストを表示します。これにより、除外候補を特定しやすくなります。

これを解決するには:

1. **最大サイズのファイルを確認する：**エラーメッセージに記載されているリストを確認してください。LLMのコンテキストに含まれない大きなファイル（例：データファイル、ログ、ビルド成果物、メディア）は存在しますか？
2. **除外を構成する:**不要なファイルまたはディレクトリを除外するには、 .contextfilesまたは--overrides / rulesオプションを使用します。
   • **例 ( .contextfiles ):**すべての.logファイルと特定の大きなデータ ディレクトリを除外するには:
     # Exclude all log files !*.log # Exclude a large data directory !large_data_files/
   • 詳細な構文と使用方法については、上記の構成セクションを参照してください。
3. **制限値を増やす（注意して使用してください）：**インクルードされるすべてのファイルが本当に必要な場合は、 --size-limit-mb （CLI）またはsize_limit_mb （MCP）を使用してサイズ制限を増やすことができます。LLMコンテキストウィンドウの制限と処理コストに注意してください。
4. **jinni usage / usageを使用します。**トラブルシューティング中にこれらの手順または構成の詳細を参照する必要がある場合は、 jinni usageコマンドまたはusage MCP ツールを使用します。