MCP Local RAG

To perform a search, use query_documents. Results include text, source path, title, chunkIndex, and relevance score.

To get more context around a specific result, pass the chunkIndex and the filePath (or source) to read_chunk_neighbors.

Que dit la documentation de l'API au sujet de l'authentification ?
...
Lis les segments voisins de ce résultat sur l'authentification.

Database and Cache Paths

DB_PATH and CACHE_DIR default to the process's working directory. If your MCP client starts the server from different project directories, use absolute paths to ensure consistency.

Embedding Models

Use MODEL_NAME or --model-name to select a Hugging-Face embedding model.

• Note on Pooling: mcp-local-rag generates embeddings using Mean Pooling and L2 Normalization. Ensure your chosen model is compatible with these settings for optimal search quality.
• German Language Example: For German documents, consider using jinaai/jina-embeddings-v2-base-de.

Critical: Configuration Changes

Changing MODEL_NAME, RAG_DEVICE, or RAG_DTYPE will make existing vectors incompatible. If you change these settings, you must either:

1. Use a new DB_PATH,
2. Delete the existing index and re-import your documents.

mcp-local-rag uses mean pooling and L2 normalization for embeddings. When selecting a MODEL_NAME, ensure the model's recommended inference setup matches these settings to maintain retrieval quality.

Warning: Changing MODEL_NAME, RAG_DEVICE, or RAG_DTYPE will make existing vectors in your database incompatible. If you change these settings, you must either:

1. Use a new DB_PATH
2. Delete the existing index and re-ingest your documents.

For English documents, Xenova/bge-small-en-v1.5 is a recommended model.

Searching

Use query_documents to find information. Results include text, source path, title, section number, and relevance score.

Reading More Context

If a search result requires more context, use read_chunk_neighbors. You must provide the chunkIndex and either the filePath or the source from the original hit.

File Access

• Access is strictly limited to the roots defined by BASE_DIR, BASE_DIRS, or the --base-dir CLI option.
• Symbolic links pointing outside configured roots are rejected.

Concurrency and Backups

• Do not run multiple CLI or MCP write processes on the same DB_PATH simultaneously. Read-only queries are possible during a synchronization process.
• To back up an index, copy the DB_PATH directory only when no write processes are active.

Privacy

• Document processing and searching do not perform network requests once the necessary models are cached locally.

When using the --visual flag for PDF ingestion, you can choose between two VLM (Vision Language Model) profiles. Both run locally and offline.

Note: The first-time download for a profile is triggered on its first use and cached in CACHE_DIR. Switching profiles does not invalidate the other's cache.

To allow operations on multiple directories, use the BASE_DIRS environment variable. It must be a valid JSON array of non-empty paths. If BASE_DIRS is invalid (e.g., an empty array or a colon-separated string), the application will error instead of falling back to BASE_DIR.

Configuration Precedence:

1. CLI --base-dir <path> options (can be repeated in ingest, list, and sync)
2. BASE_DIRS environment variable
3. BASE_DIR environment variable
4. Current working directory

Note: Each source replaces the one with lower priority; they are not merged.

# Correct usage
export BASE_DIRS='["/Users/me/work","/Users/me/specs"]'

# Using repeated CLI flags
npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md