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.
स्टार
4
टूल
—
अपटाइम
—
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
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
RAG In A Box कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या RAG In A Box के लिए API key चाहिए?
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
RAG In A Box कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
RAG In A Box stdio पर लोकल चलता है।
RAG In A Box की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-11-14 को हुई। RAG pipeline for documents (Markdown, PDF, images). 10-step hybrid search, LLM enrichment, taxonomy, MCP server. Cloud or local.