5 步用 MCP 把 PageIndex 接入 Claude 与 Cursor，直接提问完成长文档分析

5 步用 MCP 把 PageIndex 接入 Claude 与 Cursor，直接提问完成长文档分析

【免费下载链接】PageIndex📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG项目地址: https://gitcode.com/GitHub_Trending/pa/PageIndex

200 页的 PDF 没法在 AI 对话框里直接提问。PageIndex 是一个无向量、基于推理的长文档分析框架，通过 MCP 集成可以直接接入 Claude 桌面版与 Cursor 等客户端，用大白话向文档提问。

📑 工作原理：先翻目录，再读原文

PageIndex 不切块、不走向量库，它先给 PDF 生成一份"目录"，再让模型沿着目录找到页码、最后读原文。

树状索引就像书的目录：AI 按目录查内容，而不是逐字搜索。具体分两步：

• 第一步扫描 PDF，生成树状索引，每个节点是文档的自然章节，带章节标题、页码范围和简短摘要；
• 第二步在提问时，模型沿树从上到下推理、逐步缩小范围，定位到相关节点后再取页内容。

这和向量检索"相似但不相关"的毛病不同：每次检索都带明确的章节与页码引用，答案从哪来可以核对。官方 Mafin 2.5 金融文档系统基于这套方法，在 FinanceBench 基准上取得 98.7% 准确率（来源：项目官方基准数据）。

⚙️ 3 步装好并配好密钥

环境要求 Python 3.8+，无需额外安装向量数据库，三步完成：

1. 克隆仓库并进入目录
2. 安装依赖
3. 在项目根目录创建.env文件，填入 LLM 的 API key（走 LiteLLM，可换成其他模型厂商）

git clone https://gitcode.com/GitHub_Trending/pa/PageIndex cd PageIndex pip3 install --upgrade -r requirements.txt

OPENAI_API_KEY=your_API_key_here

密钥配好后，可以先对任意一份 PDF 跑一次建索引，打开生成的结构文件看看"目录"长什么样。入口脚本是 run_pageindex.py，模型与节点参数都在 pageindex/config.yaml 里，改的时候留意这两处即可。

🔌 接入 AI 客户端：Claude 与 Cursor

PageIndex 的 MCP 服务地址是 api.pageindex.ai/mcp，仓库里 pageindex/mcp_bridge.py 实现了完整的客户端协议，你只需要在客户端配置里加一条服务器记录。

在 Claude 桌面版中添加 MCP 服务器

这是最标准的 Claude MCP server 配置路径，全程在客户端图形界面内完成：

1. 打开 Claude 桌面版，进入设置，找到 MCP Servers / Developer 部分
2. 添加新的 MCP 服务器，选择远程（HTTP）类型，粘贴下面的配置片段，key 换成你自己的
3. 保存后等待状态变绿，工具列表里应出现 browse_documents、get_document_structure、get_page_content 等只读工具

配置片段（并入客户端的 mcpServers 配置）：

"pageindex": { "url": "https://api.pageindex.ai/mcp?tools=read", "headers": { "Authorization": "Bearer your_API_key" } }

注意地址末尾的?tools=read是只读模式，模型只能查询和阅读、不能删除文档，第一次接入建议用这个。

在 Cursor IDE 中启用文档分析

Cursor 文档分析的配置与上面完全相同：

1. 打开 Cursor 设置中的 MCP 入口，选择添加新的 MCP 服务器
2. 粘贴同一段 JSON 配置，填入 key
3. 验证：在对话框输入"列出我能查看的文档"，能返回文档列表就说明接好了

🧪 完整走一遍：上传、提问、核对

接好之后，一个完整闭环分三步，全程可核对。

1. 上传文档：把一份 PDF 上传到 PageIndex 文档库（本地也可以用 run_pageindex.py 建索引）。文档会先进入树状索引构建，可用 get_document 查看处理状态。
2. 直接提问：问"这份年报里的主要风险有哪些"。模型会先调 get_document_structure 取目录，缩小到风险相关章节，再调 get_page_content 按页码读原文，最后组织答案。
3. 核对答案：回答会附带章节名和页码，翻回 PDF 对应页面比对，检索是否准确一目了然。

这个"查目录 → 读原文 → 引页码"的闭环，正是 MCP 长文档分析体验的核心。

❓ 常见避坑

安装命令跑完报 ModuleNotFoundError 怎么办？

多半是 Python 版本问题。项目要求 3.8+，先用 python3 --version 确认；系统里装了多个 Python 时，注意用与解释器匹配的 pip3 重装依赖。

配置文件到底在哪个位置？

一共三处，分工不同：模型名与节点参数在 pageindex/config.yaml，API key 在项目根目录的 .env，MCP 连接地址与鉴权头在 AI 客户端的配置里，别混着改。

MCP 服务器显示连接失败或 401、403？

几乎都是鉴权问题。检查 Authorization 是否为"Bearer"加空格再加 key，key 是否过期，以及网络能否访问 api.pageindex.ai，公司网络要留意代理设置。

上传长文档后很久没响应正常吗？

正常，索引构建耗时与页数成正比。先看状态（pending、processing、completed），或用 wait_for_completion 参数最多等 3 分钟；长时间停留在 processing 时，换一份更小的文档重新验证流程。

PDF 抽不出文字（扫描件）怎么办？

自托管走的是标准 PDF 解析，纯图片的 PDF 会提示页面空白。这种情况改用带 OCR 的云端服务，或先把 PDF 转成可检索文本的版本。

🎚️ 进阶调优：先动这两个参数

默认值对多数文档够用，超长文档主要调下面两个。

• max_page_num_each_node（每节点最大页数，默认 10）：文档很长时可提到 15~20，树节点更少、检索更快，代价是章节粒度略粗
• max_token_num_each_node（每节点最大 token 数，默认 20000）：单节内容太长导致节点被截断时调大，保证章节完整
• toc_check_page_num（扫描目录的页数，默认 20）：目录位置靠后时调大，避免树建在错误的标题上

构建速度也值得关注。项目内置的 PageIndex Flash 用启发式方法做结构提取，树结构本身几秒就能生成；加上摘要与优化，1000 页的文档大约 3~4 分钟：

📚 去哪学更多

• cookbook/pageIndex_chat_quickstart.ipynb：聊天流程快速上手，跟着跑一遍就有手感
• examples/tutorials/doc-search/：文档搜索教程，覆盖描述、元数据等检索策略
• examples/tutorials/tree-search/：树搜索教程，讲清模型如何在树上导航
• examples/agentic_vectorless_rag_demo.py：自托管的 agentic 无向量 RAG 完整示例

把 PageIndex 通过 MCP 接入 Claude 与 Cursor 之后，长文档从"逐字翻"变成"按目录翻"，每个答案都能带页码去核对。挑一份你一直想问的文档，把上传、提问、核对这个闭环跑一遍，上手也就这几步的事。

【免费下载链接】PageIndex📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG项目地址: https://gitcode.com/GitHub_Trending/pa/PageIndex