agent-rag-mcp

Agent_rag

Agent_rag is a RAG (Retrieval-Augmented Generation) MCP (Model Context Protocol) Server. It uses ChromaDB for vector storage and provides flexible embedding options—from lightweight Ollama integration to local ONNX models—with zero external dependencies.

Available Tools

This server exposes several MCP tools for the orchestrator (Agent_head) or any other MCP client:

• rag_ingest — Ingest documents, directories, or raw text into a collection
• rag_search — Perform semantic search against your knowledge base
• rag_list_collections — List all active collections
• rag_delete_collection — Delete a specific collection

Features

• Flexible Embedding Providers — Choose your embedding backend:
  • Ollama (~50 MB): Lightweight, runs with Ollama service—94% smaller than torch-based setup
  • Local ONNX (~300 MB): Fully offline with CPU/GPU support—no external services needed
  • GPU-Accelerated (~1.2 GB): PyTorch + sentence-transformers for maximum performance
• ChromaDB Integration: Persistent vector database for efficient semantic search
• FastMCP Built-in: Asynchronous, thread-safe tool execution
• Easy Configuration: Flexible config.yaml for chunk size, collections, embedding models, and provider selection
• Zero External Dependencies: No API keys required—everything runs locally

Quick Start

For a complete installation guide with size comparisons, troubleshooting, and provider-specific setup:

👉 See INSTALLATION.md

Installation & Usage

Interactive Setup (Recommended)

cd Agent_rag
python setup_agent_rag.py

This interactive script guides you through provider selection and runs the appropriate installation command.

Direct Installation

For Ollama (lightweight, ~50 MB):

uv install .[ollama]
python server.py

For Local Offline (ONNX, ~300 MB):

uv install .[local]
python server.py

For GPU (PyTorch acceleration, ~1.2 GB):

uv install .[gpu]
python server.py

For All Providers (complete setup):

uv install .[all]
python server.py

Running with uvx

You can run the published MCP server directly. uvx will automatically download and run the latest version:

uvx agent-rag-mcp

Transport Modes

By default, the server runs in stdio transport mode (designed to be spawned as a subprocess by MCP clients like Agent_head).

To run it over HTTP using Server-Sent Events (SSE):

uvx agent-rag-mcp --transport sse --port 8002 --host 0.0.0.0

Specifying a Test Registry (If using TestPyPI)

If you published the package to TestPyPI instead of the main PyPI, run it via:

uvx --extra-index-url https://test.pypi.org/simple/ --index-strategy unsafe-best-match agent-rag-mcp@latest

Configuration

The embedding provider and collection behavior are configured in config.yaml:

embeddings:
  provider: "ollama" # Options: "ollama", "onnx"
  ollama_base_url: "http://localhost:11434" # Ollama service URL
  ollama_model: "nomic-embed-text" # Ollama embedding model

  # For ONNX provider:
  # model: "all-MiniLM-L6-v2"
  # device: "cpu"                 # Options: "cpu", "cuda"

database:
  persist_directory: "./chroma_db"

document_processing:
  chunk_size: 1000
  chunk_overlap: 200

For detailed configuration options and provider-specific settings, see INSTALLATION.md.

Integrating with Agent_head

To connect this RAG server to your Agent_head orchestrator, add the following configuration to Agent_head/config.yaml:

memory:
  enabled: true
  backend: "rag"

  # Configure this if backend is set to "rag"
  rag_server:
    command: "uvx"
    args: ["agent-rag-mcp"] # Or ["--from", "/path/to/local/Agent_rag", "agent-rag-mcp"] for local development
    collection: "agent_memory"

Local Development

If you are developing this package locally:

1. Install dependencies:

   uv sync
   

2. Run locally:

   uv run agent-rag-mcp
   

3. Test the server:

   python test_mcp_client.py
   

4. Build the package:

   uv build
   

Architecture

Agent_rag uses a modular provider system:

• Embeddings Layer — Pluggable providers (Ollama, ONNX, future extensibility)
• ChromaDB — Local, persistent vector database with SQLite backend
• MCP Server — FastMCP-based async tool execution and stdio/SSE transport
• Document Pipeline — Configurable chunking, ingestion, and collection management

For more details, see INSTALLATION.md.