mcp-local-rag

Converts documents (PDF, text, markdown) into vector embeddings using Hugging Face transformers running locally, then indexes them in LanceDB for semantic search without external API calls. Uses a two-stage pipeline: document chunking with configurable overlap, followed by batch embedding generation via sentence-transformers models, enabling privacy-preserving knowledge base construction entirely offline.

Executes semantic search queries against the indexed document collection by converting user queries to embeddings and computing vector similarity (cosine distance) against stored document chunks in LanceDB. Returns ranked results with relevance scores and source document metadata, enabling natural language search without keyword matching. Implements configurable top-k retrieval with optional similarity threshold filtering.

Exposes RAG operations (indexing, search, metadata retrieval) as standardized MCP tools that Claude, Cursor, and other MCP-compatible clients can discover and invoke. Implements the Model Context Protocol specification with proper tool schemas, parameter validation, and error handling, allowing seamless integration into multi-tool agent workflows without custom client code.

Automatically detects and parses multiple document formats (PDF via pdfjs, plain text, markdown) into normalized text chunks suitable for embedding. Handles PDF metadata extraction, text encoding detection, and format-specific preprocessing (markdown frontmatter stripping, code block preservation) before chunking, enabling heterogeneous document collections without manual conversion.

Splits documents into semantically-relevant chunks using token-based boundaries with configurable chunk size and overlap parameters. Preserves document structure by respecting paragraph and sentence boundaries when possible, and maintains chunk metadata (source document, chunk index, character offsets) for precise source attribution. Overlap between chunks enables better context preservation for queries that span chunk boundaries.

Manages lifecycle of Hugging Face transformer models for embedding generation, including automatic model downloading, caching, and device selection (CPU/GPU). Supports multiple embedding models (all-MiniLM-L6-v2, all-mpnet-base-v2, etc.) with configurable model selection and lazy loading to minimize startup time. Handles model versioning and ensures consistency between indexing and query embedding models.

Persists vector indexes to disk using LanceDB's columnar format, enabling fast index loading on subsequent runs without re-embedding documents. Implements index versioning and metadata tracking to detect schema changes or model mismatches. Supports index export/import for backup and distribution, and provides index statistics (document count, index size, last updated) for monitoring.

Implements MCP server initialization, request handling, and graceful shutdown with proper resource cleanup. Manages stdio-based communication with MCP clients, tool registration and discovery, and error handling with detailed diagnostic logging. Supports configuration via environment variables or config files, enabling deployment flexibility without code changes.