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.
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
Markdown
[](/listings/docsagent--docsagent)HTML
<a href="/listings/docsagent--docsagent"><img src="/api/listings/docsagent--docsagent/badge.svg" alt="findsafeskills safety rating" /></a>Install
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.
- ---
- name: docsagent
- 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.
- ---
- # DocsAgent Skill
- DocsAgent is a local-first documentation engine designed to perform lightning-fast **hybrid search** (text and semantic search) over your private local files.
- ## Key Features
- - **Privacy-First**: All indexing and searching happen 100% locally on your machine. No documents or data ever leave your system.
- - **Hybrid Search**: Combines semantic and keyword-based text search for high accuracy.
- - **Supported Formats**: Optimized for **PDF, PPTX, and DOCX** files.
- - **No Web Dependency**: This tool does not perform web searches. It relies on a local index you create.
- ## Privacy Guarantee
- * **100% Local**: All processing, indexing, and search operations are performed entirely on your machine.
- * **Zero Data Leakage**: No data is sent to external servers. Your documents remain private.
- ## When to use
- - Use this when searching for information within your own private documentation, research papers, reports, or presentations.
- - Do not use this for general internet queries, news, or public website information.
- ## Installation
- DocsAgent is a CLI toolkit, when you install the global `docsagent` package, You can directly use 'docsagent' command.
- ```bash
- npm install -g @docsagent/docsagent
- ```
- For more information, please see https://github.com/docsagent/docsagent.
- ## Usage Guidelines
- ### 1. Add Documentation
- Adds directory or file paths (PDF, DOCX, PPTX) to the index. You can pass multiple paths at once.
- ```bash
- # Add a single directory
- docsagent add ./documents/manuals
- # Add multiple files and directories at once
- docsagent add ./reports/q1.pdf ./presentation.pptx ./notes/meeting-files
- ```
- * **Use case**: Use to index folders or specific private files for searchability.
- ### 2. Search Documents
- Performs a hybrid search (text + semantic) across your indexed private documents.
- ```bash
- # Search for a specific topic
- docsagent search "how to configure local encryption"
- # Search for technical concepts
- docsagent search "API authentication process"
- ```
- The tool returns the most relevant snippets with their source paths and scores.
- * **Important**: Ensure your documents have been indexed using the `add` operation before searching.
- ### 3. List Indexed Sources
- Lists all files currently being monitored or indexed.
- ```bash
- docsagent list
- ```
- ### 4. Check Status
- Shows the indexing progress and service health.
- ```bash
- docsagent status
- ```
- ### 5. Stop Agent
- Stops the indexing service.
- ```bash
- docsagent stop
- ```
- ## Workflow: Answering Questions from Local Docs
- 1. **Check Index**: If unsure if the documents are indexed, you can try a `search` first.
- 2. **Search**: Execute `search` with a specific query derived from the user's request.
- 3. **Analyze**: Review the context returned. If multiple snippets are found, synthesize them into a coherent answer.
- 4. **Cite Sources**: Always mention the file path and page number (if available) in your response.
- ## Error Handling
- - If `search` returns "No results found", inform the user and ask if they want to index a specific directory using `add`.
- - 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.
- # DocsAgent MCP — Zotero, Obsidian & Apple Notes for AI agents 📚⚡
- [](https://apps.apple.com/us/app/docsagent/id6829574595)
- [](https://www.docsagent.app)
- [](LICENSE)
- **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](python/) ship the same tools over the same JSON-RPC contract.
- > 📱 **On the go?** [**DocsAgent for iPhone**](https://apps.apple.com/us/app/docsagent/id6829574595) —
- > your Zotero library in your pocket, with AI chat. Free on the App Store.
- ---
- ## 📱 DocsAgent for iPhone
- Same library, smaller screen. The iPhone app turns your Zotero library into **pocket Zotero** —
- ask any paper anything while you're away from your desk.
- - **Search everything** — titles, authors, and full text across your whole library
- - **Chat with papers** — grounded answers that cite the exact passage
- - **Private by design** — no account, no sign-in, your library stays on your devices
- - **Pairs with the Mac companion** — scan a pairing code once, no computer needed afterwards
- **[Download on the App Store →](https://apps.apple.com/us/app/docsagent/id6829574595)**
- Free · iOS 16 or newer · Not yet available in mainland China or the EU
- Also available on the web: [docsagent.app](https://www.docsagent.app)
- ---
- ## 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/](spec/).
- ---
- ## Quick Start
- ### 1. Start the core
- ```bash
- 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):
- ```bash
- 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`):
- ```json
- {
- "mcpServers": {
- "docsagent": {
- "command": "npx",
- "args": ["-y", "@docsagent/docsagent"]
- }
- }
- }
- ```
- Python shell (same tools, same contract, installed from this repo) — `mcpServers`:
- ```json
- {
- "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.
- ---
- ## MCP Tools (external API)
- 8 tools, 5 read + 3 write. Schemas are the single-sourced contract in
- [`spec/tools/*.json`](spec/tools) (mirrored into both packages); arguments are validated
- before handlers run and failures map to typed docsagent error codes.
- ### `list_sources`
- Every searchable source with capabilities, supported targets/includes/browse modes,
- filters, and document counts. **Call this first.**
- Sources today: `zotero` (targets `items`, `annotations`, `notes`; collections/tags browse),
- `obsidian` (a vault — notes as items, folders/tags browse), and `apple-notes` (**macOS only** —
- the engine omits the source on other platforms). The vault is found at
- `~/Documents/Obsidian Vault` (override with `DOCSAGENT_OBSIDIAN_VAULT`); Apple Notes is read
- from the system Notes store (override with `DOCSAGENT_APPLE_NOTES_DB`).
- ### `search`
- Cross-entry search over one source (items, annotations, and notes).
- | Parameter | Type | Notes |
- |---|---|---|
- | `query` | string | plain keywords or phrases; required unless `mode=grep` |
- | `mode` | `relevance` \| `grep` | BM25 relevance by default; `grep` scans for a **literal** pattern without tokenization or ranking |
- | `pattern` | string, required when `mode=grep` | literal string to scan for |
- | `caseSensitive`, `wholeWord`, `maxMatches` | | `mode=grep` only: ASCII case folding, `[A-Za-z0-9_]` word boundaries, hit cap total |
- | `target` | `"items" \| "annotations" \| "notes"` or array | default `items` |
- | `depth` | `ids` \| `snippets` \| `full` | snippets by default (BM25-ranked passages) |
- | `filters` | object | `tags`, `yearFrom`/`yearTo`, `itemType`, `authors`, `colors`, `containerId`, `titleContains` |
- | `k`, `snippetsPerResult`, `max_tokens` | numbers | ranking depth and token budget (`mode=grep`: max documents, max hit windows per document) |
- Returns `results[]` with global ids (`zotero:KEY`, `obsidian:<path>`, `apple-notes:<uuid>`),
- titles, relevance, snippets; multi-target
- searches group by target. In `mode=grep` each result carries `matchCount` and `snippets[]`
- hit windows (`hits[]` with `line`/`column`/`offset`, and meta hits tagged with `field`),
- `relevance` is `0`, and the response adds `totalMatches`. Results are deduped (id, then
- normalized title + year) and packed under a token budget.
- `search` runs against `config.defaultSource` (default `zotero`). **Mixed search** is a core
- capability: pass `source: "all"` to the core's `search` / `grep` methods and every source is
- ranked independently, then fused with **reciprocal rank fusion** (k=60) — each hit is tagged
- with its source. BM25 scores are not comparable across corpora, so fusion is rank-based.
- ### `get_content`
- Read one entry. `mode=passages` (query-ranked passages, `k`) or `mode=fulltext`
- (offset pagination with `nextOffset`). Notes return their body with tags and metadata.
- ### `get_metadata`
- `include`: `metadata`, `abstract`, `annotations`, `notes`, `citation` (bibtex / csljson /
- formatted via `citationFormat`/`citationStyle`). Notes are packed under the token budget.
- ### `list_library`
- Browse modes: `collections` (drill-down via `parentId`), `items` (by `containerId`),
- `tags`, `saved_searches`, `standalone_notes`. Browse modes are per source — Zotero exposes
- all of these, while Obsidian and Apple Notes expose `folders` (drill-down) / `tags` / `items`.
- ### Write tools (three-layer safety gate)
- | Tool | What it does | Key arguments |
- |---|---|---|
- | `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` |
- | `add_note` | Add a Markdown child note to an item (converted to Zotero note HTML), with orphan verification and rollback | `id`, `content`, `tags`, `confirmed` |
- | `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` |
- Write tools target **Zotero sources only** — the Obsidian and Apple Notes sources are read-only.
- Write safety gate (spec/algorithms/write-gate.md): **layer 1** write tools are not
- registered unless `enableWrites=true`; **layer 2** `confirmed=false` returns a preview and
- consumes no rate-limit quota; **layer 3** confirmed writes consume a per-hour rate limit
- (default 30/h). Anything above 20 items in `batch_modify` additionally reports
- `requiresConfirmation` in the preview.
- ---
- ## Engine performance
- The C++ engine powers [PapersGPT](https://www.papersgpt.com) — the same index and
- retrieval stack ships in this MCP server. Benchmark on a real Zotero installation
- ([full write-up](https://www.papersgpt.com/en/blogs/papersgpt-search-performance-benchmark)):
- | Metric | Mac (Intel i9) | Windows VM (4C8G) |
- |---|---|---|
- | Library size | 1,506 PDFs (4.5 GB on disk) | 500+ PDFs |
- | **Index build time** | **141 s** | a few seconds |
- | **Memory (agent process)** | **227 MB** | **160 MB** |
- | **Average retrieval latency** | **~15 ms** | **~15 ms** |
- - Indexing cost scales roughly **linearly** with library size; retrieval latency stays
- **constant** — a 10,000-paper library (~30 GB) indexes in about 15–20 minutes, and
- everyday search stays at **~15 ms**.
- - For comparison: a typical web page load takes 1,000–3,000 ms; a blink of an eye is
- 100–150 ms. PapersGPT answers in ~15 ms, fully offline.
- - Privacy: your library never leaves your machine.
- ## Configuration
- Config lives at `~/.docsagent/config.json` (or `$DOCSAGENT_CONFIG`) — one file shared by
- the JS shell, the Python wrapper, and the C++ core. Validated against
- [`spec/config.json`](spec/config.json).
- | Key | Default | Description |
- |---|---|---|
- | `coreHost` | `0.0.0.0` | Address the core binds and the shell dials |
- | `httpPort` | `23120` | Core HTTP port (`POST /rpc`) |
- | `coreBinary` | `""` | Optional explicit path to the core binary |
- | `zoteroDataDir` | `~/Zotero` | Zotero data directory |
- | `zoteroApiUrl` | `http://localhost:23119/api` | Zotero local API (write orchestration) |
- | `zoteroGroups` | `[]` | Group libraries to sync from zotero.org |
- | `enableWrites` | `false` | Register the three write tools |
- | `writeRateLimitPerHour` | `30` | Confirmed-write rate limit |
- | `maxTokensPerTool` | `4000` | Token budget per tool result |
- | `defaultSource` | `zotero` | Source the shell searches and resolves id prefixes in (`zotero`, `obsidian`, `apple-notes`) |
- | `transport` | `stdio` | `stdio` or `streamable-http` |
- | `httpListenAddr` | `0.0.0.0:8080` | Listen address for streamable-http (`/mcp`) |
- | `authMode` / `authConfig` | `none` | `api-key` or `oauth2` (RFC 7662) + `allowedOrigins` |
- | `rbacRoles` | `{}` | role → allowed tool names (per-request RBAC on HTTP) |
- | `logLevel` | `info` | `debug` / `info` / `warn` / `error` |
- ---
- ## Distribution
- | Channel | Package | Bundled core | Size |
- |---|---|---|---|
- | npm (JS/TS shell) | `@docsagent/docsagent` | all platforms in `bin/` | ~70 MB tarball |
- | PyPI (Python shell) | `docsagent-mcp` (`pip install ./python`) | same binaries in the wheel | ~65 MB wheel |
- Bundled core platforms: **macOS** universal (Intel + Apple Silicon), **Windows** x64
- (x86_64), **Linux** x64 (x86_64) — Linux ARM is **not** supported. Source availability:
- Zotero and Obsidian work on every platform; **Apple Notes is macOS-only** (`list_sources`
- omits it elsewhere).
- Both shells read the same config and talk to the same core — pick either (or both) as
- your MCP distribution channel. Core lifecycle (`start` / `stop` / `restart` / `status`)
- is available from both CLIs.
- ## Links
- - [DocsAgent for iPhone](https://apps.apple.com/us/app/docsagent/id6829574595) — App Store
- - [docsagent.app](https://www.docsagent.app) — website, setup guide, support
- - [spec/](spec/) — the single-sourced contract: 8 tool schemas, 23 JSON-RPC methods,
- error codes + suggested calls, config schema
- - [PapersGPT search performance benchmark](https://www.papersgpt.com/en/blogs/papersgpt-search-performance-benchmark)
- - [Zotero](https://www.zotero.org/) · [Model Context Protocol](https://modelcontextprotocol.io)
- ## License
- Apache-2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.