sageread-mcp
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.
sageread-mcp
Better SageRead 阅读数据的 MCP server(只读):让任何支持 MCP 的 AI Agent 查询你的书库、阅读进度、阅读时长、划线标注、AI 对话与论文库,并对向量库做语义检索。
Better SageRead 是基于上游 xincmm/sageread 发展的独立维护版;本 MCP 同时兼容两者的数据目录(优先读 Better SageRead,见「数据目录」一节)。
数据安全:以
readonly模式打开 SageRead 的 SQLite 数据库,不写入数据库;BM25 统计也实时只读计算,不写bm25_stats密钥不出 app:语义检索的嵌入调用经 SageRead 本地通道转发,本进程不读取/不持有任何 API Key
离线可用:应用不在运行时仍能读 SQLite、
paper.md与 EPUB;search_library自动按标题/关键词回退,未索引文档也能搜索论文支持:完整 JSON/frontmatter 字段级元数据回退、canonical 目录与连续正文窗口、分组、标注和 8 种引用格式
书籍直读:Node 直接解析 EPUB 的 OPF/spine/nav,保留公式、表格和图片;无 EPUB 时回退 mdbook 原文
图片直读:论文图片清单与安全绝对路径解析;书籍/论文单图、多图经标准 MCP
imagecontent 返回,支持缩放与批量预算混合检索:
search_library合并 sqlite-vec、BM25 与关键词/标题结果,命中带可重放read锚点和有界next_cursor跨应用联动:配合其他 MCP(如知识库类),可以让 Agent 完成"把某段阅读对话归档到知识库"这类操作
工具(tools)
0.3.0 起默认只注册 20 个现代精简工具,覆盖「浏览书库 → 检索内容 → 读原文/插图 → 查引用」的主路径。旧工具收进 SAGEREAD_MCP_LEGACY_TOOLS 开关,避免新旧工具并列造成 Agent 选择困难;迁移对照见下一节。
默认现代精简集(20 个)
工具 | 说明 | 参数 |
| 书库全部书籍(含进度状态) |
|
| 单本书进度 |
|
| 阅读时长/次数统计 |
|
| AI 对话列表 |
|
| 对话完整内容 |
|
| 划线/标注/书签(论文标注含星标/类别/来源,位置渲染为可读形式) |
|
| 读书笔记面板的 Markdown 笔记(notes 表,与划线标注不同源),按书/星标过滤 |
|
| 对话导出为 Markdown |
|
| 书库所有标签 | 无 |
| AI 技能库(可选返回完整内容) |
|
| 论文书目元数据(frontmatter + 中文标题/摘要 + 收藏文件夹,字段保持 Pandoc/CSL 原义) |
|
| 批量文献卡片(书目信息一览,供初筛) |
|
| 论文分组(文件夹/颜色/包含论文) | 无 |
| 导出参考文献引用(8 种格式,见下),单篇或整个收藏文件夹 |
|
| 统一检索:语义 + BM25 + 关键词/标题互补,命中带 |
|
| 统一 DocRef 的完整元数据、目录、图表与参考文献数、索引状态;损坏元数据返回 |
|
| 论文 Markdown/HTML 图片清单:路径、图注、小节、全量计数与分页 |
|
| 真正读取书籍/论文图片,返回 JPEG 图片本体与路径/尺寸信封;支持单图和多图 |
|
| 统一 DocRef 读 canonical 窗口;返回 |
|
| 库内引用关系:它引用了库里哪些论文 / 库里谁引用了它(按 DOI/标题匹配 References,无需向量索引) |
|
论文与书籍统一用 doc 锚点表达:论文 paper:<id>、书籍 book:<id>;get_document_info 返回目录,read_document 按目录读正文,search_library 的命中结果同样带 doc 锚点。论文工具只支持 MARKDOWN 格式的论文书籍,book:<id> 指向论文或 paper:<id> 指向普通书籍时,DocRef 工具会返回明确的重定向提示。
文档坐标、元数据与图片缓存
所有现代 offset 都是 JavaScript UTF-16 字符坐标,
range为半开区间[start,end)。read可原样回传;续读把上次next_offset放进offset,不要自行加减。论文:canonical 去除 frontmatter、统一 CRLF/CR 为 LF 并规范化 display math。
heading首窗从该节contentStart开始,后续next_offset始终是正文绝对坐标,并限制在该节边界;无heading时offset也是正文绝对坐标。before/after可围绕命中扩窗。书籍:
heading/file/spine/fragment + offset使用节内 canonical;fragment区分同一 XHTML 的多个 nav 锚点。无这些锚点时的显式offset使用全书 canonical,可按 spine 连续跨章读取。各节以\n\n拼接,公式、表格、图片src/alt保留。图片路径在切片之后解析,不改变 offset。全书 canonical 上限为 16M 字符,超过时请按章节读取。元数据:
metadata.json按字段优先,paper.mdfrontmatter 补齐缺失字段;不存在 JSON 不是错误,损坏或不可读 JSON 会进入partial/errors,不会静默覆盖可用 frontmatter。论文图片路径:
read_document先按 canonical 切片,再把窗口内实际存在且位于论文目录内的相对图片路径改写为绝对路径;缺失文件、外部 URL、data URI 和越界路径保持原样。路径改写不影响任何 offset,但可能改变返回text的长度,因此不能再用range去切改写后的文本,续读必须重放read。list_paper_figures同时扫描 Markdown 与 HTML<img>,每条含image/image_path/caption/captionFrom/section/offset;无法解析到真实文件时image_path=null。total_found是全量图片数,total是本页数量,offset/limit按图片序号分页(不是 canonical 字符坐标),next_offset用于续页。orphanCaptions只统计未归属且带明确编号的 Figure/Fig/图 图注样式行,不统计 Table 或普通正文句。图片内容:
read_images(doc, paths, max_edge?)接受 1–6 个绝对路径,论文仅限本篇目录,书籍仅限本书目录和本书{appDir}/image-cache/epub/<bookId>/。同时校验词法路径与真实路径,拒绝目录穿越、symlink/junction 越界、其他书籍缓存和伪造图片。每张源图不超过 20 MiB,使用 sharp 解码、自动旋转并输出 JPEG;透明图以白色铺底。默认长边 1024,可选 512–1536;批量 base64 总预算 700,000 字符,按张数摊分并进一步压缩。每张图返回文本信封与标准 MCPimagecontent,单张失败不抹掉同批成功图片;部分失败会在首条文本和末尾清单同时标明,全部失败才标记isError。图片缓存:仅当返回窗口内的 EPUB 图片在 mdbook 中缺盘时,才物化该图片到
{appDir}/image-cache/epub/<bookId>/<sha256>.<ext>。路径由书籍与解析后的资源 href 决定,同书同资源复用;不整书预提取。响应的图片缓存披露目录与用途。缓存暂无容量/时间清理策略。Better SageRead 0.5.0 会另行负责 MCP 图片落盘与模型协议回灌,本 MCP 不判断模型视觉能力。
旧工具(legacy,默认关闭,7 个)
设置环境变量 SAGEREAD_MCP_LEGACY_TOOLS=1 后额外注册以下 7 个旧工具(与默认集合计 27 个),仅建议旧客户端/旧提示词兼容使用:
旧工具 | 说明 | 默认集替代 |
| 向量库语义检索(默认论文库) |
|
| 论文目录(解析 paper.md 标题层级) |
|
| 论文正文切片(offset/limit 分段) |
|
| 按小节标题读论文章节 |
|
| 书籍(EPUB)目录(nav.md 层级) |
|
| 读取书籍某章正文(file + offset/limit) |
|
| 语义检索命中块前后各扩 radius 块;目标参数接受 |
|
旧工具代码与行为全部保留,只是默认不出现在 tools/list 中;开关在进程启动时读取,切换后需重启 MCP 客户端。Legacy read_paper/read_book 仍用原始 paper.md / mdbook Markdown offset,与现代 canonical 坐标不互换;legacy semantic_search 仍默认 8 条、只走向量通道并保留旧输出,不获得现代关键词回退、混合权重或游标。
工具面迁移与 legacy 开关
旧调用(0.2.0) | 0.3.0 默认写法 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
数量约定:默认 20 个;
SAGEREAD_MCP_LEGACY_TOOLS=1时 27 个(20 + 7)。npm run smoke会分别断言两种模式。启用 legacy(Claude Desktop / Cherry Studio 等支持
env的客户端):
{
"mcpServers": {
"sageread": {
"command": "npx",
"args": ["-y", "sageread-mcp"],
"env": { "SAGEREAD_MCP_LEGACY_TOOLS": "1" }
}
}
}search_library是统一入口:scope选库、doc限定单本/单篇、collection过滤论文收藏;返回的doc可直接交给read_document/get_document_info/get_citation_graph。
export_paper_citation 的 format 支持 8 种格式:
bibtex(默认):@article{}条目,key 为「第一作者姓+年份+标题首实词」,缺字段省略对应行gbt7714:GB/T 7714-2015 期刊格式,超 3 位作者用 et al.apa:APA 第 7 版,Zhao, C., ... & Hu, Y.-S. (2020).形式,附 doi.org 链接mla:MLA 第 9 版,3 位及以上作者只写第一作者 + et al.,题名转 Title Case 加引号chicago:Chicago 参考文献表格式,第一作者倒置其余正序,超 10 位取前 7 + et al.ieee:IEEE 格式,名首字母 + 姓,超 6 位只写第一作者 + et al.vancouver:Vancouver 格式,姓 + 名首字母连写,超 6 位取前 6 + et al.,尾页缩写(708-711 → 708-11)ris:RIS 机器可读格式(Zotero/EndNote 可直接导入)
Title Case 转换(mla/chicago)做了保守处理:化学式/公式/含数字或内部大写的词(Na-ion、P2-type、$x$ 等)原样保留。
Related MCP server: zotero-mcp
检索、回退与续页
search_library 默认 scope=all,也可选 papers/books;doc=paper:<id>/book:<id> 限定单篇/单本,collection 过滤论文收藏。doc 与 scope 冲突、DocRef 类型错误或 cursor 用在 doc 模式都会明确报错。
真实嵌入通道可用时,查询文本由 SageRead 应用内执行向量化(当前模型与 keyring 密钥),本进程只发文本、只收回向量,API Key 不进入 MCP。应用未运行、未配置模型或设置 SAGEREAD_DISABLE_EMBED=1 时,不会让整个检索失败:标题/关键词通道仍返回结果,并在 errors/警告 与 partial 中披露 indexed 通道不可用。Legacy semantic_search 不受这个离线开关以外的回退影响,仍要求嵌入通道。
参数:
top_k默认 6、最大 30(直接调用也强制截断);vector_weight=0.7、bm25_weight=0.3会归一化并参与实际评分和跨书排序;include_references=false默认排除 References/参考文献。旧向量库缺少is_references列时会明确警告,不会直接 SQL 失败。命中:每条同时保留中文字段并提供
doc/snippet/similarity/source/index/read/anchor_precision。source为hybrid/bm25/keyword/title;index区分indexed/not_indexed;只有经验证的唯一 canonical 位置才是exact并带 offset,重复或无法验证时降级为section,不伪造位置。hit.read可直接传给read_document,再叠加before/after。无向量回退:
doc模式完整扫描单文档;library/all 完整发现标题,并对未索引正文做有界并发、章节数、时间和结果数限制,不无界解压全库 EPUB。partial/truncated、回退统计和提取错误会如实返回,indexed 通道失败不会抹掉关键词成功结果。续页:library/all 返回确定性的无状态
next_cursor,继续时原样回传cursor。游标绑定query/scope/collection/include_references,错误组合会拒绝;doc模式不使用 cursor。merge/RRF 只记录实际发出的 section-aware 命中,被首页挤掉的 fallback 可在后续页补发,直到游标消失;首页与续页都保留partial/truncated。只读与降级:损坏或维度不匹配的单个向量库会进入
errors/警告,不拖垮其它库;内部手册等无法解析为 DocRef 的命中会跳过。BM25 实时计算,不写统计缓存。不要机械按分数过滤:现代分数混合向量、BM25 与关键词/标题通道,legacy 分数来自向量距离;语义分数低也可能是正确内容,应结合片段与出处判断。
安装与构建
npm install
npm run clean && npm run build
node --test scripts/test-document-images.mjs # 图片路径、清单、真实图片内容、批量预算与安全边界
node scripts/test-document-contract.mjs # canonical、元数据、连续窗口、结构/图片
node scripts/test-search-library.mjs # 命中扩窗、回退、参数、merge/RRF 与游标
npm run smoke # 开发库;默认 20 / legacy 27,并强制验证无向量回退
SAGEREAD_SMOKE_EMBED=1 npm run smoke # 开发库真实嵌入,必须出现 hybrid 命中
npm run smoke -- --release # 发行版库 + 无向量回退
SAGEREAD_SMOKE_EMBED=1 npm run smoke -- --release # 发行版库真实嵌入
npm pack --dry-run # 检查实际发布文件npm run smoke 默认用 SAGEREAD_DISABLE_EMBED=1 验证无向量路径;SAGEREAD_SMOKE_EMBED=1 才启用并要求真实 hybrid 命中,避免把关键词成功误当成向量成功。真实嵌入不可用时应视为对应验收未通过,不能用降级结果代替。
要求 Node.js >= 20.9.0(sharp 0.35 的运行下限);目前仅支持 Windows(数据目录路径按 %APPDATA% 解析)。
数据目录
默认自动选活动实例:扫描
%APPDATA%下所有com.bettersageread*/com.xincmm.sageread*数据目录(发行版目录名可能是com.bettersageread.app等变体),排除.bak备份,在含database\app.db的候选中挑「最近活动」的一个(按app.db与mcp-local.json的修改时间取较新者排序)。因此无需硬编码目录名,同时装着 Better SageRead 与上游 SageRead、或多个版本并存时也能自动连到当前在用的那个--dev参数或SAGEREAD_DEV=1:只在开发版目录(名字含.dev,如com.bettersageread.dev)中选活动实例SAGEREAD_DB_PATH:完全自定义 db 路径,优先级最高(设置后跳过上述扫描)
客户端配置
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"sageread": {
"command": "npx",
"args": ["-y", "sageread-mcp"]
}
}
}--dev 仅当你使用开发版数据目录时加(放在 args 末尾)。
Cherry Studio
设置 → MCP 服务器 → 添加:
{
"mcpServers": {
"sageread": {
"command": "npx",
"args": ["-y", "sageread-mcp"]
}
}
}从源码构建(备选)
git clone https://github.com/Feplus2/sageread-mcp.git
cd sageread-mcp
npm install
npm run build然后以 node 直接启动(路径按实际位置替换):
{
"mcpServers": {
"sageread": {
"command": "node",
"args": ["<path-to>/sageread-mcp/dist/index.js"]
}
}
}Kimi CLI
见 config.toml 的 mcp_servers 一节(stdio 类型,command + args 同上)。
无 MCP 客户端时直接驱动 stdio(进阶)
本 server 是标准 stdio JSON-RPC,任何能起子进程、按行读写 stdin/stdout 的 Agent 都能直接驱动(initialize → notifications/initialized → tools/list / tools/call)。
Windows 注意:部分 Agent 环境(如经 Git Bash / Python 调用)里的
node是 shell/cmd shim,用CreateProcess直接执行会报WinError 2。此时需经cmd /c node ...包装,或在command里写node的绝对真实路径(where node查)。不想依赖自动扫描时,用
SAGEREAD_DB_PATH显式指定 db 路径最稳妥(search_library会据此反推 app 数据目录去找mcp-local.json)。
许可证
MIT
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
Read-only MCP server exposing a user ORANO library to their own AI agent.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for browsing, searching, and exporting a Zotero library from AI assistants.-
- AlicenseAqualityDmaintenanceRead-only MCP server that lets Claude or any MCP client search and retrieve metadata, notes, full text, citations, and BibTeX from your local Zotero library via its built-in API.11MIT
- AlicenseNot gradedqualityCmaintenanceRead-only MCP server for accessing local Kindle library data, exposing tools to query profile, health, and book metadata.MIT
- AlicenseAqualityCmaintenanceRead-only MCP server that exposes your local Notion backups to AI agents — query databases, read pages, search a backed-up workspace. Offline by default: no LLM calls, no telemetry, no cloud.61MIT