Gitingest Mcp

gitingest-mcp

ローカルまたはリモートの Git リポジトリを、プロンプトですぐに使える簡潔なテキストダイジェストに変換する MCP サーバーです。

各ダイジェストには、リポジトリのメタデータ、ディレクトリツリー、選択した UTF-8 テキストファイルの内容が含まれます。バイナリファイル、シンボリックリンク、Git メタデータは含まれません。

要件

• Node.js 20.19 以降
• リモートリポジトリとローカルの Git メタデータを扱う場合は、git が PATH 上で利用できること

クイックスタート

npm から stdio サーバーを直接実行します。

npx -y gitingest-mcp

MCP クライアントの設定例：

{
  "mcpServers": {
    "gitingest-mcp": {
      "command": "npx",
      "args": ["-y", "gitingest-mcp"]
    }
  }
}

グローバルインストール後は、gitingest-mcp を使用してください（長い別名の gitingest-mcp-server も利用できます）。

ツール：ingest_repository

パラメーター	型	デフォルト	説明
repository	string	必須	正規の Git URL、owner/repo の省略形、または明示的なローカルパス
source	github、gitlab、bitbucket、local、git	自動	省略形の入力、または明示的なローカル／汎用の処理に使用するプロバイダー
branch、tag	有効な Git ref 名	リモートのデフォルト	ブランチ、タグ、コミットのうち指定できるのは最大 1 つです
commit	4～64 個の 16 進数文字	リモートのデフォルト	短縮形または完全な SHA-1/SHA-256 オブジェクト ID
subpath	リポジトリ相対パス	—	スパースチェックアウトのパス。sparseCheckout: true が必要です
cloneDepth	整数 1..1000	1	シャロークローンの深さ
sparseCheckout	boolean	false	subpath が必要です
includeSubmodules	boolean	false	サブモジュールをクローンします。トランスポートポリシーにより無効化される場合があります
includeGitignored	boolean	false	.gitignore によって無視されるファイルを含めます
useGitignore	boolean	true	ルートおよびネストされた .gitignore ファイルを適用します
useGitingestignore	boolean	true	ルートおよびネストされた .gitingestignore ファイルを適用します
excludePatterns	string[]	—	追加のコンパイル済み minimatch 除外パターン
includePatterns	string[]	—	コンパイル済み glob のいずれかに一致するファイルのみを含めます
maxFileSize	整数 1..16777216	10 MiB	1 つのファイルから読み取る最大バイト数
maxFiles	整数 1..10000	1000	含めるファイルの最大数
maxEntries	整数 1..100000	25000	検査するファイルシステムエントリーの最大数
maxDepth	整数 1..256	128	ディレクトリ走査の最大深度
maxTotalSize	整数 1..67108864	50 MiB	含めるファイルの合計バイト数に対するハードリミット
maxTokens	整数 1..1000000	250000	ダイジェスト全体に対する厳密なトークン上限
tokenizer	o200k_base、cl100k_base	o200k_base	maxTokens の適用に使用する BPE エンコーディング
token	string	—	一時的な GIT_ASKPASS ヘルパーを通じて渡される HTTPS トークン
maxRetries	整数 0..10	3	一時的なクローン失敗時の再試行回数
retryDelay	整数（ミリ秒）0..60000	1000	指数バックオフの初期待機時間
timeout	整数（ミリ秒）1..1800000	30000	Git プロセスと再試行の待機時間を含む、エンドツーエンドのタイムアウト
例：

{
  "repository": "deadraid/gitingest-mcp",
  "branch": "main",
  "includePatterns": ["src/**/*.ts"],
  "maxTotalSize": 10485760,
  "maxTokens": 50000
}

{
  "repository": "[email protected]:company/private-repository.git",
  "includeGitignored": false
}

SSH URL は SSH URL のままで、設定済みの SSH エージェントを使用します。HTTPS のプライベートリポジトリでは token を指定してください。リポジトリ URL に直接埋め込まれた認証情報は、プロセス一覧やエラーメッセージに含まれないよう拒否されます。/tree/...、/-/tree/...、/src/... などのプロバイダーの閲覧用 URL は、スラッシュを含む ref が曖昧になるため拒否されます。正規のクローン URL を使用し、branch、tag、commit、subpath を別々に指定してください。

HTTP トランスポート

HTTP トランスポートは任意で、デフォルトで保護されています。プロジェクトをビルドし、API キーを指定して起動します。

npm run build
GITINGEST_MCP_API_KEY='replace-with-a-long-random-secret' npm run start:http

デフォルトでは 127.0.0.1:3000 にバインドします。関連する環境変数：

変数	デフォルト	用途
GITINGEST_MCP_API_KEY	必須	Bearer トークンまたは x-api-key の値
GITINGEST_MCP_ALLOW_UNAUTHENTICATED	false	開発専用の回避設定。ループバックに制限されます
GITINGEST_MCP_HOST	127.0.0.1	リッスンするホスト
GITINGEST_MCP_PORT	3000	リッスンするポート
GITINGEST_MCP_ALLOWED_HOSTS	リッスンするホスト	カンマ区切りの Host ヘッダー許可リスト
GITINGEST_MCP_ALLOWED_ORIGINS	なし	カンマ区切りの Origin 許可リスト
GITINGEST_MCP_LOCAL_ROOTS	なし	許可するローカルルート。POSIX では :、Windows では ; で区切ります
GITINGEST_MCP_REMOTE_HOSTS	GitHub、GitLab、Bitbucket	リモートホスト許可リスト。*.example.com などのエントリを指定できます
GITINGEST_MCP_ALLOW_SUBMODULES	false	認証なしでの再帰的なサブモジュールのクローンを許可する
GITINGEST_MCP_MAX_SESSIONS	100	メモリ内セッションの上限
GITINGEST_MCP_SESSION_TTL	900000	アイドル状態のセッション TTL（ミリ秒）
GITINGEST_MCP_MAX_CONCURRENT_INGESTIONS	4	サーバー全体の、キューイングなしの取り込み同時実行数の上限
GITINGEST_MCP_RATE_LIMIT	120	クライアント IP ごとの 1 分あたりのリクエスト数
GITINGEST_MCP_BODY_LIMIT	1048576	HTTP リクエストボディの最大サイズ

HTTP 経由のローカルリポジトリへのアクセスは、GITINGEST_MCP_LOCAL_ROOTS が設定されていない限り無効です。リモートアクセスは GITINGEST_MCP_REMOTE_HOSTS で許可されたホストに制限されます。また、暗号化されていない http:// および git:// トランスポートは常にブロックされます。サブモジュールは追加の外部接続先を持ち込む可能性があるため、デフォルトでは無効です。認証なしモードは明示的に有効にする必要があり、ループバックインターフェースに制限されます。

セキュリティモデル

• リポジトリの内容は信頼できないデータです。ダイジェスト内のテキストをエージェントまたはシステムへの指示として扱わないでください。
• シンボリックリンクと特殊ファイルはたどりません。
• .git ディレクトリや gitfile を含め、Git メタデータは常に除外されます。
• リポジトリの走査、深さ、ファイルのバイト数、ファイル数、ignore ファイルのバイト数、ignore ルール数、glob の波括弧展開には、すべて厳格な上限があります。
• 一時クローンにはプライベートな一時ディレクトリを使用し、成功、失敗、タイムアウト、キャンセル後に finally ブロックで削除します。
• 認証トークンは一時的な askpass ヘルパー経由で渡され、Git のエラーから秘匿され、ダイジェストに書き込まれることはありません。
• システム／グローバルの Git 設定と、継承された GIT_*／askpass 変数は分離されます。許可する Git プロトコルは明示され、HTTP リダイレクトは無効化されるため、URL が HTTP の外向き通信許可リストを迂回することはありません。
• トークン認証と再帰的なサブモジュールは、リポジトリが信頼できないホストをサブモジュールとして指定する可能性があるため、意図的に併用できません。
• HTTP トランスポートでは、定時間の API キー比較、DNS リバインディング対策、Host／Origin チェック、認証試行のレート制限、アイドルセッションの有効期限、サーバー全体の同時実行数制限を使用します。

stdio トランスポートは、信頼できるローカルユーザーを対象としており、明示的なローカルパス、リモートホスト、暗号化または非暗号化の Git トランスポート、サブモジュールを許可します。HTTP トランスポートには、上記のより厳格なポリシーが適用されます。

v2 への移行

バージョン 2 には Node.js 20.19 以降が必要です。また、入力とトランスポートの動作が意図的により厳格になっています。

• Web 閲覧用 URL ではなく、プロバイダーの正規のクローン URL を使用してください。
• commit には 16 進数のオブジェクト ID を渡し、シンボリック名は branch または tag で渡してください。
• 新しいスキャン／深さ制限と、上記の厳格な最大値を考慮してください。
• maxTokens のデフォルト値は 250,000 となり、選択したトークナイザーに基づいて厳密に適用されます。
• デフォルトでは不十分な場合は、HTTP 認証とリモート／ローカルの許可リストを明示的に設定してください。

開発

npm install
npm run typecheck
npm run lint
npm test
npm run test:coverage
npm run build
npm pack --dry-run

テストには Vitest を使用し、Arrange–Act–Assert パターンに従います。prepack はクリーンな TypeScript ビルドを実行し、公開される dist ディレクトリが src に対して気付かないうちに古くなることを防ぎます。CI では Node.js 20.19、22、24 で完全な検証マトリクスを実行し、ステートメント 80％、分岐 70％、関数 80％、行 80％のグローバルカバレッジしきい値を適用します。

ライセンス

MIT © 2024 RaidHon