Drop your documents into a folder, run the indexer, and get a production-grade RAG pipeline with an MCP server — any MCP-compatible AI assistant (Claude Code, OpenClaw, Claude Desktop, Cursor, etc.) can search your documents with a single config entry.
The app needs no GPU. LiteLLM routes OCR/vision to cloud APIs, local
models, or fallback chains.
RAG pipeline for documents (Markdown, PDF, images). 10-step hybrid search, LLM enrichment, taxonomy, MCP server. Cloud or local.
Estrelas
4
Ferramentas
—
Disponibilidade
—
Use cases
Personal knowledge base — Index your notes, PDFs, documents, images, audio, and video. Ask your AI assistant questions and get answers grounded in your own files.
Company document search — Drop legal contracts, reports, SOPs into a folder. Employees search via any MCP-compatible assistant with metadata filters (by department, doc type, date, tags).
Research assistant — Index papers, datasets, and notes. Search by meaning, not just keywords. LLM enrichment auto-extracts entities, topics, and key facts.
Obsidian / Markdown vault — Works with any markdown source (Obsidian, HackMD, Notion exports, GitBook). Extracts YAML frontmatter for rich filtering.
PDF-heavy workflows — Scanned PDFs get OCR automatically. Page-aware chunking keeps context intact. Metadata (author, dates, page count) extracted from PDF properties.
Multi-agent tool — Expose your document collection as 16 MCP tools. Multiple agents can search, browse, filter, and manage taxonomy concurrently.
Local Deep Research integration — Let LDR run agentic web/academic research while searching this RAG index through a LangChain retriever. See Local Deep Research Integration.
Self-hosting? Prefer routing LiteLLM's ocr and vision aliases to local
models. The legacy direct-provider profile remains available via
cp config.local.yaml.example config.yaml; see Local mode.
3. Add API keys
Create a .env file in the project root:
LITELLM_API_KEY=... # OCR/vision proxy (preferred)
# LITELLM_MASTER_KEY=... # alternative when LITELLM_API_KEY is unset
OPENROUTER_API_KEY=sk-or-... # embeddings + enrichment — https://openrouter.ai/keys
DEEPINFRA_API_KEY=... # reranker — https://deepinfra.com/dash/api_keys
4. Build the index
python run_index.py
This scans your documents, extracts text (Markdown, PDFs, images, audio, video), generates embeddings, and writes everything to a LanceDB index. Prefect auto-starts a temporary server for flow/task logging — dashboard at http://127.0.0.1:4200.
5. Connect your AI assistant
The MCP server gives any compatible AI assistant access to your documents via tools like file_search, file_status, and file_recent. The assistant launches the server automatically — you just add a config entry.
Claude Code
Add to your project's .mcp.json (or ~/.claude.json for global access):
The pattern is the same for Cursor, Windsurf, or any tool that supports MCP stdio servers. Point command at the venv Python and args at mcp_server.py. API keys are loaded from the .env file automatically — no need to pass them in the MCP config.
HTTP mode (remote / non-MCP clients)
python mcp_server.py --http
# Listens on 0.0.0.0:7788
VPS / Docker deployment
Run as a standalone HTTP server on any VPS or container platform. ML inference
uses configured APIs and the LiteLLM proxy, so the app container needs no GPU.
Override documents path (default: from config.yaml)
INDEX_ROOT
Override index path (default: from config.yaml)
PORT
Server port (default: 7788)
API_KEY
Bearer token for HTTP auth. No auth when unset.
LITELLM_API_KEY
Preferred LiteLLM OCR/vision bearer credential
LITELLM_MASTER_KEY
LiteLLM credential fallback when LITELLM_API_KEY is unset
When API_KEY is set, all HTTP requests must include Authorization: Bearer <API_KEY>. See config.vps.yaml.example for VPS-specific config.
Render.com: One-click deploy with render.yaml — persistent disk at /data, auto-generated API key.
REST API (file management)
When running in HTTP mode (--http or server.py), a REST API is available alongside the MCP server for uploading, downloading, and listing documents. Auth uses the same API_KEY bearer token.
Upload a file:
curl -X POST http://localhost:7788/api/upload \
-H "Authorization: Bearer $API_KEY" \
-F "[email protected]" \
-F "directory=2-Area/Legal"
# -> {"uploaded": true, "rel_path": "2-Area/Legal/report.pdf", "doc_id": "2-Area/Legal/report.pdf", "size": 84521}
# "rel_path" is the path under documents_root; "doc_id" is a deprecated alias of
# it (it was never an index doc id) and will be dropped — read "rel_path".
Accept a document and receive its persistent ID immediately:
Acceptance publishes complete bytes, registers identity, and durably queues targeted
indexing. It runs no extraction, enrichment, or embedding. The configured scheduler
drains the existing queue asynchronously; with the scheduler disabled, run the usual
index drain/sweep. The file must be eligible under its filesystem source's scan rules
to become searchable. Registration alone is not proof of indexing.
Use the same Idempotency-Key, filename, directory and bytes when retrying an
interrupted request: the original receipt and ID are replayed. Reusing a key with
different inputs returns 409. Without a key, each request accepts a new document.
The receipt records the accepted revision; later file edits or moves do not change
that historical hash/path. Resolve the ID again and verify bytes before later reuse.
Existing files are never overwritten. Client-supplied @XXXXX@ tokens are stripped
before assigning a fresh identity. If an empty/rebuilt registry has surviving IDs
in filesystem-source filenames, acceptance returns 409 until an identity scan has
recovered them; it never consumes a surviving legacy ID. Private .organizer-accept-* staging names are
reserved: scans recover journaled acceptance before assigning IDs and remove orphan
staging left by interrupted requests. Indexing and acceptance share an identity lock
only during scans/publication, not during provider calls.
Upload a file (multipart form: file + optional directory)
/api/documents/accept
POST
Accept/register bytes, return real ID/hash, queue indexing; optional Idempotency-Key
/api/documents/{rel_path}
GET
Download a file by its path under documents_root
/api/documents/
GET
List files (query params: directory, limit, offset)
Constraints: Max upload 100 MB. Allowed types: .md, .pdf, .png, .jpg, .jpeg. Path traversal is blocked. After uploading, run file_index_update (via MCP) to index the new document.
Local mode (optional)
Preferred local OCR deployment keeps the primary config and routes LiteLLM's
ocr and vision aliases to local models; LiteLLM can retain cloud fallbacks.
For the legacy direct-provider self-hosted profile:
Copy config.local.yaml.example to config.yaml
Install and start Ollama: brew install ollama && ollama serve
Start DeepSeek OCR2 on port 8790 (for PDF/image OCR)
That profile runs OCR, embeddings, enrichment, and reranking locally. Its
enabled media provider still uses OpenRouter; set OPENROUTER_API_KEY or
disable media.
Hybrid search — Every query runs vector (semantic) and keyword (BM25) search in parallel, fuses results with Reciprocal Rank Fusion, applies length normalization, importance weighting, optional recency boost with time decay floor, cross-encoder reranking (60/40 blend with cosine fallback), MMR diversity filtering, and minimum score thresholding. Pre-filters (tags, folders, doc type, topics, and complex JSON filters) apply at the database level before retrieval so every result matches.
Multi-format extraction — Indexes Markdown, PDFs, images, audio, and video. PDFs use text extraction first, falling back to OCR for scanned pages. Images get OCR text plus visual descriptions. Audio/video files are base64-sent to OpenRouter-compatible media models for transcript/search notes. EXIF metadata (camera, GPS, dates) is extracted automatically.
LLM enrichment — Each document is analyzed by an LLM to extract structured metadata: summary, document type, entities (people, places, orgs, dates), topics, keywords, key facts, suggested tags, and suggested folder. All fields are searchable and filterable.
Taxonomy system — A controlled vocabulary of tags and folder paths stored in a separate LanceDB table with embedded descriptions. The LLM uses the taxonomy during enrichment to suggest consistent tags and filing locations. Seeded from existing tag/directory databases. Managed via 7 MCP CRUD tools (file_taxonomy_*).
Smart chunking — Markdown is split by headings, PDFs by pages. Large sections get semantic chunking (topic-boundary detection via sentence embeddings). Every chunk gets a contextual header prepended with its title, path, and topics — so each chunk is self-describing for better retrieval.
Rich metadata & filtering — YAML frontmatter (tags, status, author, dates, custom fields) is automatically extracted and promoted to filterable columns. Custom frontmatter keys are auto-promoted — no schema changes needed. file_search supports exact filters plus complex JSON filters with eq, ne, contains, prefix, in, and, or, and not.
MCP server — Exposes 16 tools over the Model Context Protocol. Any MCP-compatible assistant can search, browse, filter your documents, and manage taxonomy entries. Works over stdio (launched automatically by the assistant) or HTTP.
Incremental updates — Only new and modified files are processed on re-index. Deleted files are cleaned up automatically. Failed documents are tracked and retried.
Cloud or local — LiteLLM is the primary OCR/vision routing authority and
can select local models, cloud models, or fallback chains. Legacy direct OCR
adapters remain available. Other providers support cloud and local profiles.
Resilient by default — Per-document error handling with retries, structured MCP error responses, search diagnostics on every query (vector_search_active, reranker_applied, degraded), SQL injection protection on filter keys, and automatic LanceDB corruption recovery (version rollback + rebuild).
MCP tools
Tool
Description
file_search
Hybrid semantic + keyword search with exact filters plus complex JSON filters (and/or/not, in, contains, etc.)
comm_lookup
One-call compact lookup for comm / person / phone / call / voicemail / message questions — returns a small verdict envelope with source ids. Use this first instead of raw comm-store SQL. See docs/comm-lookup.md
file_get_chunk
Get full text + metadata for one chunk by doc_id and loc
file_get_doc_chunks
Get all chunks for a document, sorted by position
file_list_documents
Browse all indexed documents with pagination and filters
file_recent
Recently modified/indexed docs (newest first)
file_facets
Distinct values + counts for all filterable fields
file_folders
Document folder/directory structure with file counts
file_status
Index stats, provider settings, health checks
file_index_update
Incrementally update the index without leaving the assistant
file_taxonomy_list
List taxonomy entries (tags, folders, doc_types) with filters
file_taxonomy_get
Get a single taxonomy entry by id
file_taxonomy_search
Semantic search on taxonomy descriptions
file_taxonomy_add
Add a new taxonomy entry
file_taxonomy_update
Update an existing taxonomy entry
file_taxonomy_delete
Delete a taxonomy entry
file_taxonomy_import
Import taxonomy from SQLite seed databases
Run tests
The maintained path is the gate — ordered, fail-fast tiers (static → unit →
integration → staging-e2e → live) where a full pass means "this works in
production". See docs/TESTING.md for the full runbook.
make gate-fast # static + unit + integration (free, no services) — the dev loop
make gate # all five tiers, incl. a hermetic staging compose stack + live
make gate-fast needs no API keys or Docker; make gate's staging-e2e tier
brings up an isolated, memory-capped compose stack (production image + provider
simulator + throwaway Postgres) and its live tier is preflight-guarded. The live
tier uses real providers and can spend money. make gate-real adds the optional
real-provider e2e stage; make test-e2e-real runs only that extra stage.
Raw pytest still works if you want to run a subset directly:
python -m pytest -m unit -q # offline, no API keys
python -m pytest -m "unit or integration" -q # all local tiers
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo RAG In A Box?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
RAG In A Box precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte RAG In A Box usa?
RAG In A Box roda localmente via stdio.
Quando RAG In A Box foi verificado pela última vez?