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.

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.

# 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.

# 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.

docsagent list

4. Check Status

Shows the indexing progress and service health.

docsagent status

5. Stop Agent

Stops the indexing service.

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.

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

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.

MCP Tools (external API)

8 tools, 5 read + 3 write. Schemas are the single-sourced contract in spec/tools/*.json (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).

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)

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 — the same index and retrieval stack ships in this MCP server. Benchmark on a real Zotero installation (full write-up):

• 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.