ContextPull

ContextPull

ウェブサイト： https://mi2arun.github.io/contextpull/ · デモ · ドキュメント · MCP Registry io.github.mi2arun/contextpull

プッシュではなく、プルしましょう。ContextPull はドキュメントのフォルダーを、Claude Code がコードベースからプルするのと同じように、LLM エージェントが必要に応じて取得できる仕組みに変えます。常にコンテキストに含まれる小さなインデックスと、必要なときに正確なセクションを返す 5 つのツールです。モデルが受け取るのは、自ら要求したコンテンツだけです。

実行時の依存関係はゼロです。SQLite ファイルは 1 つです。オフラインで動作します。

ContextPull には、コンパニオンツールの ragbisect（旧 stagewise）が付属しています。これは中立的なベンチマークハーネスで、コーパスから評価セットを作成し、ContextPull を bm25、dense、ハイブリッドパイプラインと並べて評価します。名前は 2 つ、プロジェクトは 1 つ。測定対象の影響を受けずに測定できるよう、分けてあります。

ステータス

M1 から M3 まで実装済みです。ストア、取り込み、5 つの操作、CLI、適合性テストスイート、MCP サーバー、Claude Code 連携、LLM による要約、プロトコルクライアントの例、ragbisect アダプター、TypeScript リーダーとサーバーが含まれます。ロードマップをご覧ください。

測定結果

uv のドキュメント、603 セクション、221 個の自動生成質問、recall@5。docs/testing.mdより。

構成	recall@5	ms/q	モデルトークン/q
ハイブリッドプッシュ（dense + bm25）	0.964	69	0
bm25 プッシュ	0.923	5	0
プル、Claude Code（10 問のサンプル）	1.000	26,565	86,656
プル、gpt-5.4-mini（推論オフ）	0.615	16,023	10,891

優れたエージェントは毎回正しいセクションを読みます。推論を使わない小型モデルは、読むときには正しいセクションを読みます（ヒット時の NDCG は 0.96）が、質問の 38% で正解のセクションを見つけられません。プッシュ検索はクエリごとのコストがほぼゼロですが、プルには数万トークンかかります。表に両方の事実をあえて示しています。モデル自身の検索では、サンプルの 88% で正解のセクションが見つかりました。この差の大部分は、スニペットを読まずにそれをもとに回答することによるものです。より厳密なプロンプトでも結果は変わりませんでした。この表の以前の版では小型モデルの値を 0.045 としていましたが、これはベンチマークアダプターのスレッド処理のバグによるもので、docs/testing.mdで訂正しています。

試してみる

最も手早い方法は ./scripts/demo.sh です。付属のフィクスチャコーパスを取り込み、インデックス作成、検索、読み取り、grep を順に実行した後、正確な claude mcp add コマンドを表示します。./scripts/demo.sh ./your-docs を実行すると、自分のフォルダーで同じ操作を行えます。

uv tool install contextpull            # or: pip install contextpull   (PyPI: contextpull 0.2.0)
contextpull ingest ./docs              # writes .contextpull/store.sqlite
contextpull index                      # the always-in-context table of contents
contextpull search "refund window" --in policy-2025.md
contextpull read policy-2025.md#3 --context 1
contextpull grep TX-4419
contextpull neighbours specs.md#1
contextpull export-chunks > chunks.jsonl   # ragbisect-compatible sections

Claude Code で使う

claude mcp add contextpull -- uvx --from "contextpull[mcp]" contextpull serve ./docs

サーバーは ./docs を ./docs/.contextpull/store.sqlite に取り込み、インデックスを常にコンテキストに含まれるよう指示に追加し、5 つのツールを公開します。質問すると、トレースに search、続いて read が表示され、[path.md#3] の引用付きで回答が返ります。モデルに明示的に知らせたい場合は、contextpull claude-md で CLAUDE.md のスニペットを出力できます。インデックスにモデル生成の 1 行要約を含めるには、--summarizer openai:gpt-5.4-mini を追加します（ドキュメントのハッシュでキャッシュされます）。

ほかの MCP ホストでも同様に動作します。TypeScript、Go、Java のプロトコルクライアントの例は examples/clients/ を、サーバーを使わずにモデル API からツールを直接使用する例は examples/direct_api_loop.py をご覧ください。

詳細

uv sync --extra pdf                                             # PDFs: headings inferred from font size
uv run contextpull ingest ./docs --embed-model openai:text-embedding-3-small   # enables: search --mode hybrid
uv run contextpull serve ./docs --transport http --port 8765    # streamable HTTP at /mcp for a shared read-only server

ライブラリとして使う

アクセス制御やエアギャップ環境についての注意事項を含む、自社製品への組み込みについては、docs/embedding.md と examples/embed_with_acl.py をご覧ください。

from contextpull import Store, Ops

with Store.open(".contextpull/store.sqlite") as store:
    ops = Ops(store)
    print(ops.index())
    hits = ops.search("refund window", in_=["policy-2024.md", "policy-2025.md"]).hits
    for h in hits:
        print(h.id, h.heading_path, h.snippet)
    section = ops.read(hits[0].id).section

任意のモデル API 向けのツール定義は contextpull.tools.TOOLS（Anthropic 形式）と openai_tools() にあります。リポジトリのルートにある tools.json は、ほかの言語向けの同じ定義です。

仕組み

1. 取り込みでは、Markdown、テキスト、docx、xlsx、pptx を解析し、（pdf エクストラを指定した場合は）PDF も見出し、段落、表、コードに変換します。見出しを考慮してセクションに分割し、policy-2025.md#3 のような安定した ID を付与します。表やコードはブロックの途中で分割されません。長い表は行単位で分割され、各部分にヘッダーが含まれます。再取り込み時には、変更されていないファイルはスキップされます。
2. 保存には、識別子を分割せずに保持するトークナイザーを備えた FTS5 インデックス付きの SQLite ファイルを 1 つ使用します（--no-cache、UV_CACHE_DIR、TX-4419、3.12）。
3. インデックスは、トークン予算に合わせた目次です。文書ごとに 1 行で、モデルのコンテキストに渡されます。コーパスが予算に対して大きすぎる場合は、階層構造になります。
4. ツール：index、search（ID とスニペットのみ。本文は返しません）、read（原文そのまま）、grep（完全一致）、neighbours（ヘッダー行と次の条項）。

Node

sdk/typescript/ は、better-sqlite3 を使用した TypeScript 製の、ストアネイティブなリーダー兼 MCP サーバーです。同じストアファイルを開くため、クエリ時に Python は不要です。npm では contextpull として公開されています。

npx contextpull serve /path/store.sqlite                   # npm: contextpull 0.1.0
claude mcp add contextpull -- npx -y contextpull serve /path/store.sqlite

Python のリファレンス実装と同じ適合性テストスイートに合格し、MCP 経由で同一の結果を返します。取り込み処理は引き続き Python で行います（npx contextpull ingest は uvx contextpull ingest に処理を委譲します）。

Go

sdk/go/ は、ストアネイティブなリーダー兼、純粋な Go で実装された単一の静的バイナリサーバーです。cgo は不要で、共有読み取り専用デプロイ向けの構成です。

cd sdk/go && go build -o contextpull-server ./cmd/contextpull-server
./contextpull-server serve /data/store.sqlite --http 0.0.0.0:8765    # or without --http for stdio

同じ適合性テストスイートに合格し、MCP 経由で Python と同一の結果を返します。

その他の言語

ストアファイルが仕様です。docs/store-format.md にリーダーが実行すべき処理を記載し、conformance/ にはフィクスチャコーパス、そのストア、期待される結果を格納しています。どの言語の SDK も、check が合格すれば完成です。SDK の計画をご覧ください。

ドキュメント

docs/README.md から始めてください。アーキテクチャ、設計、システム設計、ツールリファレンス、評価、ロードマップ、意思決定記録を掲載しています。

隣接する ragbisect を使って測定しています。