AgenticRAG MCP Server

# 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 ```bash # 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: ```bash # 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 ```bash # .env file OPENAI_API_KEY=sk-... # Required for embeddings and GPT-4 ANTHROPIC_API_KEY=sk-ant-... # Optional, for Claude models ``` ### Optional Configuration ```bash # 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: ```bash source venv/bin/activate ``` ### "OpenAI API key not found" Make sure your `.env` file contains: ```bash 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 ```bash source venv/bin/activate python -m pytest tests/ ``` ### Local Testing ```bash # 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](LICENSE) file for details. ## Acknowledgments - Built for [Claude Desktop](https://claude.ai) using the [Model Context Protocol](https://github.com/anthropics/mcp) - Uses [ChromaDB](https://www.trychroma.com/) for vector storage - Powered by [OpenAI](https://openai.com/) embeddings and [LangGraph](https://github.com/langchain-ai/langgraph) If you prefer manual installation: ```bash # 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`: ```bash # 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 ```bash # Activate virtual environment source venv/bin/activate # Run all tests pytest # Run with coverage pytest --cov=src ``` ### Code Formatting ```bash # 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](https://github.com/yourusername/agenticrag-mcp/issues) - **Discussions**: [GitHub Discussions](https://github.com/yourusername/agenticrag-mcp/discussions) - **Documentation**: [Wiki](https://github.com/yourusername/agenticrag-mcp/wiki)