convez.ai
MCP ServerIntegração & APIsIntermediário
scriptkid23

DocGraph

scriptkid23/docgraph

RAG local com embeddings ONNX — indexe e consulte documentos no Cursor

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP local de RAG (Retrieval-Augmented Generation) para Cursor que permite fazer upload de arquivos e URLs, indexá-los com um embedder Rust/ONNX rodando localmente, e consultá-los sem enviar dados para a nuvem. Inclui interface web para gerenciamento de documentos e suporte a múltiplos idiomas.

Instalação

$npx convez-ai scriptkid23/docgraph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 1 dia
Versão
v1.0.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Consultar documentação técnica local do seu projeto via Cursor
  • Indexar bases de conhecimento internas sem exposição em nuvem
  • Integrar repositórios de URLs e arquivos como contexto para LLM
  • Construir assistentes de IA privados que consomem dados locais

Veredito

Solução robusta e madura para RAG privado integrado ao Cursor. Excelente para quem prioriza privacidade e quer evitar chamadas à nuvem; requer setup técnico (Docker/Rust) mas é bem documentado e rápido em produção.

README

A tradução para o português deste README ainda está na fila.

DocGraph

Local document RAG server for Cursor via MCP. Upload files or import URLs, index them with a local Rust embedder (ONNX, no Ollama or cloud key required), and query them from Cursor through the /document skill.

  • Web UI — upload files, import URLs, and manage documents
  • MCP server — search_documents, list_documents, get_document exposed to Cursor
  • Local embeddings — fast ONNX embedder written in Rust; nothing leaves your machine

Quick start with Docker (recommended)

No need to install Python, Poetry, Rust, or Node — just run Docker.

docker compose up --build

Or with plain Docker:

docker build -t docgraph .
docker run -p 8088:8088 -v docgraph-data:/data docgraph

Then open:

Notes:

  • The first build is slow (it compiles the Rust embedder and downloads dependencies); later builds are cached.
  • The first run downloads the ONNX model (~100MB) into the /data volume; later runs reuse it.
  • All data (sqlite db, Chroma index, uploaded files, model cache) is persisted in the docgraph-data volume, so it survives restarts.
  • For non-English documents, set DOCGRAPH_LOCAL_MODEL=multilingual-e5-base (uncomment it in docker-compose.yml) and re-index.

Manual install (for development)

Prerequisites

Install

poetry install
pip install maturin
cd crates/docgraph-embed && maturin develop --release && cd ../..

Poetry-only setup (no global pip install):

poetry install
poetry add --group dev maturin
poetry run maturin develop --release -m crates/docgraph-embed/Cargo.toml

First run downloads the ONNX model (~100MB) to ~/.docgraph/models.

Windows troubleshooting: maturin develop cannot overwrite module in use

If maturin develop fails with a message about pip could not overwrite the installed extension module and a leftover directory like ~ocgraph_embed, another Python process is still holding the old compiled extension.

  1. Stop all Python processes that may have imported docgraph_embed (for example, old docgraph serve terminals).
  2. Delete the leftover directory in the Poetry venv site-packages (for example, .../Lib/site-packages/~ocgraph_embed).
  3. Re-run:
poetry run maturin develop --release -m crates/docgraph-embed/Cargo.toml

Optional extras

poetry install -E openai   # cloud embedding instead of local/ollama
poetry install -E crawl    # import URLs via crawl4ai

For URL import, install the crawl extra and set up the browser:

poetry install -E crawl
poetry run crawl4ai-setup
# or: python -m playwright install chromium

Run

poetry run docgraph serve

Keep this terminal running while using Cursor.

Web UI development (React + Vite)

The UI uses a Minimalist Monochrome design system (Playfair Display, Source Serif 4, JetBrains Mono; pure black/white; sharp corners; line-based progress).

cd frontend
npm install
npm run dev          # http://127.0.0.1:5173 — proxies /api → :8088
npm run build        # output → docgraph/web/static/

Design tokens live in frontend/src/styles/. Run npm run build after UI changes.


Cursor MCP configuration

Add to your Cursor MCP settings (Settings → MCP or .cursor/mcp.json).

Recommended — run the server separately, connect via HTTP (start the server, via Docker or docgraph serve, first):

{
  "mcpServers": {
    "docgraph": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "http://127.0.0.1:8088/mcp/sse"]
    }
  }
}

Alternative — let Cursor launch the process (stdio):

{
  "mcpServers": {
    "docgraph": {
      "command": "poetry",
      "args": ["run", "docgraph", "serve", "--stdio"],
      "cwd": "/path/to/docgraph"
    }
  }
}

Replace /path/to/docgraph with the absolute path to this repository on your machine.


/document skill

Copy skills/document/SKILL.md to your Cursor skills directory:

  • Global: ~/.cursor/skills/document/SKILL.md
  • Project: .cursor/skills/document/SKILL.md

Then in Cursor chat:

/document How do I configure the embedding provider?
/document --folder docs --tag v2 What is DocGraph v2?

MCP tools

ToolDescription
search_documentsSemantic search over indexed documents
list_documentsList documents with optional filters
get_documentGet full converted markdown for a document

Configuration

Env VariableDefaultDescription
DOCGRAPH_DATA_DIR~/.docgraph (/data in Docker)Data directory
DOCGRAPH_WEB_HOST127.0.0.1 (0.0.0.0 in Docker)Bind address for the Web UI / MCP server
DOCGRAPH_WEB_PORT8088Web UI port
DOCGRAPH_EMBED_PROVIDERlocallocal, ollama, or openai
DOCGRAPH_LOCAL_MODELnomic-embed-textLocal ONNX (English, 768-dim). For multilingual: multilingual-e5-base
DOCGRAPH_OLLAMA_URLhttp://127.0.0.1:11434Ollama endpoint when provider=ollama
DOCGRAPH_OLLAMA_EMBED_MODELnomic-embed-text:latestOllama embedding model
DOCGRAPH_CRAWL_TIMEOUT_SEC30Per-URL crawl timeout
DOCGRAPH_MAX_URLS_PER_IMPORT50Max URLs per import batch
DOCGRAPH_MAX_CHUNKS_PER_DOC5000Hard cap on chunks per document (oversize → ERROR)
DOCGRAPH_TOKENIZER_SOURCEautoauto, char-ratio, or tiktoken
DOCGRAPH_HEADING_PREFIXtruePrepend heading breadcrumb to markdown chunks
DOCGRAPH_ATOMIC_BLOCKStrueKeep code fences and tables atomic when chunking
DOCGRAPH_CODE_CHUNKERregexregex or treesitter (requires poetry install -E treesitter)
DOCGRAPH_DEDUP_ENABLEDtrueSkip duplicate chunk text within a document
DOCGRAPH_MMR_LAMBDA0.7MMR diversity (1.0 = pure relevance)
DOCGRAPH_HYBRID_ENABLEDtrueEnable hybrid search (vector + BM25/FTS5)
DOCGRAPH_RRF_K60Reciprocal Rank Fusion constant
DOCGRAPH_RERANK_ENABLEDtrueEnable cross-encoder reranker (poetry install -E rerank)
DOCGRAPH_RERANK_MODELbge-reranker-v2-m3Reranker model (fastembed)
DOCGRAPH_RERANK_TOP_N4Number of candidates passed to the reranker. Each candidate ≈ 700ms cross-encoder forward pass on CPU — see benchmarks/README.md
DOCGRAPH_RERANK_TIMEOUT_SEC3.0Per-call rerank timeout (falls back to RRF order on timeout)
DOCGRAPH_RERANK_PREWARMtrueWarm up reranker model at server startup
DOCGRAPH_RERANK_SCORE_GAP_RATIO0.5Skip rerank when top-1 RRF dominates by this ratio
DOCGRAPH_RERANK_MIN_FLOOR0.015Skip rerank when top-1 RRF score is below this floor

File watcher (roadmap 3.1)

Auto-indexes files in user-configured directories. Runtime-toggleable via Web UI, CLI, or HTTP API — no restart needed.

Quick start — Web UI

Open http://127.0.0.1:8088, switch to the Folder watch tab (4th tab in the Ingest section):

  1. Fill in the Add directory form (path, folder, tags, optional ignore globs) → submit. Form rejects non-existent paths inline.
  2. Click Enable watcher in the status bar.
  3. Watched docs appear in the Documents table with a [WATCHED] badge. Hover the badge to see the full source path.
  4. Click Reconcile any time you suspect drift (e.g. after a batch edit on disk) — forces a disk-vs-DB delta scan.
  5. Remove a watched dir inline; choose to keep the indexed docs as orphans or delete them too.

The status bar polls /api/watch/status every 2s while enabled, 5s while disabled.

Quick start — CLI

# Add a watched directory (server must be running)
docgraph watch add ~/Notes --folder notes --tags personal

# Turn the watcher on
docgraph watch enable

# Check what it's doing
docgraph watch status

# Turn it off (paths persist; re-enable later picks them up)
docgraph watch disable

How it works

  • Text files (.md, .py, .rs, .json, etc.) are referenced in place — no duplicate copy in data_dir.
  • Binary files (.pdf, .docx, .pptx, .xlsx, …) are copied into data_dir/files/originals/ as a snapshot at index time; the converted markdown is cached and regenerated only when the source file's mtime changes.
  • Unknown extensions are skipped silently. Extend via DOCGRAPH_WATCH_EXTRA_TEXT_EXTS / DOCGRAPH_WATCH_EXTRA_BINARY_EXTS.

Ignore patterns

Three layers compose:

  1. Hardcoded defaults — .git, node_modules, __pycache__, .venv, .DS_Store, *.pyc, *.swp, *~, etc.
  2. .docgraphignore at each watched-dir root — gitignore syntax (minus negation). Reloaded on its own mtime.
  3. Per-dir ignore_globs from the add-dir API/CLI.

Watched vs uploaded

A file at the same path can exist as two separate docs if you both upload it via POST /api/documents and watch its directory. They have independent lifecycles. Watcher docs use source_type=watched; upload docs use source_type=file.

Config knobs

Env varYAML keyDefaultPurpose
DOCGRAPH_WATCH_DEBOUNCE_SECwatch.debounce_sec2.0Per-path debounce window before enqueueing
DOCGRAPH_WATCH_QUEUE_CAPACITYwatch.queue_capacity500Aggregate cap across per-worker queues
DOCGRAPH_WATCH_WORKERSwatch.workers4Number of async ingest workers
DOCGRAPH_WATCH_RECOVERY_INTERVAL_SECwatch.recovery_interval_sec600Periodic reconcile (fsevents-drop backstop)
DOCGRAPH_WATCH_EXTRA_TEXT_EXTSwatch.extra_text_exts[]Extra extensions to treat as native text
DOCGRAPH_WATCH_EXTRA_BINARY_EXTSwatch.extra_binary_exts[]Extra extensions to convert as binary

HTTP API

MethodPathPurpose
GET/api/watch/statusSnapshot of watcher state, stats, queue depth
POST/api/watch/enableStart observer + workers, run reconcile
POST/api/watch/disableStop observer, cancel workers, drain queue
GET/api/watch/dirsList watched dirs (with per-dir doc count)
POST/api/watch/dirsAdd a dir: body {path, folder, tags, ignore_globs}
DELETE/api/watch/dirs/{wd_id}Remove a dir (optional ?delete_docs=true)
POST/api/watch/reconcileManual reconcile across all dirs (watcher must be enabled)

Inside Docker

Docker volumes are declared at container creation, so the watcher inside the container can only see directories that have been bind-mounted into it. The easiest pattern is to mount your home directory read-only once, then add any subfolder runtime without restarting the container:

# docker-compose.yml
volumes:
  - docgraph-data:/data
  - ${HOME}:/host:ro      # entire home, read-only

docker compose up -d, then in the Web UI's Folder watch tab, add paths under /host/...:

Host pathIn-container path you type in the form
~/Notes/host/Notes
~/Projects/myapp/host/Projects/myapp

Read-only mounts are safe — watcher only reads files (spec §8.7 forbids writing user-owned paths). State (watched_dirs, docs, indexes) persists in docgraph-data, so container restarts are state-preserving.

For a stricter setup, mount specific folders individually:

volumes:
  - docgraph-data:/data
  - ${HOME}/Notes:/watched/notes:ro
  - ${HOME}/Projects/docgraph:/watched/code:ro

Then use /watched/notes etc. in the form. Trade-off: adding a new path later requires editing compose + docker compose up -d.

On macOS / Windows Docker Desktop, fsevents propagation through the VirtIOFS/gRPC FUSE layer can sometimes lag. The 10-minute recovery reconcile (config knob DOCGRAPH_WATCH_RECOVERY_INTERVAL_SEC) is the backstop; you can also click Reconcile in the UI for an immediate sync.

Known limitations

  • Symlinks are not followed (would risk indexing loops). Documented.
  • macOS fsevents can drop events under burst — the 10-minute recovery reconcile backstops this.
  • Watcher does not auth its endpoints — they inherit whatever auth ships when roadmap 3.4 lands.
  • Docker bind mounts are static — adding a new mount path (when not using the ${HOME}:/host:ro pattern) requires docker compose up -d to recreate the container.

Re-index after changing chunk settings:

poetry run docgraph reindex --all
# or inside Docker:
docker compose exec docgraph docgraph reindex --all

See the chunker improvements spec.


Troubleshooting

"Hybrid search returns vector-only results" The FTS5 index hasn't been populated (e.g., after upgrading from a pre-hybrid version).

  • Automatic: server startup detects an empty FTS index and rebuilds in the background.
  • Manual: poetry run docgraph rebuild-fts.

"Reranker reports disabled / error" Check GET /api/health field rerank_status:

  • error — reranker construction failed. Rebuild the Rust crate inside the Poetry venv:
    env -u CONDA_PREFIX -u CONDA_DEFAULT_ENV -u CONDA_SHLVL -u CONDA_PROMPT_MODIFIER \
      poetry run maturin develop --release \
      --manifest-path crates/docgraph-embed/Cargo.toml
    
  • loading — wait 5–10s; the BGE model is downloading on first use (~600MB).
  • disabled — set DOCGRAPH_RERANK_ENABLED=true or enable it in the YAML config.

"First search after startup is slow (~10s)" Reranker cold-start. rerank_prewarm=true (default) warms the model in the background at server start; if the first query is still slow, check the server log for prewarm errors.

Test

poetry run pytest tests/ -v
poetry run pytest tests/ -m integration -v   # optional: live embedder / Ollama
Ver o original no GitHub

Bom para

Relacionados