PinRAG

PinRAG

概要

PinRAG は、何かについて学びたいのに、教材があちこちに散らばっているときに便利です。PDF や電子書籍、GitHub リポジトリ、YouTube 動画、Discord の議論、通常のメモなどの教材を、共有 RAG インデックス 1 つにまとめてインデックス化できます。その後、Cursor、VS Code（GitHub Copilot）、または MCP 対応のアシスタントから質問するだけで、ページ、タイムスタンプ、ファイル、スレッドを参照した引用付きの回答を得られます。

内部では、LangChain を使用して構築された 検索拡張生成（Retrieval-Augmented Generation）を、MCP（Model Context Protocol）サーバーとして提供します。エディターからドキュメントを追加したり、自然言語で検索したり、インデックス化した項目を一覧表示または削除したりできます。入力として、PDF、ローカルのテキストファイルやディレクトリ、Discord のエクスポートデータ、YouTube（URL、再生リスト、または ID から取得した文字起こし）、GitHub リポジトリの URL に対応しています。YouTube では、オプションでビジョンを追加し、画面上のコード、図、UI テキストを文字起こしとともに同じチャンクに統合できます。詳しくはYouTube のビジョンによる補強をご覧ください。

特長

• マルチ形式のインデックス作成 — PDF（.pdf）、ローカルファイルまたはディレクトリ、プレーンテキスト（.txt）、Discord のエクスポート（.txt）、YouTube（動画またはプレイリストの URL、または動画 ID）、GitHub リポジトリ（URL）、Web ドキュメントサイト（URL）
• YouTube のビジョン機能（任意） — デフォルトでは無効です。有効にすると、ビジョンモデル（OpenAI、Anthropic、または OpenRouter のネイティブ動画機能）を実行し、画面上の構造化されたコンテキストをトランスクリプトに統合することで、RAG チャンクに音声だけでなく、検索可能なコード名、ラベル、図を含めます。OpenRouter モードでは、ローカルでの ffmpeg の実行や動画のダウンロードは不要です。openai／anthropic ではシーンのキーフレームを使用し、pinrag[vision] と ffmpeg が必要です（YouTube ビジョンによる拡充を参照）
• 引用付き RAG — 回答では出典のコンテキストを引用します。PDF のページ、YouTube のタイムスタンプ、プレーンテキストおよび Discord のドキュメント名、GitHub リポジトリのチャンクインデックス、Web ドキュメントの出典 URL が含まれます
• ドキュメントタグ — インデックス作成時にドキュメントにタグを付けて、検索対象を絞り込めます（例：AMIGA、PI_PICO）
• メタデータによるフィルタリング — query_tool は document_id、tag、document_type、PDF の page_min／page_max、response_style（詳細または簡潔）に対応しています
• MCP ツール — add_document_tool、query_tool、list_documents_tool、remove_document_tool、set_document_tag_tool、list_collections_tool。ツールで任意の collection を指定すると、その呼び出しでは PINRAG_COLLECTION_NAME が上書きされます
• MCP リソース — pinrag://documents（インデックス済みドキュメント）と pinrag://server-config（環境変数と設定）。Cursor の MCP パネルでクリックすると表示できます
• MCP プロンプト — use_pinrag（パラメーター：request）。ドキュメントの検索、インデックス作成、一覧表示、削除に使用します
• LLM の設定 — OpenRouter（デフォルト。無料の openrouter/free ルーター）、OpenAI、Anthropic、または Cerebras Inference（OpenAI 互換 API）に対応しています。MCP の env またはシェルで PINRAG_LLM_PROVIDER と PINRAG_LLM_MODEL を設定します
• ローカル埋め込み — Nomic（PINRAG_EMBEDDING_MODEL、デフォルトは nomic-embed-text-v1.5）。API キーは不要です。初回実行時にモデルの重み（約 270 MB）がダウンロードされ、キャッシュされます
• 検索とチャンク分割のオプション — 構造を考慮したチャンク分割（デフォルトで有効）。FlashRank による再ランキング、複数クエリへの拡張、PDF の親子チャンクを任意で利用できます（「設定」を参照）
• オブザーバビリティ — MCP ツールの通知（ctx.log）と、任意で利用できる LangSmith のトレース
• 使用技術 — LangChain、Chroma。OpenRouter、OpenAI、Anthropic、FlashRank は任意で利用できます

インストール

エディターに PinRAG を MCP サーバーとして追加します。uv をインストールし、uvx が PATH 上にあることを確認してください。これにより、事前に pip install しなくても PyPI から PinRAG を実行できます。

Cursor： ~/.cursor/mcp.json の mcpServers の下に次の内容を追加します。

{
  "mcpServers": {
    "pinrag": {
      "command": "uvx",
      "args": ["--refresh", "pinrag"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here",
        "PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
      }
    }
  }
}

VS Code（GitHub Copilot）： コマンドパレットから MCP: Open User Configuration を実行するか、ワークスペースに .vscode/mcp.json を追加して、次の形式を統合します。最上位のキーは servers です。

{
  "servers": {
    "pinrag": {
      "command": "uvx",
      "args": ["--refresh", "pinrag"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here",
        "PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
      }
    }
  }
}

クイックスタート

HTTP サーバーモード

MCP over HTTP に対応したクライアント（例：--server を指定した pinrag-cli）の場合は、次を実行します。

pinrag server [--host 127.0.0.1] [--port 8765]

これにより、http://<host>:<port>/mcp で ストリーミング可能な HTTP MCP エンドポイントが起動します。エディター向けのデフォルトの pinrag stdio コマンドに変更はありません。pinrag server は追加機能です。--server http://127.0.0.1:8765/mcp を指定して pinrag-cli を接続します。

MCP サーバーの設定

API キーと PinRAG の設定は、MCP エントリの env ブロックに記述します。エディターから起動されたサーバーは .env ファイルを読み込みません。

チャットでの使用

操作	ツール
ファイル、ディレクトリ、URLをインデックス化する	add_document_tool — 必須の paths：ローカルパス（PDF、プレーンテキストまたは DiscordChatExporter の .txt、ディレクトリ）または URL（YouTube 動画、プレイリスト URL、GitHub リポジトリ、ウェブドキュメントサイト。YouTube 動画 ID のみでも指定できます）のリスト。任意の tags（パスごとに1つ）。GitHub URL の場合のみ：branch、include_patterns、exclude_patterns。
インデックス化済みドキュメントを一覧表示する	list_documents_tool — documents（ID）、total_chunks、および任意の tag フィルターを返します。document_details には、メタデータに含まれている場合、document_type、タグ、ページ数／メッセージ数／セグメント数、タイトル、集計された bytes、upload_timestamp が含まれることがあります。
フィルターを使ってクエリする	query_tool — 必須の query。任意の document_id、tag、document_type、page_min ／ page_max（PDF の範囲）、response_style（thorough または concise。PINRAG_RESPONSE_STYLE の値を使う場合は空欄のままにします）。
ドキュメントを削除する	remove_document_tool — 必須の document_id（list_documents_tool で取得した正確な値）。
リソースを表示する（読み取り専用）	MCP パネルで Resources を開き、pinrag://documents（インデックス化済みドキュメント）または pinrag://server-config（PINRAG_VERSION を含む有効な設定）を選択します。

チャットで、「/path/to/amiga-book.pdf をタグ AMIGA で追加して」、「https://youtu.be/xyz をインデックス化して、何が書かれているか尋ねて」、「https://github.com/owner/repo をインデックス化して、コードベースについて尋ねて」、または 「https://docs.langchain.com/ をインデックス化して、そのメモリ API を要約して」 と依頼してください。AI がツールを呼び出します。引用には、PDF のページ番号、YouTube のタイムスタンプ（例：t. 1:23）、プレーンテキストおよび Discord エクスポートのドキュメント名、GitHub のチャンクインデックスラベル、ウェブドキュメントのソース URL が表示されます。

GitHub のインデックス化

add_document_tool と、paths 内の URL を使ってリポジトリをインデックス化します。例：https://github.com/owner/repo、https://github.com/owner/repo/tree/branch、または github.com/owner/repo（スキームは省略可能）。

GitHub 専用オプション： branch、include_patterns ／ exclude_patterns — デフォルトでは一般的なテキストファイルとソースファイルが優先され、容量の大きなアーティファクトは除外されます。対象外のファイルが必要な場合はパターンを使用してください。PINRAG_GITHUB_MAX_FILE_BYTES（デフォルトは 512 KiB）を超えるファイルはスキップされます。

認証： プライベートリポジトリの場合、または大規模なインデックスでレート制限を受けにくくする場合は、MCP の env（またはシェル）で GITHUB_TOKEN を設定してください。小規模な公開リポジトリの処理では、設定なしで利用できることがよくあります。リポジトリの読み取りアクセス権を持つクラシックまたはファインスコープ PAT を使用してください。PinRAG には OAuth はありません。

Web ドキュメントのインデックス作成

add_document_tool に任意のドキュメントサイトの URL を指定します。例：https://docs.langchain.com/、https://docs.crewai.com/、https://picocomputer.github.io/。PinRAG は、llms.txt／llms-full.txt（Mintlify 形式）、sitemap.xml（robots.txt の Sitemap: ヒントおよびネストされたサイトマップインデックスを含む）、その後、シード URL からのスコープ付き BFS クロールの順にページを検出します。

スコープ： ホストが完全一致するページ（サブドメインは対象外）と、シードから導出されるパスプレフィックスが対象です。たとえば、https://docs.example.com/guide/ の場合、/guide/ 配下のページのみがインデックスされます。ドキュメントツリー全体を取得するには、サイトのルート URL を使用してください。

抽出： text/markdown のレスポンス（llms.txt の高速パスからのもの）はそのまま処理されます。HTML は trafilatura で処理され、失敗した場合は <main>／<article>／[role=main] を対象にする BeautifulSoup と markdownify のフォールバックが実行されます。

制限と配慮： PINRAG_WEB_MAX_PAGES（デフォルト 200）、PINRAG_WEB_MAX_DEPTH（5）、PINRAG_WEB_MAX_PAGE_BYTES（1 MiB）、PINRAG_WEB_CONCURRENCY（4）、PINRAG_WEB_RATE_LIMIT_PER_HOST（2.0/秒）、PINRAG_WEB_RESPECT_ROBOTS（true）で制御されます。Cloudflare で保護されたページなど、一部のサイトでは Python のみのクライアントに 403 が返される場合があります。これは既知の制限です。

引用： Web のチャンクには source_url メタデータフィールドが含まれます。回答ではページごとの URL が引用されます。また、document_id は <host><path_prefix> となるため、remove_document_tool／set_document_tag_tool はサイト全体に対して一度に動作します。

YouTube のインデックス作成と IP ブロック

特にクラウド環境や大量のリクエストを送信する IP から、トランスクリプトを大量に取得してインデックスを作成すると、"YouTube is blocking requests from your IP" のようなエラーが返される場合があります。MCP の env（またはシェル）を使用して、youtube-transcript-api にプロキシを指定してください。

PINRAG_YT_PROXY_HTTP_URL=http://user:[email protected]:80
PINRAG_YT_PROXY_HTTPS_URL=http://user:[email protected]:80

PINRAG_YT_PROXY_* はトランスクリプトの取得にのみ適用されます。yt-dlp の処理（タイトル、プレイリスト）では使用されません。通常、住宅用プロキシやローテーションプロキシのほうが、データセンターの IP を直接使用するより良好な結果が得られます。

一部の処理に失敗した場合（例：プレイリスト内の一部の動画）、add_document_tool は blocked、disabled、missing_transcript、other をキーとする件数を含む fail_summary を返します。

YouTube のビジョンによるエンリッチメント（オプション）

デフォルトのインデックス作成では、トランスクリプトのみを使用します。PINRAG_YT_VISION_ENABLED=true を設定すると、画面上のコンテンツに対するビジョンキャプションが追加され、トランスクリプトに時刻が対応付けられます。チャンクには has_visual、frame_count、visual_source などのメタデータが含まれます。

PINRAG_YT_VISION_PROVIDER：

• openai（デフォルト）または anthropic：yt-dlp によるダウンロード → シーンに基づくフレーム抽出 → フレームごとに1 回のマルチモーダル呼び出し。pinrag[vision]、PATH 上の ffmpeg／ffprobe、および OPENAI_API_KEY または ANTHROPIC_API_KEY が必要です（追加機能は pinrag と同じ環境にインストールしてください。例：uv sync --extra vision または pip install 'pinrag[vision]'）。
• openrouter：動画ごとに video_url を使用して、OpenRouter に1 回リクエストします（デフォルトは google/gemini-2.5-flash）。必要なのは OPENROUTER_API_KEY のみです。ダウンロード、ffmpeg、pinrag[vision] は不要です。PINRAG_YT_VISION_MODEL を上書きする場合は、動画に対応したモデルを選択してください。

運用： ビジョン設定を変更した後は、インデックスを再作成してください。openai／anthropic では、PINRAG_YT_VISION_MAX_FRAMES と、必要に応じて PINRAG_YT_VISION_IMAGE_DETAIL=high（小さい文字が読みやすくなりますが、トークン数は増加します）でコストとタイムアウトを調整してください。MCP stdio： yt-dlp の進捗は stderr に出力されるため、stdout は JSON のみになります。動画のダウンロードは YouTube の利用規約や現地の規則に違反する可能性があります。利用者の判断で行ってください。Docker： ffmpeg と pinrag[vision] を含めるには、BUILD_WITH_VISION=1 を指定してビルドしてください（Dockerfile を参照）。

ヒント

• pinrag が見つからない場合： MCP はログイン時の PATH を引き継ぎます。pipx または uv tool install の実行後にエディターを再起動し、which pinrag で確認してください。
• PINRAG_PERSIST_DIR： ベクトルストアがサーバープロセスの cwd に依存しないよう、MCP の env には安定した絶対パス（例：~/.pinrag/chroma_db）を使用してください。
• FlashRank： 同じツール環境に pinrag[rerank] をインストールしてください（pipx install 'pinrag[rerank]' / uv tool install 'pinrag[rerank]'）。調整可能な項目は設定にあります。
• YouTube のビジョン機能： 環境変数と依存関係については、YouTube ビジョン機能のエンリッチメントに従ってください。ビジョン設定を変更した後は、再インデックスしてください。
• pinrag://server-config： MCP のリソース → この URI で、PINRAG_VERSION、有効な LLM／埋め込み／チャンク分割設定、および API キーの設定済み／未設定状態を確認できます。

設定

MCP リソース pinrag://server-config には PINRAG_VERSION（環境変数ではなく、パッケージのバージョン）と、以下の変数の有効な値、および設定済みの API キーが表示されます。この表を環境変数の完全なリファレンスとして使用してください。

環境変数：

変数	デフォルト	説明
LLM
プロバイダーとモデル
PINRAG_LLM_PROVIDER	openrouter	openrouter、openai、anthropic、または cerebras
PINRAG_LLM_MODEL	(プロバイダーのデフォルト)	未設定の場合：OpenRouter は openrouter/free、OpenAI は gpt-4o-mini、Anthropic は claude-haiku-4-5、Cerebras は llama3.1-8b です。任意のモデル ID で上書きできます（例：OpenRouter の anthropic/claude-sonnet-4-6、Cerebras の gpt-oss-120b）。
OpenRouter
PINRAG_OPENROUTER_MODEL_FALLBACKS	(未設定)	OpenRouter の models リストに送信する、フォールバックモデルのスラッグをカンマ区切りで指定します。プライマリ（PINRAG_LLM_MODEL）が失敗した場合（レート制限、ダウンタイムなど）、ゲートウェイは次のスラッグを試します。無料モデルを追加すると、コストをかけずに利用できます。旧エイリアス：PINRAG_LLM_MODEL_FALLBACKS。
PINRAG_OPENROUTER_SORT	(未設定)	任意の provider.sort です。price、throughput、または latency を指定します。未設定の場合、OpenRouter はデフォルトのプロバイダー選択を使用します。特定のバックエンドを固定するために PINRAG_OPENROUTER_PROVIDER_ORDER を設定する場合は、ルーティングの指定が競合しないよう、これを未設定のままにすることをおすすめします。
PINRAG_OPENROUTER_PROVIDER_ORDER	(未設定)	provider.order 用のプロバイダー名をカンマ区切りで指定します（順番に試されます）。例：PINRAG_LLM_MODEL=openai/gpt-oss-120b とともに Cerebras を指定すると、Cerebras を利用したルーティングを優先します。OpenRouter のモデルのプロバイダー一覧にある正確なラベルを使用してください。
OPENROUTER_APP_URL	https://github.com/ndjordjevic/pinrag	アプリの帰属情報（HTTP-Referer）です。サイトの URL で上書きできます（OpenRouter のアプリ帰属情報を参照）。PinRAG はこの値を OPENROUTER_HTTP_REFERER にコピーして、OpenRouter Python SDK に渡します。
OPENROUTER_APP_TITLE	PinRAG	アプリのタイトル（X-Title）です。OpenRouter ダッシュボードでの使用状況を識別するために上書きできます。PinRAG はこの値を OPENROUTER_X_OPEN_ROUTER_TITLE にコピーして、SDK に渡します。
API キー
OPENROUTER_API_KEY	(LLM、評価器、または YouTube のビジョン機能に OpenRouter を使用する場合に必須)	PINRAG_LLM_PROVIDER=openrouter、PINRAG_EVALUATOR_PROVIDER=openrouter、または YouTube のビジョン機能で PINRAG_YT_VISION_PROVIDER=openrouter の場合に必須です。
OPENAI_API_KEY	(OpenAI LLM または OpenAI の YouTube ビジョン機能に必須)	PINRAG_LLM_PROVIDER=openai の場合、または PINRAG_YT_VISION_ENABLED=true かつ PINRAG_YT_VISION_PROVIDER=openai の場合に必須です。
OPENAI_BASE_URL	(任意)	OpenAI API のベース URL を上書きします（例：ビジョン機能またはその他の OpenAI 互換呼び出しで、OPENAI_API_KEY に OpenRouter のキーを設定して https://openrouter.ai/api/v1 を指定します）。
CEREBRAS_API_KEY	(Cerebras LLM に必須)	PINRAG_LLM_PROVIDER=cerebras の場合に必須です。Cerebras クラウドコンソールでキーを取得してください。
PINRAG_CEREBRAS_BASE_URL	https://api.cerebras.ai/v1	Cerebras の OpenAI 互換ベース URL を上書きします（例：専用推論エンドポイント）。
ANTHROPIC_API_KEY	(Anthropic LLM または Anthropic の YouTube ビジョン機能に必須)	PINRAG_LLM_PROVIDER=anthropic、PINRAG_EVALUATOR_PROVIDER=anthropic、または YouTube のビジョン機能で PINRAG_YT_VISION_PROVIDER=anthropic の場合に必須です。
埋め込み
PINRAG_EMBEDDING_MODEL	nomic-embed-text-v1.5	ローカルの Nomic モデル ID（langchain-nomic 経由）です。初回実行時に重み（約 270 MB）をダウンロードし、キャッシュします。API キーは不要です。
ストレージとチャンク分割
PINRAG_PERSIST_DIR	chroma_db	Chroma ベクトルストアのディレクトリです（絶対パスを設定しない場合、デフォルトではサーバープロセスの作業ディレクトリを基準とした相対パスです。固定の場所にする場合は、例：~/.pinrag/chroma_db）。
PINRAG_CHUNK_SIZE	1000	テキストチャンクのサイズ（文字数）
PINRAG_CHUNK_OVERLAP	200	チャンクの重複部分のサイズ（文字数）
PINRAG_STRUCTURE_AWARE_CHUNKING	true	コードや表の境界に合わせた、構造を考慮したチャンク分割のヒューリスティクスを適用します
PINRAG_COLLECTION_NAME	pinrag	Chroma コレクション名です。デフォルトでは、単一の共有コレクションを使用します。
ANONYMIZED_TELEMETRY	setdefault による未設定時の値は False	Chroma のテレメトリーフラグです。PinRAG の MCP ロギング設定は os.environ.setdefault("ANONYMIZED_TELEMETRY", "False") を呼び出すため、空または未設定の場合はオプトアウトとして扱われます。Chroma のテレメトリーを有効にする場合は、env に true を設定してください。
検索
PINRAG_RETRIEVE_K	20	再ランキングが無効の場合の検索対象プールのサイズです。再ランキングが有効の場合、PINRAG_RERANK_RETRIEVE_K が未設定ならこの値が適用され、その後、結果は PINRAG_RERANK_TOP_N 件に絞られます。
親子検索
PINRAG_USE_PARENT_CHILD	false	小さなチャンクを埋め込み、より大きな親チャンクを返すには、true を設定します（PDF、GitHub、YouTube、Discord のインデックス作成に対応。通常の .txt は対象外です）。再インデックス作成が必要です。
PINRAG_PARENT_CHUNK_SIZE	2000	PINRAG_USE_PARENT_CHILD=true の場合の親チャンクのサイズ（文字数）です。
PINRAG_CHILD_CHUNK_SIZE	800	PINRAG_USE_PARENT_CHILD=true の場合の子チャンクのサイズ（文字数）です。
再ランキング
PINRAG_USE_RERANK	false	FlashRank による再ランキングを有効にするには、true を設定します。より多くのチャンクを取得し、ローカルでスコアを再計算して、上位 N 件を LLM に渡します。pip install pinrag[rerank] が必要です。API キーは不要です。
PINRAG_RERANK_RETRIEVE_K	(PINRAG_RETRIEVE_K を継承)	PINRAG_USE_RERANK=true の場合に FlashRank の前に取得するチャンク数です。未設定の場合は PINRAG_RETRIEVE_K と同じ値になります（別途固定の 20 が設定されるわけではありません）。
PINRAG_RERANK_TOP_N	10	PINRAG_USE_RERANK=true の場合に再ランキング後、LLM に渡すチャンク数です（再ランキング前に取得した件数が上限です）。
マルチクエリ
PINRAG_USE_MULTI_QUERY	false	ユーザーのクエリを LLM で別の言い回しに変換し、各バリエーションで検索して統合する（一意な結果を結合する）には、true を設定します。短いクエリや曖昧なクエリの再現率が向上します。
PINRAG_MULTI_QUERY_COUNT	4	生成する代替クエリの数です（デフォルトは 4、最大 10）。統合時の検索には元のクエリも含まれます。
応答スタイル
PINRAG_RESPONSE_STYLE	thorough	RAG 回答のスタイルです。thorough（詳細）または concise を指定します。評価ターゲットで使用され、MCP query で response_style が省略された場合のデフォルトとしても使用されます。
MCP 通知
PINRAG_VERBOSE_LOGGING	false	ツール／リソースの実行に関するフェーズごとの詳細な MCP 通知（形式の検出、トランスクリプトの読み込み、ビジョン機能のパス／ステップ、チャンクの upsert）を出力するには、true を設定します。デフォルトでは、開始／成功／エラーの簡潔なライフサイクルログが出力されます。
GitHub のインデックス作成
GITHUB_TOKEN	(任意)	GitHub API 用の個人アクセストークンです。プライベートリポジトリでは必須です。パブリックリポジトリではレート制限が緩和されます。
PINRAG_GITHUB_MAX_FILE_BYTES	524288（512 KB）	GitHub リポジトリのインデックス作成時に、このサイズを超えるファイルをスキップします。
PINRAG_GITHUB_DEFAULT_BRANCH	main	GitHub URL で指定されていない場合のデフォルトブランチです。
プレーンテキストのインデックス作成
PINRAG_PLAINTEXT_MAX_FILE_BYTES	524288（512 KB）	インデックス作成時に、このサイズを超える通常の .txt ファイルをスキップします。
Web ドキュメントのインデックス作成
PINRAG_WEB_MAX_PAGES	200	Web のインデックス作成 1 回あたりに取得するページの最大数です。
PINRAG_WEB_MAX_DEPTH	5	シード URL からの BFS クロールの最大深度です（llms.txt／サイトマップの高速処理では無視されます）。
PINRAG_WEB_MAX_PAGE_BYTES	1048576（1 MiB）	レスポンス本文がこのサイズを超えるページをスキップします。
PINRAG_WEB_REQUEST_TIMEOUT	20	リクエストごとの HTTP タイムアウト（秒）です（接続＋読み取り）。
PINRAG_WEB_CONCURRENCY	4	ホストごとの同時取得数の上限です。
PINRAG_WEB_RATE_LIMIT_PER_HOST	2.0	ホストごとのトークンバケット補充レート（リクエスト／秒）です。
PINRAG_WEB_USER_AGENT	PinRAGBot/<version> (+https://github.com/ndjordjevic/pinrag)	Web のインデックス作成に使用する HTTP User-Agent ヘッダーです。一部のサイトでは汎用ボットがブロックされるため、必要に応じて上書きしてください。
PINRAG_WEB_RESPECT_ROBOTS	true	クロール時に robots.txt の拒否ルールを適用するかどうかを指定します。true／false を指定します。
PINRAG_WEB_PREFER_LLMS_TXT	true	サイトマップ／BFS より先に llms.txt／llms-full.txt を試します。サイトマップまたはクロールによる検出を強制するには無効にします。
YouTube トランスクリプトプロキシ
PINRAG_YT_PROXY_HTTP_URL	(なし)	トランスクリプト取得用の HTTP プロキシ URL です（例：http://user:pass@proxy:80）。YouTube に IP をブロックされる場合に使用します。
PINRAG_YT_PROXY_HTTPS_URL	(なし)	トランスクリプト取得用の HTTPS プロキシ URL です。汎用プロキシを使用する場合は、HTTP と同じ値を指定します。
YouTube のビジョン機能（任意）
PINRAG_YT_VISION_ENABLED	false	true／1／yes／on を設定すると、YouTube の画面上の情報を補完します。openai／anthropic：pinrag[vision]、PATH 上の ffmpeg、および対応する API キーが必要です。openrouter：OPENROUTER_API_KEY のみが必要です（ネイティブの video_url パスを使用し、ローカルへのダウンロードは不要です）。
PINRAG_YT_VISION_PROVIDER	openai	openai、anthropic、または openrouter を指定します。PINRAG_LLM_PROVIDER とは独立しているため、RAG LLM とビジョン機能で異なるプロバイダーを使用できます。旧エイリアス：PINRAG_VISION_PROVIDER。
PINRAG_YT_VISION_MODEL	(プロバイダーごと)	未設定の場合：OpenAI は gpt-4o-mini、Anthropic は claude-sonnet-4-6、OpenRouter は google/gemini-2.5-flash です。ビジョン対応 ID を使用してください。旧エイリアス：PINRAG_VISION_MODEL。
PINRAG_YT_VISION_MAX_FRAMES	8	ダウンロード＋フレームのパスのみ（openai／anthropic）：シーン検出後に解析するキーフレーム数の上限です。openrouter では無視されます（単一の動画リクエストを使用）。
PINRAG_YT_VISION_MIN_SCENE_SCORE	27.0	ダウンロード＋フレームのパスのみ： PySceneDetect AdaptiveDetector のしきい値です（値が大きいほどカット数が減ります）。openrouter では無視されます。
PINRAG_YT_VISION_IMAGE_DETAIL	low	OpenAI のフレームパスのみ： image_url.detail に使用する low、high、または auto です。anthropic（フルフレーム）および openrouter（video_url）では無視されます。
LangSmith（任意）
LANGSMITH_TRACING	(無効)	LangSmith にトレースを送信するには、true を設定します。LANGSMITH_API_KEY が必要です。
LANGSMITH_API_KEY	(なし)	LangSmith の Settings → API keys から取得する API キーです。
LANGSMITH_PROJECT	(LangChain のデフォルト)	トレースのプロジェクト名です（例：pinrag）。
LANGSMITH_ENDPOINT	米国 API（暗黙のデフォルト）	EU ワークスペース： トレースを EU プロジェクトに送信するには、https://eu.api.smith.langchain.com を設定します。ブラウザーでアカウントが eu.smith.langchain.com を使用している場合は、この設定が必要です。米国リージョンのワークスペースでは省略できます（デフォルトの API ホストが使用されます）。
評価器（LLM による判定）
PINRAG_EVALUATOR_PROVIDER	openai	LLM による判定の採点を実行する LLM のプロバイダーとして、openai、anthropic、または openrouter を指定します。評価実行（LangSmith の実験）でのみ使用されます。
PINRAG_EVALUATOR_MODEL	(プロバイダーのデフォルト)	正確性の採点に使用するモデルです（例：gpt-4o、claude-sonnet-4-6、評価器のプロバイダーが OpenRouter の場合は openrouter/free）。OpenRouter では、デフォルトの無料ルーターがモデルを切り替える場合があります。採点には厳密な JSON スキーマを使用するため、安定した構造化出力が必要な場合は、openrouter.ai/models にある特定の無料スラッグを設定してください。評価器のプロバイダーが openrouter の場合、以下の OpenRouter ルーティング環境変数も採点器に適用されます。
PINRAG_EVALUATOR_MODEL_CONTEXT	(プロバイダーのデフォルト)	根拠性の採点に使用するモデルです（取得したコンテキストが大きい場合。例：gpt-4o-mini、claude-haiku-4-5、評価器のプロバイダーが OpenRouter の場合は openrouter/free）。OpenRouter については PINRAG_EVALUATOR_MODEL と同じ注意事項が適用されます。評価器のプロバイダーが OpenRouter の場合、PINRAG_OPENROUTER_MODEL_FALLBACKS、PINRAG_OPENROUTER_SORT、PINRAG_OPENROUTER_PROVIDER_ORDER が採点クライアントに適用されます。

埋め込みモデルを変更する場合の再インデックス： PINRAG_EMBEDDING_MODEL を変更するには、再インデックスが必要です。ベクトルの次元数は、インデックス作成時に使用したモデル（古いデフォルトの埋め込みモデルで作成されたインデックスを含む）と一致している必要があります。

親子構造を有効にする場合の再インデックス： PINRAG_USE_PARENT_CHILD=true を設定するには、再インデックスが必要です。新しい構造（Chroma 内の子チャンク、docstore 内の親チャンク）は、対応するドキュメント形式（通常の .txt を除く）のインデックス作成時にのみ作成されます。

YouTube のビジョン機能を切り替える場合の再インデックス： PINRAG_YT_VISION_ENABLED のオン／オフ、PINRAG_YT_VISION_PROVIDER の変更、またはビジョンモデル／PINRAG_YT_VISION_IMAGE_DETAIL／フレーム数の上限の変更を行う場合、新しい動作をチャンクに反映するには、対象の YouTube ドキュメントを再インデックスする必要があります。

モニタリングと可観測性

クエリのパフォーマンス指標（レイテンシ、処理時間、トークン使用量）の確認とデバッグには、LangSmith を使用してください。MCP の env またはシェルで LANGSMITH_TRACING=true と LANGSMITH_API_KEY を設定します。必要に応じて LANGSMITH_PROJECT も設定してください（上の表を参照）。LangSmith ワークスペースが EU リージョンにある場合（ブラウザーで eu.smith.langchain.com を使用している場合）は、LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com も必ず設定してください。設定しないと、EU デプロイ環境にトレースが表示されないことがあります。米国リージョンのアカウントではデフォルトの API ホストが使用されるため、LANGSMITH_ENDPOINT を設定する必要はありません。詳しくは notes/langsmith-setup.md を参照してください。

MCP 側のイントロスペクションを行うには、PINRAG_VERBOSE_LOGGING=true を設定して、notifications/message に詳細な処理フェーズのイベントを表示します（例：YouTube のトランスクリプトの読み込み、ビジョン機能が実行されるかどうか、チャンクのアップサートの進行状況）。

複数のプロバイダーとコレクション

Chroma のコレクションごとにベクトルの次元数は固定されており、チャンクの書き込み時に使用した PINRAG_EMBEDDING_MODEL と一致している必要があります。デフォルトの ID nomic-embed-text-v1.5 は 768 次元の Nomic モデルです。別の PINRAG_EMBEDDING_MODEL 値では次元数が異なる場合があるため、モデルのドキュメントを確認してください。

• デフォルト： PINRAG_COLLECTION_NAME のデフォルト値は pinrag です。既存のコレクションに対して PINRAG_EMBEDDING_MODEL を変更する場合は、新しいコレクションに再インデックスするか、古いコレクションを消去してください。そうしないと、埋め込みの次元数エラーにより、追加やクエリが失敗する場合があります。
• モデルごとのコレクション： インデックスごとに PINRAG_EMBEDDING_MODEL と PINRAG_COLLECTION_NAME の安定した組み合わせを使用してください（ストアを分離する場合は PINRAG_PERSIST_DIR も含めます）。コレクションにクエリするには、インデックス作成時と同じ環境変数の値を設定してください。同じソースを別の組み合わせで再度インデックスすることもできます（env を変更し、必要に応じて MCP を再起動してから、add_document_tool を実行します）。
• MCP ツール： 各ツールはデフォルトで config.get_persist_dir() と config.get_collection_name() を使用します。ツール呼び出し時に collection を指定すると、そのリクエストのコレクション名を上書きできます。list_collections_tool は、設定された永続化ディレクトリ内のコレクション名を一覧表示します（必要に応じて persist_dir で上書きできます）。

MCP リファレンス

pinrag MCP サーバー（FastMCP("PinRAG")）が提供するツール、プロンプト、読み取り専用リソースです。ツールの結果は常に _server_version を含む JSON オブジェクトです。PINRAG_VERBOSE_LOGGING=true の場合は、_verbose_log が含まれることもあります。

add_document_tool は、インデックス化された項目、失敗した項目、件数、persist_directory、collection_name を返します。また、いずれかのパスで失敗した場合は fail_summary も返します。query_tool は answer と sources を返します（各エントリーには document_id、page（PDF のページ番号。PDF 以外では多くの場合 0）、および YouTube の場合は秒単位の start が含まれることがあります）。

query_tool

自然言語で質問します。任意のフィルターを指定すると検索対象を絞り込めます（使用しない場合は "" にするか省略します）。

Parameter	Description
query	質問（必須）
document_id	このドキュメントに限定します — list_documents_tool から取得した正確な参照、一覧のタイトル、または一意の PDF ファイル名（拡張子なし）
page_min, page_max	PDF のページ範囲（両端を含みます。両方の指定が必要です。1 ページのみの場合は同じ値を 2 回指定します）
tag	このタグが付いたチャンクのみ
document_type	pdf、youtube、discord、github、plaintext、または web
response_style	thorough または concise。空（スキーマのデフォルト値）またはその他の文字列の場合は、PINRAG_RESPONSE_STYLE に基づいて決定されます（server.py を参照：環境変数を上書きするのはこの 2 つのリテラル値のみです）。

フィルターは組み合わせて使用できます。sources リストでは、PDF に page、YouTube に start（秒）が使用されます。回答には start から生成された t. M:SS 形式のラベルが表示される場合があります。GitHub の引用には、回答テキスト内でチャンクインデックス形式の p. N ラベルが使用されます。Web ドキュメントのソースには、ページごとの source_url が含まれます。

例：「OpenOCD とは何ですか？ Pico のドキュメントの 16〜17 ページのみ」 → query_tool(query="What is OpenOCD?", document_id="RP-008276-DS-1-getting-started-with-pico.pdf", page_min=16, page_max=17)。

add_document_tool

ローカルファイル（PDF、プレーンテキストまたは Discord の .txt、ディレクトリ）、YouTube（動画 URL、プレイリスト URL、または ID のみ）、GitHub URL（スキームは省略可能）、または Web ドキュメントサイト（任意の http(s) URL）をインデックス化します。paths には複数の処理対象を指定できます。1 つのパスで失敗しても、ほかの処理はロールバックされません。データは PINRAG_PERSIST_DIR ／ PINRAG_COLLECTION_NAME にのみ保存されます（これらを指定する MCP パラメーターはありません）。

Parameter	Description
paths	必須のリスト：ファイル、ディレクトリ、URL、または動画 ID
tags	任意。paths の各項目に 1 つずつ、同じ順序で指定します
branch	GitHub のみ：ブランチの上書き
include_patterns	GitHub のみ：glob 形式の包含リスト
exclude_patterns	GitHub のみ：glob 形式の除外リスト

list_documents_tool

documents、total_chunks、persist_directory、collection_name、document_details（タグ、タイトル、件数、存在する場合は集計済みの bytes、upload_timestamp など）を返します。tag が設定されている場合、total_chunks にはコレクション全体ではなく、そのタグが付いたチャンクのみがカウントされます。

Parameter	Description
tag	任意。このタグが付いたドキュメントのみ

remove_document_tool

document_id に該当するすべてのチャンクを削除します。list_documents_tool から取得した正確な参照、一覧のタイトル、または一意の PDF ファイル名（拡張子なし）を指定できます。

Parameter	Description
document_id	必須 — 正確な参照、一覧のタイトル、または一意の PDF ファイル名（拡張子なし）

set_document_tag_tool

1 つのドキュメントのインデックス済みチャンクすべてに tag を設定するか、既存のタグを置き換えます。再インデックスせずに、インデックス化後のタグの追加や修正に便利です。ドキュメントの指定方法は remove_document_tool と同じです。

Parameter	Description
document_id	必須 — 正確な参照、一覧のタイトル、または一意の PDF ファイル名（拡張子なし）
tag	必須 — 空でないタグ文字列
collection	任意の上書き値（デフォルト：PINRAG_COLLECTION_NAME）

MCP プロンプト：use_pinrag

組み込みのルーティング説明です。request が 1 行目に挿入され、続いて各ツールを使用する条件とそのパラメーターが示されます（server.py の use_pinrag と一致します）。Cursor など、MCP プロンプトを公開するクライアントで表示されます。

Parameter	Description
request	任意のユーザー目標（空でもかまいません）

MCP リソース

Resource	Description
pinrag://documents	サーバーで設定されたコレクションのプレーンテキスト一覧（format_documents_list から取得）
pinrag://server-config	有効な環境変数／設定の出力（PINRAG_VERSION、主要な運用変数、API キーの有無を含む）

テストの実行

リポジトリのルートから、開発用の追加依存関係をインストールします（例：uv sync --extra dev）。

• 高速（integrationなし）：
  uv run pytest tests/ -q -m "not integration"
pyproject.tomlでintegrationのマークが付けられたテストをすべてスキップします（ネットワーク、APIキー、オプションのアセット、MCP stdio）。sample_pdf_pathフィクスチャを使用するテストには、tests/conftest.pyでこのマーカーが自動的に付与されるため、フル実行の場合にのみdata/pdfs/内のサンプルPDFが必要です。

• 全テスト：
  uv run pytest tests/ -q

  シークレット： MCP stdioテストでは、サブプロセスの環境変数はシェルの環境変数を引き継ぎ、不足しているOPENAI_API_KEY／ANTHROPIC_API_KEYはtests/.mcp_stdio_integration.envから補完されます（tests/mcp_stdio_integration.env.exampleからコピーしてください。ファイルから読み込まれるのはこれらのキーのみです。すでに設定されている環境変数が優先されます）。PINRAG_MCP_ITEST_ENV_FILEで読み込むファイルを指定できます。マージ後、test_mcp_stdio_repo.pyではOPENAI_API_KEYが必要となり、PINRAG_LLM_PROVIDERは認証情報のチェックに合格する必要があります（例：OpenRouterを使用する場合はOPENROUTER_API_KEYを設定します）。test_mcp_stdio_pypi.pyでも有効なOpenAIキーが必要です。

  PDF／stdio： デフォルトのPDFはdata/pdfs/sample-text.pdfです（Gitには含まれていません）。PINRAG_MCP_ITEST_PDF／PINRAG_MCP_ITEST_QUERYで上書きできます。stdioテストでは、uvをPATHに設定するか、バイナリのパスをPINRAG_TEST_UVに設定する必要があります。

  PyPI MCPテスト： pypi_mcpのマーカーが付いています。-m "not pypi_mcp"またはPINRAG_MCP_ITEST_SKIP_PYPI=1でスキップできます。PINRAG_MCP_ITEST_PYPI_SPECでインストールするバージョンを固定できます（デフォルトのpinragはPyPIの最新バージョンです）。

  詳細なログを表示する場合：--log-cli-level=INFO。

data/ディレクトリはGitの追跡対象外です。data/pdfs/などをローカルで作成してください。data/内のファイルはコミットされません。

ライセンス

MIT Licenseです。全文はLICENSEにあります。