Skip to content
Back to search

docsagent

⚡ DocsAgent — give your AI agents instant, private access to your personal knowledge base (Zotero, Obsidian, Apple Notes supported now, local docs on the road). Native C++ search core: BM25 + passage ranking in ~15 ms. MCP server for Claude, Cursor, Cline & any MCP client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/docsagent/docsagent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/docsagent/docsagent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/docsagent--docsagent/badge.svg)](/listings/docsagent--docsagent)

HTML

<a href="/listings/docsagent--docsagent"><img src="/api/listings/docsagent--docsagent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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):

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

(`core stop` / `core restart` also available. The core indexes every configured source — your Zotero data directory, your Obsidian vault, and (macOS) Apple Notes — and serves JSON-RPC on `http://0.0.0.0:23120/rpc`.)

2. Configure your MCP client

Claude Desktop / Cursor / Cline / Qwen Code (`mcpServers`):

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

Python shell (same tools, same contract, installed from this repo) — `mcpServers`:

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

Install the Python package first (step 1) so `docsagent-mcp` is on your PATH.

On startup the shell connects to the core, loads sources, and checks index status. If the core is not running it fails fast with startup instructions — it never spawns anything.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 86 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: docsagent
  3. description: Search and manage private, local document collections (PDF, PPTX, DOCX) offline. Use when you need to find information within your private files, not for web research.
  4. ---
  5. # DocsAgent Skill
  6. DocsAgent is a local-first documentation engine designed to perform lightning-fast **hybrid search** (text and semantic search) over your private local files.
  7. ## Key Features
  8. - **Privacy-First**: All indexing and searching happen 100% locally on your machine. No documents or data ever leave your system.
  9. - **Hybrid Search**: Combines semantic and keyword-based text search for high accuracy.
  10. - **Supported Formats**: Optimized for **PDF, PPTX, and DOCX** files.
  11. - **No Web Dependency**: This tool does not perform web searches. It relies on a local index you create.
  12. ## Privacy Guarantee
  13. * **100% Local**: All processing, indexing, and search operations are performed entirely on your machine.
  14. * **Zero Data Leakage**: No data is sent to external servers. Your documents remain private.
  15. ## When to use
  16. - Use this when searching for information within your own private documentation, research papers, reports, or presentations.
  17. - Do not use this for general internet queries, news, or public website information.
  18. ## Installation
  19. DocsAgent is a CLI toolkit, when you install the global `docsagent` package, You can directly use 'docsagent' command.
  20. ```bash
  21. npm install -g @docsagent/docsagent
  22. ```
  23. For more information, please see https://github.com/docsagent/docsagent.
  24. ## Usage Guidelines
  25. ### 1. Add Documentation
  26. Adds directory or file paths (PDF, DOCX, PPTX) to the index. You can pass multiple paths at once.
  27. ```bash
  28. # Add a single directory
  29. docsagent add ./documents/manuals
  30. # Add multiple files and directories at once
  31. docsagent add ./reports/q1.pdf ./presentation.pptx ./notes/meeting-files
  32. ```
  33. * **Use case**: Use to index folders or specific private files for searchability.
  34. ### 2. Search Documents
  35. Performs a hybrid search (text + semantic) across your indexed private documents.
  36. ```bash
  37. # Search for a specific topic
  38. docsagent search "how to configure local encryption"
  39. # Search for technical concepts
  40. docsagent search "API authentication process"
  41. ```
  42. The tool returns the most relevant snippets with their source paths and scores.
  43. * **Important**: Ensure your documents have been indexed using the `add` operation before searching.
  44. ### 3. List Indexed Sources
  45. Lists all files currently being monitored or indexed.
  46. ```bash
  47. docsagent list
  48. ```
  49. ### 4. Check Status
  50. Shows the indexing progress and service health.
  51. ```bash
  52. docsagent status
  53. ```
  54. ### 5. Stop Agent
  55. Stops the indexing service.
  56. ```bash
  57. docsagent stop
  58. ```
  59. ## Workflow: Answering Questions from Local Docs
  60. 1. **Check Index**: If unsure if the documents are indexed, you can try a `search` first.
  61. 2. **Search**: Execute `search` with a specific query derived from the user's request.
  62. 3. **Analyze**: Review the context returned. If multiple snippets are found, synthesize them into a coherent answer.
  63. 4. **Cite Sources**: Always mention the file path and page number (if available) in your response.
  64. ## Error Handling
  65. - If `search` returns "No results found", inform the user and ask if they want to index a specific directory using `add`.
  66. - If a path is not found during `add`, verify the path exists before retrying.
README.md · README · 274 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DocsAgent MCP — Zotero, Obsidian & Apple Notes for AI agents 📚⚡
  2. [![App Store](https://img.shields.io/badge/App%20Store-iPhone%20app-0D96F6?logo=appstore&logoColor=white)](https://apps.apple.com/us/app/docsagent/id6829574595)
  3. [![Website](https://img.shields.io/badge/Website-docsagent.app-0ea5e9)](https://www.docsagent.app)
  4. [![License](https://img.shields.io/badge/License-Apache--2.0-blue)](LICENSE)
  5. **DocsAgent gives AI agents instant, private access to your personal knowledge base.**
  6. **`docsagent`** is the spec-driven **MCP (Model Context Protocol) server** that lets
  7. any AI agent — Claude Desktop, Cursor, Cline, Qwen Code, or any MCP client — search, read, and
  8. write your **Zotero** library, **Obsidian** vault, and **Apple Notes** (macOS) through a resident
  9. **C++ search engine**. BM25 full-text search + query-ranked passage retrieval over **1,000+ PDFs**
  10. at **~15 ms**, fully local (RAG-ready knowledge base).
  11. - 🔒 **Local-first & private** — the engine reads your Zotero library, Obsidian vault, and
  12. Apple Notes store directly on your machine. Your notes and PDFs never leave it.
  13. - 🗂 **Three sources, one query** — Zotero items/annotations/notes, Obsidian vaults, and
  14. Apple Notes (macOS only); mixed search fuses all three by reciprocal rank.
  15. - ⚡ **Native C++ search core** — inverted-index BM25 + passage ranking, millisecond lookup,
  16. low memory footprint (160–227 MB for a 1,500-paper library).
  17. - 🧩 **8 MCP tools** — 5 read + 3 write, with JSON-schema validated arguments, token budgets,
  18. result dedup, and a three-layer write safety gate.
  19. - 🌐 **Two transports** — stdio for local MCP clients, Streamable HTTP for remote deployment
  20. (origin checks, API-key / OAuth 2.0 token introspection, per-request RBAC, `/health` probe).
  21. - 🐍 **Two shells, one core** — this TypeScript package and a feature-equal
  22. [Python wrapper](python/) ship the same tools over the same JSON-RPC contract.
  23. > 📱 **On the go?** [**DocsAgent for iPhone**](https://apps.apple.com/us/app/docsagent/id6829574595) —
  24. > your Zotero library in your pocket, with AI chat. Free on the App Store.
  25. ---
  26. ## 📱 DocsAgent for iPhone
  27. Same library, smaller screen. The iPhone app turns your Zotero library into **pocket Zotero** —
  28. ask any paper anything while you're away from your desk.
  29. - **Search everything** — titles, authors, and full text across your whole library
  30. - **Chat with papers** — grounded answers that cite the exact passage
  31. - **Private by design** — no account, no sign-in, your library stays on your devices
  32. - **Pairs with the Mac companion** — scan a pairing code once, no computer needed afterwards
  33. **[Download on the App Store →](https://apps.apple.com/us/app/docsagent/id6829574595)**
  34. Free · iOS 16 or newer · Not yet available in mainland China or the EU
  35. Also available on the web: [docsagent.app](https://www.docsagent.app)
  36. ---
  37. ## Architecture
  38. ```
  39. MCP Client (Claude Desktop / Cursor / Cline / Qwen Code / any MCP host)
  40. │ stdio (local) or Streamable HTTP /mcp (remote)
  41. ▼
  42. MCP shell ← this package (@docsagent/mcp-zotero / docsagent-mcp-zotero)
  43. · tool schemas (spec-driven), argument validation, token budget, dedup
  44. · write orchestration via the Zotero local API, write safety gate, RBAC
  45. · group-library sync via the Zotero Web API
  46. │ JSON-RPC 2.0 over HTTP ({coreHost}:{httpPort}/rpc, cpp-httplib)
  47. ▼
  48. DocsAgent Core (resident C++ engine)
  49. · reads ~/Zotero/zotero.sqlite + storage/, an Obsidian vault, and (macOS) the
  50. Apple Notes store — directly on your machine
  51. · builds & serves one index per source (BM25 + passage ranking); mixed search
  52. (source "all") fuses them by reciprocal rank (RRF, k=60)
  53. ```
  54. The shell **never spawns the core** during tool calls and never touches your source files.
  55. The core runs as a background service and stays available across MCP client restarts.
  56. Tool schemas and error codes: [spec/](spec/).
  57. ---
  58. ## Quick Start
  59. ### 1. Start the core
  60. ```bash
  61. npx @docsagent/docsagent start # spawn the bundled core for your platform
  62. npx @docsagent/docsagent status # pid / endpoint / version
  63. ```
  64. Python shell (same verbs, under the `core` subcommand):
  65. ```bash
  66. pip install ./python # build the wheel locally (PyPI upload pending)
  67. docsagent-mcp core start
  68. ```
  69. (`core stop` / `core restart` also available. The core indexes every configured source — your
  70. Zotero data directory, your Obsidian vault, and (macOS) Apple Notes — and serves JSON-RPC on
  71. `http://0.0.0.0:23120/rpc`.)
  72. ### 2. Configure your MCP client
  73. Claude Desktop / Cursor / Cline / Qwen Code (`mcpServers`):
  74. ```json
  75. {
  76. "mcpServers": {
  77. "docsagent": {
  78. "command": "npx",
  79. "args": ["-y", "@docsagent/docsagent"]
  80. }
  81. }
  82. }
  83. ```
  84. Python shell (same tools, same contract, installed from this repo) — `mcpServers`:
  85. ```json
  86. {
  87. "mcpServers": {
  88. "docsagent-zotero-py": {
  89. "command": "docsagent-mcp"
  90. }
  91. }
  92. }
  93. ```
  94. Install the Python package first (step 1) so `docsagent-mcp` is on your PATH.
  95. On startup the shell connects to the core, loads sources, and checks index status. If the
  96. core is not running it fails fast with startup instructions — it never spawns anything.
  97. ---
  98. ## MCP Tools (external API)
  99. 8 tools, 5 read + 3 write. Schemas are the single-sourced contract in
  100. [`spec/tools/*.json`](spec/tools) (mirrored into both packages); arguments are validated
  101. before handlers run and failures map to typed docsagent error codes.
  102. ### `list_sources`
  103. Every searchable source with capabilities, supported targets/includes/browse modes,
  104. filters, and document counts. **Call this first.**
  105. Sources today: `zotero` (targets `items`, `annotations`, `notes`; collections/tags browse),
  106. `obsidian` (a vault — notes as items, folders/tags browse), and `apple-notes` (**macOS only** —
  107. the engine omits the source on other platforms). The vault is found at
  108. `~/Documents/Obsidian Vault` (override with `DOCSAGENT_OBSIDIAN_VAULT`); Apple Notes is read
  109. from the system Notes store (override with `DOCSAGENT_APPLE_NOTES_DB`).
  110. ### `search`
  111. Cross-entry search over one source (items, annotations, and notes).
  112. | Parameter | Type | Notes |
  113. |---|---|---|
  114. | `query` | string | plain keywords or phrases; required unless `mode=grep` |
  115. | `mode` | `relevance` \| `grep` | BM25 relevance by default; `grep` scans for a **literal** pattern without tokenization or ranking |
  116. | `pattern` | string, required when `mode=grep` | literal string to scan for |
  117. | `caseSensitive`, `wholeWord`, `maxMatches` | | `mode=grep` only: ASCII case folding, `[A-Za-z0-9_]` word boundaries, hit cap total |
  118. | `target` | `"items" \| "annotations" \| "notes"` or array | default `items` |
  119. | `depth` | `ids` \| `snippets` \| `full` | snippets by default (BM25-ranked passages) |
  120. | `filters` | object | `tags`, `yearFrom`/`yearTo`, `itemType`, `authors`, `colors`, `containerId`, `titleContains` |
  121. | `k`, `snippetsPerResult`, `max_tokens` | numbers | ranking depth and token budget (`mode=grep`: max documents, max hit windows per document) |
  122. Returns `results[]` with global ids (`zotero:KEY`, `obsidian:<path>`, `apple-notes:<uuid>`),
  123. titles, relevance, snippets; multi-target
  124. searches group by target. In `mode=grep` each result carries `matchCount` and `snippets[]`
  125. hit windows (`hits[]` with `line`/`column`/`offset`, and meta hits tagged with `field`),
  126. `relevance` is `0`, and the response adds `totalMatches`. Results are deduped (id, then
  127. normalized title + year) and packed under a token budget.
  128. `search` runs against `config.defaultSource` (default `zotero`). **Mixed search** is a core
  129. capability: pass `source: "all"` to the core's `search` / `grep` methods and every source is
  130. ranked independently, then fused with **reciprocal rank fusion** (k=60) — each hit is tagged
  131. with its source. BM25 scores are not comparable across corpora, so fusion is rank-based.
  132. ### `get_content`
  133. Read one entry. `mode=passages` (query-ranked passages, `k`) or `mode=fulltext`
  134. (offset pagination with `nextOffset`). Notes return their body with tags and metadata.
  135. ### `get_metadata`
  136. `include`: `metadata`, `abstract`, `annotations`, `notes`, `citation` (bibtex / csljson /
  137. formatted via `citationFormat`/`citationStyle`). Notes are packed under the token budget.
  138. ### `list_library`
  139. Browse modes: `collections` (drill-down via `parentId`), `items` (by `containerId`),
  140. `tags`, `saved_searches`, `standalone_notes`. Browse modes are per source — Zotero exposes
  141. all of these, while Obsidian and Apple Notes expose `folders` (drill-down) / `tags` / `items`.
  142. ### Write tools (three-layer safety gate)
  143. | Tool | What it does | Key arguments |
  144. |---|---|---|
  145. | `import_item` | Import local PDFs or resolve DOI / ISBN / arXiv IDs (via the Zotero translation server); optional `autoClassify` suggests collections | `paths` \| `identifiers`, `containerId`, `autoClassify`, `confirmed` |
  146. | `add_note` | Add a Markdown child note to an item (converted to Zotero note HTML), with orphan verification and rollback | `id`, `content`, `tags`, `confirmed` |
  147. | `batch_modify` | Bulk `add_to_collection` / `remove_from_collection` / `add_tags` / `remove_tags` on up to 200 items in batches of 50 | `action`, `ids`, `containerId`, `tags`, `confirmed` |
  148. Write tools target **Zotero sources only** — the Obsidian and Apple Notes sources are read-only.
  149. Write safety gate (spec/algorithms/write-gate.md): **layer 1** write tools are not
  150. registered unless `enableWrites=true`; **layer 2** `confirmed=false` returns a preview and
  151. consumes no rate-limit quota; **layer 3** confirmed writes consume a per-hour rate limit
  152. (default 30/h). Anything above 20 items in `batch_modify` additionally reports
  153. `requiresConfirmation` in the preview.
  154. ---
  155. ## Engine performance
  156. The C++ engine powers [PapersGPT](https://www.papersgpt.com) — the same index and
  157. retrieval stack ships in this MCP server. Benchmark on a real Zotero installation
  158. ([full write-up](https://www.papersgpt.com/en/blogs/papersgpt-search-performance-benchmark)):
  159. | Metric | Mac (Intel i9) | Windows VM (4C8G) |
  160. |---|---|---|
  161. | Library size | 1,506 PDFs (4.5 GB on disk) | 500+ PDFs |
  162. | **Index build time** | **141 s** | a few seconds |
  163. | **Memory (agent process)** | **227 MB** | **160 MB** |
  164. | **Average retrieval latency** | **~15 ms** | **~15 ms** |
  165. - Indexing cost scales roughly **linearly** with library size; retrieval latency stays
  166. **constant** — a 10,000-paper library (~30 GB) indexes in about 15–20 minutes, and
  167. everyday search stays at **~15 ms**.
  168. - For comparison: a typical web page load takes 1,000–3,000 ms; a blink of an eye is
  169. 100–150 ms. PapersGPT answers in ~15 ms, fully offline.
  170. - Privacy: your library never leaves your machine.
  171. ## Configuration
  172. Config lives at `~/.docsagent/config.json` (or `$DOCSAGENT_CONFIG`) — one file shared by
  173. the JS shell, the Python wrapper, and the C++ core. Validated against
  174. [`spec/config.json`](spec/config.json).
  175. | Key | Default | Description |
  176. |---|---|---|
  177. | `coreHost` | `0.0.0.0` | Address the core binds and the shell dials |
  178. | `httpPort` | `23120` | Core HTTP port (`POST /rpc`) |
  179. | `coreBinary` | `""` | Optional explicit path to the core binary |
  180. | `zoteroDataDir` | `~/Zotero` | Zotero data directory |
  181. | `zoteroApiUrl` | `http://localhost:23119/api` | Zotero local API (write orchestration) |
  182. | `zoteroGroups` | `[]` | Group libraries to sync from zotero.org |
  183. | `enableWrites` | `false` | Register the three write tools |
  184. | `writeRateLimitPerHour` | `30` | Confirmed-write rate limit |
  185. | `maxTokensPerTool` | `4000` | Token budget per tool result |
  186. | `defaultSource` | `zotero` | Source the shell searches and resolves id prefixes in (`zotero`, `obsidian`, `apple-notes`) |
  187. | `transport` | `stdio` | `stdio` or `streamable-http` |
  188. | `httpListenAddr` | `0.0.0.0:8080` | Listen address for streamable-http (`/mcp`) |
  189. | `authMode` / `authConfig` | `none` | `api-key` or `oauth2` (RFC 7662) + `allowedOrigins` |
  190. | `rbacRoles` | `{}` | role → allowed tool names (per-request RBAC on HTTP) |
  191. | `logLevel` | `info` | `debug` / `info` / `warn` / `error` |
  192. ---
  193. ## Distribution
  194. | Channel | Package | Bundled core | Size |
  195. |---|---|---|---|
  196. | npm (JS/TS shell) | `@docsagent/docsagent` | all platforms in `bin/` | ~70 MB tarball |
  197. | PyPI (Python shell) | `docsagent-mcp` (`pip install ./python`) | same binaries in the wheel | ~65 MB wheel |
  198. Bundled core platforms: **macOS** universal (Intel + Apple Silicon), **Windows** x64
  199. (x86_64), **Linux** x64 (x86_64) — Linux ARM is **not** supported. Source availability:
  200. Zotero and Obsidian work on every platform; **Apple Notes is macOS-only** (`list_sources`
  201. omits it elsewhere).
  202. Both shells read the same config and talk to the same core — pick either (or both) as
  203. your MCP distribution channel. Core lifecycle (`start` / `stop` / `restart` / `status`)
  204. is available from both CLIs.
  205. ## Links
  206. - [DocsAgent for iPhone](https://apps.apple.com/us/app/docsagent/id6829574595) — App Store
  207. - [docsagent.app](https://www.docsagent.app) — website, setup guide, support
  208. - [spec/](spec/) — the single-sourced contract: 8 tool schemas, 23 JSON-RPC methods,
  209. error codes + suggested calls, config schema
  210. - [PapersGPT search performance benchmark](https://www.papersgpt.com/en/blogs/papersgpt-search-performance-benchmark)
  211. - [Zotero](https://www.zotero.org/) · [Model Context Protocol](https://modelcontextprotocol.io)
  212. ## License
  213. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.