sageread-mcp

Better SageRead 阅读数据的 MCP server（只读）：让任何支持 MCP 的 AI Agent 查询你的书库、阅读进度、阅读时长、划线标注、AI 对话与论文库，并对向量库做语义检索。

Better SageRead 是基于上游 xincmm/sageread 发展的独立维护版；本 MCP 同时兼容两者的数据目录（优先读 Better SageRead，见「数据目录」一节）。

• 数据安全：以 readonly 模式打开 SageRead 的 SQLite 数据库，不会以任何形式写入，不影响 SageRead 运行

• 密钥不出 app：语义检索的嵌入调用经 SageRead 本地通道转发，本进程不读取/不持有任何 API Key

• SageRead 不在运行时只读工具可用（数据是本地文件）；semantic_search 需应用运行（嵌入在 app 内执行）

• 论文支持：读取论文目录、正文与分组，列出论文标注（含星标/类别/来源）

• 书籍直读：get_book_toc / read_book 解析 EPUB 的 mdbook 目录并直读整章正文（不再只能靠 3 块上下文拼接）

• 语义检索：基于 SageRead 的向量库（sqlite-vec）做自然语言近邻检索

• 跨应用联动：配合其他 MCP（如知识库类），可以让 Agent 完成"把某段阅读对话归档到知识库"这类操作

工具（tools）

论文工具（get_paper_info / get_paper_toc / read_paper / read_paper_section）仅支持 MARKDOWN 格式的论文书籍；书籍工具（get_book_toc / read_book）面向 EPUB 等普通书籍，两者互斥，误用会返回明确的重定向提示。

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

语义检索说明

semantic_search 需要：① SageRead 应用正在运行（启动时会写 mcp-local.json 本地通道凭据）； ② 已在「设置 → 向量模型」配置并选中向量模型；③ 对论文/书籍执行过向量化。

查询文本的向量化由 SageRead 应用内执行（用当前选中模型与 keyring 密钥），sageread-mcp 只发文本、只收回向量——API Key 绝不进入本进程。未启动应用/未配置模型时，工具返回带引导的降级提示而非崩溃。

• 查询向量维度与向量索引维度不一致时，会提示在 SageRead 中重建向量索引

• collection 按收藏文件夹过滤论文（仅影响论文域），与 paper_id 同给时取交集

• 相似度数值偏低不代表没命中：返回的「相似度」是向量距离换算值，受嵌入模型与文本长度影响很大，实测有 17% 相似度却内容完全正确的命中。不要按相似度阈值过滤结果，应逐条看内容与出处判断相关性

安装与构建

npm install
npm run build        # 产物在 dist/
npm run smoke        # 冒烟测试（连真实开发版数据库走一遍）
SAGEREAD_SMOKE_EMBED=1 npm run smoke   # 追加 semantic_search 的真实嵌入调用

要求 Node.js >= 18；目前仅支持 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 路径最稳妥（semantic_search 会据此反推 app 数据目录去找 mcp-local.json）。

许可证

MIT