Skip to main content
Glama
akshayvarala

rag

by akshayvarala
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Agentic-RAG-MCP

Local-first RAG retrieval engine built as a plugin for agentic environments via the Model Context Protocol (MCP).

The agent's own model handles generation. This server retrieves relevant context — the agent reasons and answers. No redundant LLM loaded by the plugin.

Python MCP License: MIT Tests

Why

Agentic coding tools (opencode, Claude Desktop, Hermes, pi, …) are great at reasoning but have no memory of your documents. Agentic-RAG-MCP fills that gap:

  • Ingest PDFs, DOCX, code, notes → normalized Markdown → chunks → embeddings → local vector DB

  • Search via MCP tools with metadata filtering — the agent grounds answers in your data

  • Inspect exact evidence with rag.get_chunk before answering

Everything runs locally. No cloud APIs, no data leaves your machine.

Related MCP server: DocAgent-MCP

Features

Area

Details

MCP-native

5 tools + 3 resources, works with opencode, Claude Desktop, any MCP client

Instruction-aware embeddings

Qwen3-Embedding with separate document/query prefixes

Pluggable backends

Embedding registry: local GGUF, SentenceTransformers, OpenAI, Cohere

Local vector DB

Qdrant in-process/file persistence, cosine similarity

Sandboxed ingestion

Relative paths only; rejects absolute paths, .., null bytes

Metadata filtering

Filter search by document_id, file_type, source

ABC everywhere

Converter, chunker, embeddings, vector store, reranker, LLM all swappable

Quick Start

git clone https://github.com/akshayvarala/Agentic-rag-mcp.git
cd Agentic-rag-mcp
pip install -e ".[gguf]"
cp .env.example .env   # edit model paths
python -m rag.cli status
python -m rag.cli ingest notes.pdf
python -m rag.cli search "what is retrieval augmented generation?"
python -m rag.cli serve   # start MCP server (stdio)

MCP Integration

opencode

~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rag": {
      "type": "local",
      "command": ["python", "-m", "rag.cli", "serve"],
      "cwd": "/path/to/Agentic-rag-mcp",
      "environment": { "PYTHONPATH": "/path/to/Agentic-rag-mcp/src" },
      "enabled": true
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "rag": {
      "command": "python",
      "args": ["-m", "rag.cli", "serve"],
      "cwd": "/path/to/Agentic-rag-mcp",
      "env": { "PYTHONPATH": "/path/to/Agentic-rag-mcp/src" }
    }
  }
}

Any MCP client (stdio)

PYTHONPATH=src python -m rag.cli serve

MCP Tools

Tool

Description

rag.search(query, top_k, document_id?, file_type?, source?)

Primary tool. Ranked chunks with scores + metadata

rag.ingest(relative_path)

Convert → chunk → embed → store. Sandboxed to ALLOWED_INPUT_DIR

rag.get_chunk(chunk_id)

Full chunk text + metadata for evidence inspection

rag.status()

Models, collection stats, config

rag.delete(document_id)

Remove a document from the index

Resources: rag://config, rag://models, rag://stats.

Configuration

.env (see .env.example):

# Embeddings (required) — pick ONE provider
EMBEDDING_PROVIDER=qwen_local
EMBEDDING_MODEL_PATH=C:\llama-cpp\Qwen3-Embedding-0.6B-Q8_0.gguf
EMBEDDING_DIMENSION=1024
EMBEDDING_BATCH_SIZE=32

# Vector store
QDRANT_PATH=./data/qdrant
QDRANT_COLLECTION=rag_documents

# Pipeline
DATA_DIR=./data
ALLOWED_INPUT_DIR=./data/original
CHUNK_SIZE=1024
CHUNK_OVERLAP=128

# MCP
MCP_HOST=127.0.0.1
MCP_PORT=3000
LOG_LEVEL=INFO

Embedding providers (EMBEDDING_PROVIDER): qwen_local (GGUF via llama-cpp), st_local (SentenceTransformers), openai, cohere.

Architecture

src/rag/
├── config.py          # Pydantic BaseSettings from .env
├── logging.py         # Structured logging (stderr-safe for MCP stdio)
├── errors.py          # RAGError + Conversion/Embedding/VectorStore/Security/Config/LLM/...
├── metadata.py        # Index metadata tracking
├── pipeline.py        # convert → chunk → embed → store → search
├── cli.py             # ingest / search / get-chunk / status / serve
├── converters/        # DocumentConverter ABC + MarkItDown
├── chunking/          # Overlapping text chunker with positions
├── embeddings/        # base + qwen_local + st_local + openai + cohere + registry
├── llm/               # Optional standalone LLM (llama-cpp) — NOT used by agent
├── vectorstore/       # VectorStore ABC + Qdrant local
├── retrieval/         # Retriever + Reranker ABC
├── mcp/               # server (MCP 2.x API) + tools + security
└── agent/             # Thin RAGAgent adapter for harnesses

Key design decisions:

  1. Retrieval-only — saves ~559MB vs loading a second LLM; avoids model confusion.

  2. Instruction-aware embeddings — embed_documents() and embed_query() use different prefixes; never treat them identically.

  3. Separate search/inspect — rag.search finds, rag.get_chunk reads deeply.

  4. MCP-first — no REST layer; agents consume tools directly.

Testing

PYTHONPATH=src python -m pytest tests/ -q
# 51 passed

Covers: chunking, converters, embeddings, vector store, retrieval, reranker, security (traversal/absolute-path/null-byte/oversize), pipeline, MCP tools, LLM.

Requirements

  • Python 3.11+

  • A GGUF embedding model or one of the API providers

  • ~1GB disk for Qdrant data (grows with corpus)

License

MIT — see LICENSE.

Contributors

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • rag-retriever-mcp

    code-lawyer
    F
    license
    A
    quality
    D
    maintenance
    A local-first document retrieval engine that mounts as an MCP tool for agents to index files, search for relevant passages, and let the agent's own LLM answer.
    4
    -

  • DocAgent-MCP

    wuliuke
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables local document question-answering and retrieval via MCP, supporting multi-turn conversation, intent recognition, and tools for document search, Q&A, and summarization.
    5
    -

  • CorpusGate

    mustafa0zdemir
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI tools to securely search and retrieve relevant, source-attributed chunks from private local documents via MCP, without sending document content to third-party services.
    1
    MIT