DocsAgent — Zotero, Obsidian & Apple Notes MCP Server

DocsAgent MCP — 为 AI Agent 提供 Zotero、Obsidian 和 Apple Notes 📚⚡

DocsAgent 让 AI Agent 能即时、私密地访问你的个人知识库。 docsagent 是一个由规范驱动的 MCP（Model Context Protocol）服务，让任意 AI Agent——Claude Desktop、Cursor、Cline、Qwen Code 或任何 MCP 客户端——都能通过常驻的 C++ 搜索引擎搜索、读取和写入你的 Zotero 文献库、Obsidian 知识库和 Apple Notes（macOS）。基于 1,000+ PDF 的 BM25 全文搜索 + 查询排序段落检索，耗时约 15 ms，完全在本地运行（适用于 RAG 的知识库）。

• 🔒 本地优先且私密——引擎直接在你的设备上读取 Zotero 文献库、Obsidian 知识库和 Apple Notes 存储。你的笔记和 PDF 永远不会离开设备。
• 🗂 三个来源，一次查询——Zotero 条目／批注／笔记、Obsidian 知识库和 Apple Notes（仅限 macOS）；混合搜索通过倒数排名融合这三个来源。
• ⚡ 原生 C++ 搜索核心——倒排索引 BM25 + 段落排序，毫秒级检索，内存占用低（1,500 篇论文的文献库占用 160–227 MB）。
• 🧩 8 个 MCP 工具——5 个读取 + 3 个写入，支持 JSON Schema 参数验证、令牌预算、结果去重，以及三层写入安全门控。
• 🌐 两种传输方式——stdio 供本地 MCP 客户端使用；Streamable HTTP 用于远程部署（来源检查、API 密钥／OAuth 2.0 令牌内省、按请求执行 RBAC、/health 探测）。
• 🐍 两种封装，一个核心——此 TypeScript 包和功能相同的 Python 封装通过相同的 JSON-RPC 契约提供相同的工具。

---

架构

MCP Client (Claude Desktop / Cursor / Cline / Qwen Code / any MCP host)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← this package (@docsagent/mcp-zotero / docsagent-mcp-zotero)
   · tool schemas (spec-driven), argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
   · group-library sync via the Zotero Web API
        │  JSON-RPC 2.0 over HTTP ({coreHost}:{httpPort}/rpc, cpp-httplib)
        ▼
DocsAgent Core (resident C++ engine)
   · reads ~/Zotero/zotero.sqlite + storage/, an Obsidian vault, and (macOS) the
     Apple Notes store — directly on your machine
   · builds & serves one index per source (BM25 + passage ranking); mixed search
     (source "all") fuses them by reciprocal rank (RRF, k=60)

工具调用期间，封装绝不会启动核心进程，也不会触碰你的源文件。 核心作为后台服务运行，在 MCP 客户端重启后仍可使用。 工具架构和错误代码：spec/。

---

快速开始

1. 启动核心

npx @docsagent/docsagent start           # spawn the bundled core for your platform
npx @docsagent/docsagent status          # pid / endpoint / version

Python 封装（相同命令，位于 core 子命令下）：

pip install ./python                      # build the wheel locally (PyPI upload pending)
docsagent-mcp core start

（也提供 core stop / core restart。核心会为每个已配置的来源建立索引——你的 Zotero 数据目录、Obsidian 知识库，以及（macOS 上的）Apple Notes——并在 http://0.0.0.0:23120/rpc 提供 JSON-RPC 服务。）

2. 配置 MCP 客户端

Claude Desktop / Cursor / Cline / Qwen Code（mcpServers）：

{
  "mcpServers": {
    "docsagent": {
      "command": "npx",
      "args": ["-y", "@docsagent/docsagent"]
    }
  }
}

Python 封装（相同工具、相同契约，从此仓库安装）——mcpServers：

{
  "mcpServers": {
    "docsagent-zotero-py": {
      "command": "docsagent-mcp"
    }
  }
}

请先安装 Python 包（步骤 1），确保 docsagent-mcp 位于 PATH 中。

启动时，封装会连接核心、加载来源并检查索引状态。如果核心未运行，它会立即失败并显示启动说明——绝不会启动任何进程。

---

MCP 工具（外部 API）

共 8 个工具，5 个读取 + 3 个写入。架构以 spec/tools/*.json 中的规范为唯一来源（同步至两个包）；运行处理程序前会验证参数，失败时会映射为带类型的 docsagent 错误代码。

list_sources

列出所有可搜索来源及其功能、支持的目标／包含项／浏览模式、筛选条件和文档数。请先调用此工具。

当前支持的来源：zotero（目标为 items、annotations、notes；可浏览分类／标签）、 obsidian（一个知识库——笔记作为条目，可浏览文件夹／标签）和 apple-notes（仅限 macOS——在其他平台上，引擎会省略此来源）。知识库位于 ~/Documents/Obsidian Vault（可通过 DOCSAGENT_OBSIDIAN_VAULT 覆盖）；Apple Notes 从系统 Notes 存储中读取（可通过 DOCSAGENT_APPLE_NOTES_DB 覆盖）。

search

跨条目搜索一个来源中的内容（条目、批注和笔记）。

参数	类型	说明
query	字符串	普通关键词或短语；除非 mode=grep，否则为必填
mode	relevance | grep	默认为 BM25 相关性搜索；grep 会扫描字面模式，不进行分词或排序
pattern	字符串，在 mode=grep 时必填	要扫描的字面字符串
caseSensitive、wholeWord、maxMatches		仅用于 mode=grep：ASCII 大小写折叠、[A-Za-z0-9_] 单词边界、命中总数上限
target	"items" | "annotations" | "notes" 或数组	默认为 items
depth	ids | snippets | full	默认为 snippets（按 BM25 排序的段落）
filters	对象	tags、yearFrom/yearTo、itemType、authors、colors、containerId、titleContains
k、snippetsPerResult、max_tokens	数字	排序深度和令牌预算（mode=grep 时为最大文档数、每个文档的最大命中窗口数）

返回包含全局 ID（zotero:KEY、obsidian:<path>、apple-notes:<uuid>）、标题、相关性和摘要的 results[]；多目标搜索会按目标分组。在 mode=grep 下，每个结果包含 matchCount 和 snippets[] 命中窗口（hits[] 中带有 line/column/offset，元数据命中项则带有 field 标签），relevance 为 0，响应还会添加 totalMatches。结果会去重（先按 ID，再按规范化标题和年份），并控制在令牌预算内。

search 会针对 config.defaultSource（默认为 zotero）运行。混合搜索是核心功能：将 source: "all" 传给核心的 search / grep 方法后，每个来源都会独立排序，然后通过倒数排名融合（k=60）合并结果——每个命中项都会标记其来源。不同语料库的 BM25 分数不可比较，因此融合依据排名进行。

get_content

读取一条条目。mode=passages（按查询排序的段落，k）或 mode=fulltext（带 nextOffset 的偏移分页）。笔记会返回正文及标签和元数据。

get_metadata

include：metadata、abstract、annotations、notes、citation（通过 citationFormat/citationStyle 指定 bibtex / csljson / 格式化引用）。笔记会控制在令牌预算内。

list_library

浏览模式：collections（通过 parentId 逐级浏览）、items（按 containerId）、tags、saved_searches、standalone_notes。浏览模式按来源区分——Zotero 提供所有这些模式，而 Obsidian 和 Apple Notes 提供 folders（逐级浏览）/ tags / items。

写入工具（三层安全关卡）

工具	功能	关键参数
import_item	导入本地 PDF，或解析 DOI / ISBN / arXiv ID（通过 Zotero translation server）；可选的 autoClassify 会推荐分类集合	paths | identifiers、containerId、autoClassify、confirmed
add_note	为条目添加 Markdown 子笔记（转换为 Zotero 笔记 HTML），并验证是否为孤立笔记，必要时回滚	id、content、tags、confirmed
batch_modify	对最多 200 个条目进行批量 add_to_collection / remove_from_collection / add_tags / remove_tags 操作，每批 50 个	action、ids、containerId、tags、confirmed

写入工具仅适用于 Zotero 来源——Obsidian 和 Apple Notes 来源为只读。

写入安全关卡（spec/algorithms/write-gate.md）：除非设置 enableWrites=true，否则第 1 层不会注册写入工具；第 2 层中，confirmed=false 会返回预览，且不消耗速率限制额度；第 3 层中，已确认的写入会消耗每小时速率限制额度（默认为 30/h）。在 batch_modify 中，超过 20 个条目的操作还会在预览中报告 requiresConfirmation。

引擎性能

C++ 引擎为 PapersGPT 提供支持——同一套索引和检索技术栈也用于此 MCP 服务。在真实的 Zotero 安装环境中进行基准测试（完整报告）：

指标	Mac（Intel i9）	Windows VM（4C8G）
文库大小	1,506 篇 PDF（磁盘占用 4.5 GB）	500+ 篇 PDF
索引构建时间	141 s	几秒
内存（Agent 进程）	227 MB	160 MB
平均检索延迟	~15 ms	~15 ms

• 索引耗时大致随文库大小线性增长；检索延迟则保持恒定——包含 10,000 篇论文（约 30 GB）的文库约需 15–20 分钟完成索引，日常搜索仍为 ~15 ms。
• 作个比较：典型网页加载需要 1,000–3,000 ms；眨眼约为 100–150 ms。PapersGPT 完全离线，约 15 ms 即可给出答案。
• 隐私：你的文库不会离开你的设备。

配置

配置文件位于 ~/.docsagent/config.json（或 $DOCSAGENT_CONFIG）——JS shell、Python 封装层和 C++ 核心共用同一个文件。根据 spec/config.json 进行验证。

键	默认值	说明
coreHost	0.0.0.0	核心绑定并由 shell 连接的地址
httpPort	23120	核心 HTTP 端口（POST /rpc）
coreBinary	""	可选的核心二进制文件显式路径
zoteroDataDir	~/Zotero	Zotero 数据目录
zoteroApiUrl	http://localhost:23119/api	Zotero 本地 API（写入操作编排）
zoteroGroups	[]	从 zotero.org 同步的群组文库
enableWrites	false	注册三个写入工具
writeRateLimitPerHour	30	已确认写入的速率限制
maxTokensPerTool	4000	每个工具结果的 Token 预算
defaultSource	zotero	shell 搜索和解析 ID 前缀时使用的数据源（zotero、obsidian、apple-notes）
transport	stdio	stdio 或 streamable-http
httpListenAddr	0.0.0.0:8080	streamable-http（/mcp）的监听地址
authMode / authConfig	none	api-key 或 oauth2（RFC 7662）+ allowedOrigins
rbacRoles	{}	角色 → 允许使用的工具名称（HTTP 上按请求执行 RBAC）
logLevel	info	debug / info / warn / error

---

分发

渠道	包	随附核心	大小
npm（JS/TS shell）	@docsagent/docsagent	bin/ 中包含所有平台的文件	~70 MB tarball
PyPI（Python shell）	docsagent-mcp（pip install ./python）	wheel 中包含相同的二进制文件	~65 MB wheel

随附核心支持的平台：macOS 通用版（Intel + Apple Silicon）、Windows x64 （x86_64）、Linux x64（x86_64）——不支持 Linux ARM。数据源可用性： Zotero 和 Obsidian 可在所有平台上使用；Apple Notes 仅限 macOS（其他平台上的 list_sources 不会列出它）。

两个 shell 读取相同的配置，并连接到同一个核心——可任选其一（或同时使用），作为 MCP 分发渠道。两个 CLI 均支持核心生命周期管理（start / stop / restart / status）。

链接

• spec/ — 单一来源的规范：8 个工具 schema、23 个 JSON-RPC 方法、错误代码 + 建议调用、配置 schema
• PapersGPT 搜索性能基准测试
• Zotero · Model Context Protocol

许可证

Apache-2.0