DocsAgent 为 AI 代理提供即时、私密访问您的个人知识库。 docsagent 是基于规范的 MCP（模型上下文协议）服务器，它允许 任何 AI 代理——Claude Desktop、Cursor、Cline、Qwen Code 或任何 MCP 客户端——搜索、读取和 通过驻留者写入你的Zotero库、Obsidian库和Apple Notes（macOS） C++搜索引擎。BM25全文搜索+查询排序文章检索，1,000+ PDF 在**~15毫秒时，完全本地化（RAG准备知识库）。

• 🔒 本地优先且私有 — 引擎读取你的Zotero库、Obsidian vault，且 Apple Notes 直接存储在你的电脑上。你的笔记和 PDF 永远不会离开电脑。
• 🗂 三个来源，一个查询 — Zotero物品/注释/笔记，Obsidian保险库，以及 Apple Notes（仅限macOS）;混合搜索按倒数排序融合了这三者。
• ⚡ 原生C++搜索核心 — 反索引BM25 + 文章排名，毫秒查找， 内存占用较低（1500纸库为160–227 MB）。
• 🧩 8 个 MCP 工具 — 5 读取 + 3 写，带有 JSON-schema 验证参数，令牌预算， 结果去重，以及三层写入安全门。

DocsAgent MCP — Zotero, Obsidian & Apple Notes for AI agents 📚⚡

DocsAgent gives AI agents instant, private access to your personal knowledge base. docsagent is the spec-driven MCP (Model Context Protocol) server that lets any AI agent — Claude Desktop, Cursor, Cline, Qwen Code, or any MCP client — search, read, and write your Zotero library, Obsidian vault, and Apple Notes (macOS) through a resident C++ search engine. BM25 full-text search + query-ranked passage retrieval over 1,000+ PDFs at ~15 ms, fully local (RAG-ready knowledge base).

• 🔒 Local-first & private — the engine reads your Zotero library, Obsidian vault, and Apple Notes store directly on your machine. Your notes and PDFs never leave it.
• 🗂 Three sources, one query — Zotero items/annotations/notes, Obsidian vaults, and Apple Notes (macOS only); mixed search fuses all three by reciprocal rank.
• ⚡ Native C++ search core — inverted-index BM25 + passage ranking, millisecond lookup, low memory footprint (160–227 MB for a 1,500-paper library).
• 🧩 8 MCP tools — 5 read + 3 write, with JSON-schema validated arguments, token budgets, result dedup, and a three-layer write safety gate.
• 🌐 Two transports — stdio for local MCP clients, Streamable HTTP for remote deployment (origin checks, API-key / OAuth 2.0 token introspection, per-request RBAC, /health probe).
• 🐍 Two shells, one core — this TypeScript package and a feature-equal Python wrapper ship the same tools over the same JSON-RPC contract.

---

Architecture

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)

The shell never spawns the core during tool calls and never touches your source files. The core runs as a background service and stays available across MCP client restarts. Tool schemas and error codes: spec/.

---

Quick Start

1. Start the core

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

Python shell (same verbs, under the core subcommand):