ContextPull

ContextPull

网站： https://mi2arun.github.io/contextpull/ · 演示 · 文档 · MCP Registry io.github.mi2arun/contextpull

拉取，而非推送。ContextPull 可将一组文档转化为大模型 Agent 可按需拉取内容的形式，就像 Claude Code 从代码库中拉取内容一样：一个始终位于上下文中的小型索引，以及五个按需返回准确章节的工具。模型永远不会收到自己没有请求的内容。

零运行时依赖。一个 SQLite 文件。支持离线运行。

ContextPull 随附配套项目 ragbisect（原名 stagewise）：一个中立的基准测试工具，可从语料库构建评测集，并将 ContextPull 与 bm25、dense 和 hybrid 流程进行评分比较。两个名称，一个项目，彼此分开，以确保测量过程独立于被测对象。

状态

M1 到 M3 已完成：存储、导入、五项操作、CLI、一致性测试套件、MCP 服务、Claude Code 集成、大模型摘要、协议客户端示例、ragbisect 适配器，以及 TypeScript 阅读器和服务端。请参阅路线图。

测量结果

uv 文档，共 603 个章节、221 个自动生成的问题，recall@5，数据来自 docs/testing.md：

配置	recall@5	ms/q	每个问题的模型 Token 数
hybrid push（dense + bm25）	0.964	69	0
bm25 push	0.923	5	0
pull，Claude Code（10 个问题的样本）	1.000	26,565	86,656
pull，关闭推理的 gpt-5.4-mini	0.615	16,023	10,891

强大的 Agent 每次都能读到正确的章节；小型且不启用推理的模型在读取时能读到正确章节（命中时 NDCG 为 0.96），但有 38% 的问题找不到标准答案所在的章节。每次查询的推送式检索几乎没有成本；拉取则要耗费数万个 Token。表格特意同时列出了这两个事实。模型自行搜索时，在 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，并将索引写入指令，使其始终位于上下文中，同时提供五个工具。提出问题后，执行轨迹会显示 search，然后是 read，最后给出带有 [path.md#3] 引用的回答。如果想明确告知模型，可运行 contextpull claude-md 来打印一段 CLAUDE.md 片段。添加 --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 extra 时的 PDF，将其转换为标题、段落、表格和代码，并按标题切分为带有稳定 ID 的片段，例如 policy-2025.md#3。表格和代码不会在块中间拆分；长表格会按行拆分，且每个部分都会包含表头。重新摄取时会跳过未更改的文件。
2. 存储是一个 SQLite 文件，带有 FTS5 索引，其分词器会将标识符作为整体保留（--no-cache、UV_CACHE_DIR、TX-4419、3.12）。
3. 索引是一个按 token 预算控制的目录，每个文档占一行，并提供给模型的上下文。如果语料库太大，超出预算，就会采用分层结构。
4. 工具：index、search（ID 和摘要，不包含正文）、read（原文）、grep（精确匹配）、neighbours（表头行、下一条条款）。

Node

sdk/typescript/ 是一个基于存储格式的 TypeScript 读取器和 MCP 服务，使用 better-sqlite3：可打开同一个存储文件，查询时无需 Python。它以 contextpull 的名称发布到 npm。

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 进行测量，它就在隔壁。