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):
- Open
%APPDATA%\Claude\claude_desktop_config.json - Add the configuration from
claude_config_snippet.json
macOS/Linux (Claude Desktop):
- Open
~/.config/claude/claude_desktop_config.json - 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
- Indexing: The system chunks your code respecting language boundaries and creates embeddings
- Retrieval: When you search, an AI agent generates optimized queries and retrieves relevant chunks
- Self-Evaluation: The agent evaluates if it has enough context and can perform additional searches
- 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"
- Ensure you've added the configuration to Claude's config file
- Restart Claude Desktop completely
- 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:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
.envfile - 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_TOKENSfor your codebase - Increase
EMBEDDING_BATCH_SIZEfor faster indexing - Monitor costs with
get_repo_statstool
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
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes and test
- Submit a pull request
License
MIT License - see LICENSE file for details
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Wiki