AgenticRAG MCP Server

An intelligent codebase processing server that provides agentic RAG (Retrieval-Augmented Generation) capabilities through the Model Context Protocol (MCP).

Features

• Intelligent Code Indexing: Automatically chunks and embeds codebases for semantic search
• Agentic Retrieval: Self-critiquing retrieval loop that ensures comprehensive context
• Multi-Model Architecture: Uses GPT-4o for retrieval and Claude 3 for planning
• Live Updates: File system watching for automatic re-indexing
• Cost Control: Built-in telemetry and budget management

Quick Installation

1. Clone and Install

# Clone the repository
git clone https://github.com/aibozo/agenticrag-mcp.git
cd agenticrag-mcp

# Run the installation script
./install.sh

The install script will:

• Check Python version (3.8+ required)
• Create a virtual environment
• Install all dependencies
• Prompt for your API keys
• Create necessary directories
• Generate Claude configuration

2. Add to Claude

After installation, add AgenticRAG to Claude:

Windows (Claude Desktop):

1. Open %APPDATA%\Claude\claude_desktop_config.json
2. Add the configuration from claude_config_snippet.json

macOS/Linux (Claude Desktop):

1. Open ~/.config/claude/claude_desktop_config.json
2. Add the configuration from claude_config_snippet.json

3. Restart Claude

Restart Claude to load the new MCP server.

Manual Installation

If you prefer to install manually:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# Add to Claude Desktop
claude mcp add agenticrag python3 /path/to/agenticrag-mcp/mcp_launcher.py

Usage

Once installed, you can use these tools in Claude:

Initialize a Repository

Please index the repository at /path/to/my/project as "myproject"

Search Your Code

Search myproject for "how does authentication work?"

Get Repository Statistics

Show me the stats for myproject

Example Conversation

You: Can you index my FastAPI project at ~/projects/api?

Claude: I'll index your FastAPI project for you.
        [Calls init_repo tool]
        ✓ Successfully indexed repository 'api'
        - Total files: 47
        - Total chunks: 312
        - Total tokens: 52,841
        - Duration: 4.32 seconds

You: How does the authentication middleware work?

Claude: Let me search for information about the authentication middleware.
        [Calls search_repo tool]
        Based on my search, the authentication middleware in your FastAPI project:
        
        1. JWT Token Validation (auth/middleware.py, lines 15-45):
           - Validates Bearer tokens on protected routes
           - Extracts user claims from JWT payload
           - Returns 401 for invalid/expired tokens
        
        2. User Context (auth/middleware.py, lines 50-72):
           - Adds user object to request state
           - Enables access via request.state.user
        
        The middleware is registered in main.py on line 23.

Configuration

Required Environment Variables

# .env file
OPENAI_API_KEY=sk-...        # Required for embeddings and GPT-4
ANTHROPIC_API_KEY=sk-ant-... # Optional, for Claude models

Optional Configuration

# Vector Database
CHROMA_PERSIST_DIRECTORY=./chroma_db

# Logging
LOG_LEVEL=INFO
LOG_FILE=./logs/agenticrag.log

# Models
DEFAULT_EMBEDDING_MODEL=text-embedding-3-large
DEFAULT_LLM_MODEL=gpt-4o

Architecture

agenticrag-mcp/
├── src/
│   ├── agents/          # Agentic RAG implementation
│   │   ├── base.py      # Base agent class
│   │   ├── retriever.py # Self-evaluating retriever
│   │   ├── compressor.py # Result compression
│   │   └── workflow.py  # LangGraph orchestration
│   ├── indexing/        # Code indexing pipeline
│   │   ├── chunker.py   # Semantic code chunking
│   │   ├── embedder.py  # OpenAI embeddings
│   │   └── indexer.py   # Repository indexer
│   ├── storage/         # Vector storage
│   │   └── vector_store.py # ChromaDB interface
│   └── mcp_server.py    # MCP server implementation
├── mcp_launcher.py      # MCP entry point
├── install.sh           # Installation script
└── requirements.txt     # Python dependencies

How It Works

1. Indexing: The system chunks your code respecting language boundaries and creates embeddings
2. Retrieval: When you search, an AI agent generates optimized queries and retrieves relevant chunks
3. Self-Evaluation: The agent evaluates if it has enough context and can perform additional searches
4. Compression: Results are intelligently summarized to provide clear, actionable answers

Troubleshooting

"No module named 'chromadb'"

Activate the virtual environment:

source venv/bin/activate

"OpenAI API key not found"

Make sure your .env file contains:

OPENAI_API_KEY=your-key-here

"MCP server not found in Claude"

1. Ensure you've added the configuration to Claude's config file
2. Restart Claude Desktop completely
3. Check the logs in ./logs/agenticrag.log

Search returns no results

Ensure you've indexed the repository first using the init_repo tool.

Development

Running Tests

source venv/bin/activate
python -m pytest tests/

Local Testing

# Test indexing
python test_indexing.py

# Test agentic RAG
python test_agentic_rag.py

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built for Claude Desktop using the Model Context Protocol
• Uses ChromaDB for vector storage
• Powered by OpenAI embeddings and LangGraph

If you prefer manual installation:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env with your API keys

Usage

Once installed, you can use these tools in Claude:

Index a Repository

Use the init_repo tool to index a codebase:
- path: /path/to/your/project
- repo_name: my-project

Search Code

Use the search_repo tool to find relevant code:
- query: "How does the authentication system work?"
- repo_name: my-project

Get Statistics

Use the get_repo_stats tool to see indexing statistics:
- repo_name: my-project

Example Conversation

User: Index my Python project at /home/user/myproject

Claude: I'll index your Python project for semantic search.
[Uses init_repo tool with path="/home/user/myproject" and repo_name="myproject"]

User: Find all the database connection code

Claude: I'll search for database connection code in your project.
[Uses search_repo tool with query="database connection" and repo_name="myproject"]
[Returns relevant code snippets with file paths and explanations]

Configuration

The server can be configured via environment variables in .env:

# API Keys (required)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Optional configurations
CHUNK_SIZE_TOKENS=1280        # Size of code chunks
MAX_FILE_SIZE_MB=2           # Maximum file size to index
DAILY_BUDGET_USD=100         # Cost control limit

Troubleshooting

Module Not Found

• Ensure virtual environment is activated: source venv/bin/activate
• Check installation: pip list | grep agenticrag

API Key Errors

• Verify keys in .env file
• Ensure no extra spaces or quotes around keys
• Check key permissions for required models

Claude Can't Find Tools

• Verify configuration path is absolute, not relative
• Check Claude logs: Help → Show Logs
• Ensure MCP server section exists in config

Server Won't Start

• Check Python version: python3 --version (need 3.8+)
• Verify Redis is running: redis-cli ping
• Check port availability: lsof -i:8000

Performance Issues

• Adjust CHUNK_SIZE_TOKENS for your codebase
• Increase EMBEDDING_BATCH_SIZE for faster indexing
• Monitor costs with get_repo_stats tool

Development

Running Tests

# Activate virtual environment
source venv/bin/activate

# Run all tests
pytest

# Run with coverage
pytest --cov=src

Code Formatting

# Format code
black src tests

# Lint code
ruff check src tests

Project Structure

agenticrag-mcp/
├── src/                    # Source code
│   ├── agents/            # AI agents
│   ├── api/              # API endpoints
│   ├── indexing/         # Code indexing
│   └── storage/          # Vector storage
├── tests/                 # Test files
├── install.sh            # Installation script
├── requirements.txt      # Dependencies
└── .env.example         # Environment template

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki