history_rag
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
HistoryRAG
许可证:AGPL-3.0-only,全文见 LICENSE。发行包附应用源码与构建脚本;第三方组件各自保留原许可证。
面向历史研究资料的本地 RAG 项目,默认适配 Windows 11 和 16 GB 内存。RAGFlow 负责文档解析、索引和混合检索,Ollama 提供本地 Embedding,Codex 通过 history_rag MCP 读取证据。
普通使用者从这里开始
在本仓库的 Releases 下载 HistoryRAG-0.4.0-Windows-x64.zip,完整解压后双击 HistoryRAG.exe,按中文首次安装向导操作。无需 Git、Python 或单独安装 Ollama。自己的文献、笔记和账号都留在自己的电脑。
Code → Download ZIP 下载的是源代码,不是可双击运行的安装包。 非开发者请使用 Releases 中的 Windows 包。首次需联网下载后端和模型,并按提示完成 Docker、本地资料库账号及自己的 Codex 登录。包内 README-START.txt 有完整说明。
当前是首次安装试用版,已完成本机自动测试、独立运行和敏感信息检查,尚未在全新电脑完成整套首装验收。
Related MCP server: busca-arquivos
给另一台电脑首次安装(0.4.0)
向朋友提供 Windows x64 发行 ZIP,完整解压后运行 HistoryRAG.exe。中文向导会选择专用目录、检查软件、按本人选择安装 Docker Desktop、下载模型/镜像、启动独立后端。无需 Python、Git 或单独安装 Ollama;检索模型运行在同一套容器中。首次仍需本人完成 Docker 的必要授权/重启、本地 RAGFlow 注册和生成 API Key,以及 Codex 登录。
提供本地 API Key 后,向导自动添加 Ollama 检索模型、创建或复用唯一的“历史资料库”、合并 Codex 的 history_rag 连接并创建桌面快捷方式。已有连接冲突时不自动覆盖,只有勾选替换才修改,修改前自动备份。不会复制作者账号、密钥、文献或运行状态。
向导使用专用 Compose 项目、独立随机密码和本机回环端口,不复用或删除已有 Docker 数据卷。支持失败后原目录重试。停止服务保留数据。新电脑的镜像和模型需要联网下载,不是离线包;Infinity 镜像要求兼容 x86-64-v3/AVX2 的 CPU。
接入方式采用 OpenAI 官方 MCP 配置 中的 STDIO command/args。把安装目录下 research(桌面“历史研究工作区”)添加为 Codex 项目,以加载研究规则;不修改用户全局 AGENTS.md 或替他登录。
开发者构建:安装 .[build],然后运行 python scripts/build-release.py --output <输出目录>。发行包附带应用源代码、AGPLv3 许可证和第三方许可说明,不包含 config/app.json、数据、日志、模型或作者环境。再分发时应保留许可证、依赖声明和对应源码。本机与模拟测试不替代新电脑的完整首次安装验收。
日常使用
双击
START-HistoryRAG.cmd,打开中文“历史资料库”窗口。窗口会自动启动并检查后端服务。点击“放入文献”,把 PDF 或 DOCX 复制到打开的文件夹。
窗口保持打开,每 10 秒自动扫描一次。只有解析完成且生成分块后,才显示“可检索”;原文件随后保存在“查看原文件”目录。
在 Codex 中直接要求检索“历史资料库”。无需另外点击同步。
关闭窗口会停止自动导入,但保留查询服务。若需要释放服务资源,关闭窗口后双击
STOP-HistoryRAG.cmd。
窗口支持查看文档状态、手动重新扫描和重试失败。失败原件保留在 data/failed,不会每 10 秒无限重试。相同内容不会重复上传,重复副本保留在 data/originals/duplicates。导入任务进行中暂不关闭窗口,避免中途打断。
重复打开入口不会重复启动导入器;手动同步与自动导入也不会同时处理同一批文件。启动日志在 logs/startup.log,窗口日志在 logs/desktop.log 和 logs/desktop-error.log。
支持 PDF、DOCX、Markdown、TXT(具体以配置中的 supported_extensions 为准)。
点击“放入笔记”可打开专门的个人笔记目录;通过该目录收录的文件带有个人笔记标记,避免把自己的解释当作史料。历史文献仍使用“放入文献”。需要桌面入口时运行一次 scripts/create-shortcuts.ps1,会创建“历史资料库”和“放入历史文献”两个快捷方式;不会覆盖同名已有快捷方式。
导入使用文件快照。若原件在解析过程中被继续修改,已上传版本独立归档,新内容留在导入目录供下一轮处理,不会把新内容误认成旧版。关闭窗口后需再次打开才能继续自动收录;目前不安装开机启动项或系统后台服务。
章节阅读、原页核对和课题记录
新增 MCP 工具在重新加载 Codex 后可用:
history_document_outline:读取 PDF 物理页数和内嵌书签目录。没有书签时,应先查看目录页定位章节。history_read_pages:每次按实际页序连续读取最多 20 页,逐批读取完整章节;返回覆盖范围和稀疏文本提示。扫描件没有可用文本层时,需查看原页,不能声称已经全文阅读。history_verify_page:返回原始 PDF 页面的图像,核对异体字、引文、注释和印刷页码。history_document_versions:查看原文件位置和新旧版本。将修改后同名文件再次复制到导入文件夹,新版本成功收录后才替代旧版成为默认检索来源;失败时旧版继续可用。不同作品请使用不同文件名。旧版文件和远程记录均保留,可指定文档 ID 查询旧版。history_research_save/history_research_read:按用户要求保存、继续或查看课题记录,保留每次修订。记录在data/state/research.db;不是史料证据,也不会自动混入文献检索。
原页读取目前要求本地状态库能够定位原文件。直接在 RAGFlow 网页上传、未由本程序登记的文件暂不支持此功能。PDF 页序从 1 开始;不得未经核实把 RAGFlow 的 page_index 换算成印刷页码。
常用辅助入口:
CHECK-HistoryRAG.cmd:检查服务、资料库、Embedding 和解析状态。RETRY-Failed.cmd:重试data/failed中的失败文档;已经上传过的文件会直接重试解析,不重复上传。
文档状态
本地状态库位于 data/state/history-rag.db:
uploading:正在上传。parsing:RAGFlow 正在解析和生成向量。indexed:RAGFlow 返回DONE,并且至少生成了一个分块。failed:上传或解析失败;错误详情保存在状态库中,原文件移入data/failed。
旧版产生的 uploaded 记录只代表文件曾上传,不能证明已完成索引。可通过 CHECK-HistoryRAG.cmd 对照远程解析统计。
升级旧版后可运行以下命令,用 RAGFlow 的实际状态修正本地记录:
.\.venv\Scripts\python.exe -m history_rag.cli --config .\config\app.json --reconcile-stateMCP 工具
自带的 stdio MCP bridge 提供:
ragflow_retrieval:检索史料证据片段。ragflow_list_datasets:列出资料库。ragflow_list_documents:查看文档、解析进度、分块数量和文档 ID。ragflow_health:检查资料库、Embedding 与解析数量。ragflow_list_chats:列出 RAGFlow 助手。
修改 MCP bridge 后需要重新加载 Codex,工具列表才会刷新。
首次安装
在 PowerShell 中运行:
Set-Location E:\Git\HistoryRAG
.\scripts\install-ollama.ps1
.\scripts\start-ollama.ps1
ollama pull bge-m3
.\scripts\bootstrap.ps1
.\scripts\prepare-images.ps1
.\scripts\start-ragflow.ps1然后:
打开
http://127.0.0.1。在 RAGFlow 中添加 Ollama,地址为
http://host.docker.internal:11434。添加
bge-m3Embedding 模型并创建“历史资料库”。生成 RAGFlow API Key。
复制
config/app.example.json为config/app.json,填写 API Key 和资料库 ID。运行
SYNC-Documents.cmd前可先执行scripts/sync-once.ps1 -DryRun。
config/app.json 包含密钥,已被 .gitignore 排除,不要提交或分享。
配置要点
request_timeout_seconds:单次 RAGFlow 请求超时。parse_timeout_seconds:等待一篇文档完成解析的最长时间,默认 1800 秒。parse_poll_interval_seconds:解析状态轮询间隔,默认 3 秒。move_after_upload:索引完成后是否移动原文件。
默认采用内置 chunking pipeline,并通过 /api/v1/datasets/{dataset_id}/chunks 触发解析。若资料库改用 ingestion pipeline,需要改为 RAGFlow 的 /api/v1/documents/ingest 接口。
诊断和测试
.\scripts\diagnose.ps1
.\.venv\Scripts\python.exe -m history_rag.cli --config .\config\app.json --health
.\.venv\Scripts\python.exe -m pytest -q如果 MCP 提示无法连接后端,先运行 START-HistoryRAG.cmd;网页能够打开不等于检索已经就绪,以启动末尾的系统自检结果为准。
目录
codex/ Codex 规则与 MCP 配置示例
config/ 本地配置模板
data/inbox/ 待入库文档
data/originals/ 已成功索引的原文件
data/failed/ 失败文档
data/state/ SQLite 状态库与进程记录
scripts/ Windows 管理脚本与 MCP bridge
src/ 增量同步程序
tests/ 自动测试Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Versioned documentation registry and semantic search for AI tools and coding assistants.
Retrieve citation-ready technical context and coordinate evidence-backed work between AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables local-first, versioned evidence retrieval from papers without loading the whole library into a conversation, with optional Zotero, writing, fixed-commit code, and experiment record integration returning bounded excerpts and page images.51MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to search and read the user's local document collection (PDF, Word, Excel, Markdown, plain text) during a conversation by subject, by file name/path, or by exact word, and to retrieve file contents page by page. It also supports finding folders relevant to a topic and checking indexing status, with everything running locally on the user's machine.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to perform local hybrid search over crawled web pages and personal PDF, Markdown, HTML, and text documents, returning cited passages with source, section, page, and score details. It also exposes tools to list documents, retrieve full document text, and check index status.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables users to index and retrieve local documents through semantic, BM25, or hybrid search, with tools for chunk reads and page images accessible from MCP clients such as Codex and ChatGPT web.MIT