Jinni: Bring Your Project Into Context

Jinni：プロジェクトをコンテキストに取り込む

Jinni は、プロジェクトのコンテキストを大規模言語モデルに効率よく提供するツールです。関連するプロジェクトファイルをまとめて表示することで、ファイルを一つずつ読み込む際の制限や非効率を解消します。各ファイルの内容の前には、パスを示す簡単なヘッダーが付加されます。

```path=src/app.py
print("hello")

このツールの基本理念は、LLM のコンテキストウィンドウは大きく、モデルは賢いため、プロジェクトを直接見せることが、どんな依頼にもモデルが対応できるようにする最善の方法だということです。

AI ツールと連携するための MCP（Model Context Protocol）サーバーと、必要な場所に貼り付けられるよう、プロジェクトのコンテキストをクリップボードにコピーする手動利用向けのコマンドラインユーティリティ（CLI）があります。

これらのツールでは、ほとんどのユースケースですぐに使えるよう、何が関連するプロジェクトコンテキストかについて独自の判断を行い、次のものを自動的に除外します。

* バイナリファイル
* ドットファイルと隠しディレクトリ
* ログ、ビルドディレクトリ、一時ファイルなどによく使われる命名規則

必要に応じて、.contextfiles を使い、対象の包含・除外を細かくカスタマイズできます。これは包含対象を定義する点を除けば .gitignore と同様に機能します。.gitignore ファイルも自動的に尊重されますが、.contextfiles のルールが優先されます。

MCP サーバーは、希望に応じてプロジェクトの一部または全体を提供できます。デフォルトではプロジェクト全体が対象ですが、モデルに特定のモジュールや一致するパターンなどを指定して要求できます。

MCP クイックスタート

Cursor ／ Roo ／ Claude Desktop ／任意のクライアント向け MCP サーバー設定ファイル：

{
    "mcpServers": {
        "jinni": {
            "command": "uvx",
            "args": ["jinni-server"]
        }
    }
}

セキュリティ対策として、LLM が予期しない動作をした場合に備えて、サーバーが特定のディレクトリツリー内だけを読み取るよう制限できます。args リストに "--root", "/absolute/path/" を追加してください。

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

IDE を再読み込みすると、エージェントにコンテキストを読み込むよう依頼できるようになります。

特定のモジュールやパスに限定したい場合は、そのように依頼してください。たとえば、「テストのコンテキストを読み込んで」と指示します。

Cursor での使用例：

Cursor ユーザー向けの注意事項

Cursor は、許可された最大サイズを超えるコンテキストを通知なく破棄することがあります。そのため、プロジェクトの規模が大きく、ツール呼び出しが行われなかったかのようにエージェントが動作する場合は、取り込む対象を減らしてみてください（「xyz のコンテキストを読み込んで」）。

コンポーネント

1. jinni MCP サーバー：

   • Cursor、Cline、Roo、Claude Desktop などの MCP クライアントと連携します。
   • 指定したプロジェクトディレクトリから、関連ファイルの内容を連結した文字列を返す read_context ツールを公開します。

2. jinni CLI：

   • プロジェクトのコンテキストダンプを手動で生成するコマンドラインツールです。
   • コピー＆ペーストやファイル入力を使って LLM にコンテキストを渡すのに便利です。または、出力を必要な場所にパイプできます。

機能

• 効率的なコンテキスト収集： 関連するプロジェクトファイルを1回の操作で読み取り、連結します。
• インテリジェントなフィルタリング（Gitignore 形式の包含）：
  • .gitignore 構文に基づくシステム（pathspec ライブラリの gitwildmatch）を使用します。
  • プロジェクトルートから下位にある .gitignore ファイルを自動的に読み込みます。これらの除外は、.contextfiles のルールで上書きできます。
  • プロジェクト内のディレクトリに配置された .contextfiles を使用した階層型の設定に対応しています。処理中のファイル／ディレクトリに応じて、ルールが動的に適用されます。
  • マッチング動作： パターンは、処理対象の対象ディレクトリからの相対パスに対してマッチします。出力パスは、元のプロジェクトルートからの相対パスのままです。
  • ルールルートの動作： 各対象には、それぞれ独自のルールルートがあります。
    • プロジェクトルート（または CWD）内の対象では、プロジェクトルート／CWDがルールルートとして使用されます。
    • 外部の対象では、その対象自体がルールルートとして使用され、ルールセットが自己完結するようにします。
  • 上書き： --overrides（CLI）または rules（MCP）を使用して、指定したルールセットのみを適用できます。上書きが有効な場合、組み込みのデフォルトルールとすべての .contextfiles は無視されます。上書きルールのパス照合も、対象ディレクトリからの相対パスに対して行われます。
  • 明示的な対象の包含： 対象として明示的に指定されたファイルは常に含まれます（ルールチェックは回避しますが、バイナリ／サイズチェックは回避しません）。
• カスタマイズ可能な設定（.contextfiles／上書き）：
  • 相対パスに適用される .gitignore 形式のパターンを使用して、包含または除外するファイル／ディレクトリを正確に指定できます。
  • ! で始まるパターンはマッチを否定します（除外パターン）。詳細は、以下の「設定」セクションを参照してください。
• 大きなコンテキストの処理： 含まれるファイルの合計サイズが設定可能な上限（デフォルト：100MB）を超えると、DetailedContextSizeError で処理を中断します。エラーメッセージには、サイズに最も大きく寄与している上位10個のファイルの一覧が含まれるため、除外候補を特定できます。コンテキストサイズの管理方法については、「トラブルシューティング」セクションを参照してください。
• メタデータヘッダー： 出力には、各対象ファイルのパスヘッダー（例：````path=src/app.py）が含まれます。list_only` で無効にできます。
• エンコーディング処理： 複数の一般的なテキストエンコーディング（UTF-8、Latin-1 など）を試します。
• 一覧のみモード： ファイルの内容を含めず、含まれるファイルの相対パスのみを一覧表示できます。

使用方法

MCP サーバー（read_context ツール）

1. セットアップ： MCP クライアント（例：Claude Desktop の claude_desktop_config.json）を設定し、uvx 経由で jinni サーバーを実行します。
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（ブール値、任意）： サーバーのデバッグログを有効にします。
   • exclusions（オブジェクト、任意）： 除外設定です。次の 3 つのフィールドを任意で指定できます。
     • global（文字列の配列）：全体で除外するキーワード（例：["tests", "deprecated"]）
     • scoped（オブジェクト）：対象を限定した除外用に、パスとキーワード配列を対応付けます（例：{"src/legacy": ["old", "deprecated"]}）
     • patterns（文字列の配列）：除外するファイルパターン（例：["*.test.js", "*_old.*"]）
   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",
        "args": ["jinni-server"]
      }
    }
  }
  

LLM が予期しない動作をした場合に備え、セキュリティ上の理由からサーバーが特定のディレクトリツリー内のみを読み取るように制限できます。args リストに "--root", "/absolute/path/" を追加してください。

正確なセットアップ手順については、お使いの MCP クライアントのドキュメントを参照してください。uv がインストールされていることを確認してください

コマンドラインユーティリティ（jinni CLI）

jinni [OPTIONS] [<PATH...>]

• <PATH...>（任意）： 解析するプロジェクトのディレクトリまたはファイルのパスを1つ以上指定します。指定がない場合は、現在のディレクトリ（.）が既定で使用されます。
• -r <DIR> / --root <DIR>（任意）： プロジェクトのルートディレクトリを指定します。指定すると、ここからルールの検索が始まり、出力パスはこのディレクトリからの相対パスになります。省略した場合、ルートは<PATH...>引数の共通の祖先（.のみを処理する場合はCWD）から推定されます。
• --output <FILE> / -o <FILE>（任意）： 出力を標準出力に表示する代わりに、<FILE>に書き込みます。
• --list-only / -l（任意）： 対象に含まれるファイルの相対パスのみを一覧表示します。
• --overrides <FILE>（任意）： .contextfilesと.gitignoreに加えて、<FILE>のルールを優先度の高いルールとして追加します。
• --size-limit-mb <MB> / -s <MB>（任意）： コンテキストの最大サイズ（MB）を上書きします。
• --debug-explain（任意）： 対象に含める／除外する理由の詳細を標準エラー出力とjinni_debug.logに表示します。
• --root <DIR> / -r <DIR>（任意）： 上記を参照してください。
• --no-copy（任意）： 標準出力に出力する際、内容がシステムのクリップボードに自動的にコピーされないようにします（既定ではコピーされます）。
• --not <keyword>（任意、繰り返し指定可能）： キーワードに一致するモジュール／ディレクトリを除外します（例：--not tests --not vendor）。複数回指定できます。
• --not-in <path:keywords>（任意、繰り返し指定可能）： パス内の特定のキーワードを除外します（例：--not-in src/legacy:old,deprecated）。複数回指定できます。
• --not-files <pattern>（任意、繰り返し指定可能）： パターンに一致するファイルを除外します（例：--not-files '*.test.js' --not-files '*_old.*'）。複数回指定できます。
• --keep-only <modules>（任意）： 指定したモジュール／ディレクトリのみを残し、それ以外はすべて除外します（カンマ区切り、例：--keep-only src,lib,docs）。

除外の例

CLI の例：

# Exclude all test directories
jinni --not tests

# Exclude multiple keywords
jinni --not tests --not vendor --not deprecated

# Exclude old code only in specific paths
jinni --not-in src/legacy:old,deprecated --not-in lib/v1:legacy

# Exclude specific file patterns
jinni --not-files "*.test.js" --not-files "*_old.*"

# Keep only src and docs, exclude everything else
jinni --keep-only src,docs

# Combine different exclusion types
jinni --not tests --not-in src/experimental:wip --not-files "*.bak"

注： 除外コマンド（--not*フラグ）は、既存の.gitignoreおよび.contextfilesのルールに加えて適用されます。これにより、それ以外の場合に対象となるファイルをさらに絞り込みます。

MCP の例：

{
  "project_root": "/path/to/project",
  "targets": [],
  "rules": [],
  "exclusions": {
    "global": ["tests", "vendor"],
    "scoped": {
      "src/legacy": ["old", "deprecated"],
      "lib/experimental": ["wip", "unstable"]
    },
    "patterns": ["*.test.js", "*_backup.*"]
  }
}

インストール

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

pipを使用する場合：

pip install jinni

uvを使用する場合：

uv pip install jinni

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

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

Windows + WSL

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

project_root として、以下のいずれかを指定します（CLI の --root または MCP の引数）：

/home/user/project
vscode-remote://wsl+Ubuntu-22.04/home/user/project

ラッパー、マウント、追加のフラグは不要です。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 を実行してください。

ランタイム OS	渡す値	_translate_wsl_path() の戻り値
Windows	vscode-remote://wsl%2BUbuntu/home/a/b	\\wsl$\\Ubuntu\home\a\b
Windows	/home/a/b	\\wsl$\\Ubuntu\home\a\b（wslpath 経由）
Linux/WSL	vscode-remote://wsl+Ubuntu/home/a/b	/home/a/b
Linux/WSL	/home/a/b	/home/a/b（変更なし）

例

• my_project/ のコンテキストをコンソールに出力する：

  jinni ./my_project/ # 単一のディレクトリを処理
  jinni ./src ./docs/README.md # 複数の対象を処理
  jinni # 現在のディレクトリ（.）を処理
  

• 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 は、.gitignore 形式のパターンに基づいて、含めるファイルやディレクトリ、除外するファイルやディレクトリを判定するために、.contextfiles（またはオーバーライドファイル）を使用します。

• 基本原則： ルールは、処理中の現在の対象ディレクトリを基準として、走査中に動的に適用されます。
• 配置場所（.contextfiles）： .contextfiles は任意のディレクトリに配置できます。ルールの検出はルールのルート（内部対象の場合はプロジェクトのルート、外部対象の場合は対象自体）から始まり、処理中の現在のディレクトリまで下位へ進みます。
• 形式： UTF-8 エンコードのプレーンテキストで、1 行につき 1 パターンを記述します。
• 構文： 標準の .gitignore パターン構文を使用します（具体的には pathspec の gitwildmatch 実装です）。
  • コメント： # で始まる行は無視されます。
  • 包含パターン： 含めるファイルやディレクトリを指定します（例：src/**/*.py、*.md、/config.yaml）。
  • 除外パターン： ! で始まる行は、一致するファイルを除外することを示します（パターンを否定します）。
  • アンカー： 先頭の / は、パターンを .contextfiles があるディレクトリに固定します。
  • ディレクトリのマッチング： 末尾の / はディレクトリのみに一致します。
  • ワイルドカード： *、**、? は .gitignore と同様に機能します。
• ルールの適用ロジック：
  1. 対象の特定： Jinni は対象ディレクトリ（明示的に指定されたディレクトリ、またはプロジェクトのルート）を特定します。
  2. オーバーライドの確認： --overrides（CLI）または rules（MCP）が指定されている場合、それらのルールのみが使用されます。すべての .contextfiles と組み込みのデフォルトルールは無視されます。パスのマッチングは対象ディレクトリを基準に行われます。
  3. 動的コンテキストルール（オーバーライドなし）： ファイルまたはサブディレクトリを処理する際：
     • Jinni は、ルールのルートから現在の項目のディレクトリまでにあるすべての .gitignore と .contextfiles を検出します。
     • ルールは次の順序で結合されます：組み込みのデフォルトルール、.gitignore のルール、.contextfiles のルール（優先されます）。
     • 結合したルールを仕様（PathSpec）にコンパイルします。
     • 現在のファイルまたはサブディレクトリのパスを対象ディレクトリからの相対パスとして計算し、この仕様と照合します。
  4. マッチング： 結合したルールセット内で、項目の相対パスに一致する最後のパターンによって、その項目の扱いが決まります。! は一致を否定します。ユーザー定義のパターンに一致しない項目は、組み込みのデフォルト除外ルール（!.* など）に一致しない限り、含められます。
  5. 対象の処理： 明示的に対象として指定されたファイルは、ルールの確認を回避します。出力パスは常に元の project_root からの相対パスになります。

例（.contextfiles）

例 1：Python ソースとルートの設定ファイルを含める

my_project/.contextfiles に配置：

# Include all Python files in the src directory and subdirectories
src/**/*.py

# Include the main config file at the root of the project
/config.json

# Include all markdown files anywhere
*.md

# Exclude any test data directories found anywhere
!**/test_data/

例 2：サブディレクトリでのオーバーライド

my_project/src/.contextfiles に配置：

# In addition to rules inherited from parent .contextfiles...

# Include specific utility scripts in this directory
utils/*.sh

# Exclude a specific generated file within src, even if *.py is included elsewhere
!generated_parser.py

開発

• 設計の詳細： DESIGN.md

• サーバーをローカルで実行： 開発中（uv pip install -e . などでインストールした後）は、サーバーモジュールを直接実行できます：

  python -m jinni.server [OPTIONS]
  

  ローカル開発用の MCP クライアント設定例：

  {
    "mcpServers": {
      "jinni": {
        // 必要に応じて python のパスを調整するか、正しい環境が有効になっていることを確認してください
        "command": "python -m jinni.server"
        // セキュリティのため、サーバーがツリー内のみを読み取るように制限することもできます（推奨）：
        // "command": "python -m jinni.server --root /absolute/path/to/repo"
      }
    }
  }
  

トラブルシューティング

コンテキストサイズエラー（DetailedContextSizeError）

コンテキストサイズの上限を超えたことを示すエラーが発生した場合、Jinni は読み込みを試みたファイルのうち、サイズが大きい上位 10 件の一覧を表示します。この一覧を参考に、除外するファイルを特定できます。

解決方法：

1. サイズの大きいファイルを確認する： エラーメッセージに表示された一覧を確認します。LLM のコンテキストに含めるべきではない大きなファイル（データファイル、ログ、ビルド成果物、メディアなど）はありませんか？
2. 除外を設定する： .contextfiles または --overrides / rules オプションを使って、不要なファイルやディレクトリを除外します。
   • 例（.contextfiles）： すべての .log ファイルと、特定の大きなデータディレクトリを除外するには、次のようにします。

     # すべてのログファイルを除外
     !*.log
     
     # 大きなデータディレクトリを除外
     !large_data_files/
     

   • 詳しい構文と使い方については、上記の設定セクションを参照してください。
3. 上限を引き上げる（注意して使用してください）： すべてのファイルが本当に必要な場合は、--size-limit-mb（CLI）または size_limit_mb（MCP）を使ってサイズ上限を引き上げられます。LLM のコンテキストウィンドウの上限と処理コストに注意してください。
4. jinni usage / usage を使用する： トラブルシューティング中に、この手順や設定の詳細を確認する必要がある場合は、jinni usage コマンドまたは usage MCP ツールを使用してください。