RAG Local MCP Server for Semantic Passage Retrieval

Overview

This MCP (Model Context Protocol) server provides a lightweight, local way to store and retrieve text passages using semantic passage retrieval. It is designed to act as a fast, private retrieval layer for Retrieval-Augmented Generation (RAG) workflows: you index passages (documents split into passages), and at query time you retrieve the most semantically relevant passages to provide context for a language model.

Running the server locally keeps data private, reduces latency compared to remote services, and makes it easy to integrate passage retrieval into development, evaluation, and production RAG pipelines. The server exposes a simple HTTP API and a small client surface so you can add passages, build indexes, and perform nearest-neighbor semantic queries from your applications.

Features

• Local storage of passage text + metadata for private RAG workflows
• Semantic retrieval via vector embeddings and nearest-neighbor index
• Simple HTTP API compatible with Model Context Protocol patterns
• Configurable embedding provider and model (supports local or remote encoders)
• Configurable index type (in-memory vs persistent index)
• Fast top-k retrieval for providing context to LLM prompts
• Minimal dependencies for easy deployment and development

Installation / Configuration

Clone the repository and install Python dependencies (example):

git clone https://github.com/renl/mcp-rag-local.git
cd mcp-rag-local
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Start the server with Uvicorn (example):

# development
uvicorn mcp_rag_local.server:app --host 0.0.0.0 --port 8080 --reload

Configuration is handled primarily via environment variables. Example env file (.env):

# .env
MCP_HOST=0.0.0.0
MCP_PORT=8080
DATA_DIR=./data
EMBEDDING_PROVIDER=local   # or "openai", "huggingface", etc.
EMBEDDING_MODEL=all-MiniLM-L6-v2
INDEX_TYPE=faiss           # or "annoy", "hnsw", "memory"
TOP_K=5

Common commands for index management:

# add passages (example script included)
python scripts/add_passages.py --input data/articles.jsonl

# build or rebuild index from stored passages
python scripts/build_index.py

# run a health check
curl http://localhost:8080/health

Available Resources

The server exposes a small set of HTTP endpoints for managing and querying passages. Example endpoints (conceptual — refer to the repository for exact paths):

• POST /passages
  • Add one or more passages (text + optional metadata)
• POST /query
  • Submit a natural language query and return top-k semantically similar passages with scores
• GET /passages/{id}
  • Retrieve a stored passage by id
• DELETE /passages/{id}
  • Remove a passage from storage
• GET /health
  • Service health and status

Client examples are included in the repo: a simple Python client and shell curl snippets. The server persists raw passages and the vector index in the configured DATA_DIR so you can back up, inspect, or migrate stored content.

Configuration table

Quick Examples

Add passages (curl):

curl -X POST http://localhost:8080/passages \
  -H "Content-Type: application/json" \
  -d '[{"id":"p1","text":"The Eiffel Tower is in Paris.","meta":{"source":"wiki"}},{"id":"p2","text":"Paris is the capital of France.","meta":{"source":"notes"}}]'

Query for relevant passages:

curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query":"Where is the Eiffel Tower located?","top_k":3}'

Python client usage (requests):

import requests
payload = {"query": "What is the capital of France?", "top_k": 4}
r = requests.post("http://localhost:8080/query", json=payload)
results = r.json()
for item in results["passages"]:
    print(item["id"], item["score"], item["text"][:120])

Use Cases

• RAG for chatbots: Retrieve a small set of high-quality passages to prepend to prompts, improving factuality and grounding for LLM responses.
• Private knowledge bases: Keep internal documents on-premises while enabling semantic search and retrieval without cloud storage.
• Offline or low-latency retrieval: Run the index locally inside a microservice to avoid network round-trips for embeddings + retrieval.
• Evaluation and development: Quickly iterate on passage-splitting, embedding models, and prompt templates in local development environments.
• Document augmentation: Enrich user queries with contextual passages for downstream processing (summarization, classification, answer extraction).

This MCP server is intended as a compact, developer-friendly component for building RAG systems. Refer to the repository examples and scripts to seed passages, configure embedding backends, and integrate retrieval results into your prompt pipelines.