MCP with Gemini Integration

# Gemini LLM Integration with Semantic Search This project implements a powerful client-server application that integrates Google's Gemini LLM for natural language understanding and semantic search capabilities. The system provides intelligent responses to queries about company policies, benefits, and procedures using an extensible knowledge base with a modular, developer-friendly architecture. ## Features - **🧠 LLM Brain Tool Selection**: Real LLM-based tool selection and parameter extraction - **Semantic Search**: Uses Gemini 2.0 Flash Lite for understanding natural language queries - **Interactive & Batch Modes**: Run single queries or batch process multiple questions - **Comprehensive Knowledge Base**: Covers HR policies, benefits, and company procedures - **Dynamic Tool Registration**: Modular system for easy addition of new tools - **Developer-Friendly**: Simple interface for contributors to add their own tools - **Robust Error Handling**: Graceful fallbacks and clear error messages - **Rate Limiting**: Respects Gemini API limits with intelligent throttling - **Clean Interface**: Simple command-line interface for easy interaction ## Project Structure ``` gemini-llm-integration/ ├── src/ │ ├── client/ │ │ └── main.py # Enhanced MCP client with interactive and batch modes │ ├── server/ │ │ ├── main.py # Server with dynamic tool registration │ │ ├── logging_config.py # Logging configuration │ │ ├── validation.py # Input validation │ │ └── tool_registration.py # Tool registration system │ ├── tools/ │ │ ├── __init__.py # Tool registry and discovery system │ │ ├── knowledge_base.py # Knowledge base search tool │ │ ├── calculator.py # Mathematical calculation tool │ │ └── weather.py # Weather information tool │ └── utils/ │ ├── gemini_client.py # Rate-limited Gemini client │ └── persistent_rate_limiter.py # Rate limiting implementation ├── scripts/ │ ├── interactive_client.py # 🧠 LLM Brain Interactive Client │ └── monitor_rate_limits.py # Rate limit monitoring ├── data/ │ └── knowledge_base.json # Comprehensive company knowledge base (Q&A format) ├── tests/ │ ├── test_enhanced_implementation.py # Enhanced implementation tests │ └── test_server_tools.py # Server tool tests ├── docs/ │ └── project_structure.md # Detailed project structure ├── approach/ │ └── overall_approach.md # System architecture approach ├── README.md # This documentation └── requirements.txt # Python dependencies ``` ## Prerequisites - Python 3.11+ - Google Gemini API key - Required Python packages (installed via requirements.txt) ## Setup 1. **Set up the virtual environment**: ```bash # From the project root (gemini-llm-integration) python -m venv venv source venv/bin/activate # On macOS/Linux # On Windows: venv\Scripts\activate ``` 2. **Install dependencies**: ```bash pip install -r requirements.txt ``` 3. **Configure environment variables**: Create a `.env` file in the project root with your Gemini API key: ```env GEMINI_API_KEY=your_api_key_here ``` ## Running the Application ### Option 1: 🧠 LLM Brain Interactive Client (Recommended) The LLM Brain Interactive Client uses real LLM intelligence for tool selection - no keyword matching! ```bash cd gemini-llm-integration source venv/bin/activate python scripts/interactive_client.py ``` **Features:** - 🧠 Real LLM-based tool selection - 🧠 Intelligent parameter extraction - 🧠 No keyword matching - pure LLM intelligence - 🧠 Context-aware decision making - 🧠 Rate-limited API calls **Interactive Commands:** - `brain` - See LLM brain capabilities - `status` - Check rate limiting status - `tools` - See available tools - `quit` - Exit gracefully **Example Queries:** ``` 🧠 > What is 15 + 27? 🧠 > Calculate the square root of 16 🧠 > What's the weather in New York? 🧠 > How many sick days do employees get? 🧠 > What is the company's vacation policy? ``` ### Option 2: Enhanced MCP Client The Enhanced MCP Client connects to the MCP server and uses LLM-based tool selection. 1. **Start the server** in one terminal: ```bash cd gemini-llm-integration source venv/bin/activate python src/server/main.py ``` 2. **Run the enhanced client** in another terminal: **Interactive mode** (for live queries): ```bash cd gemini-llm-integration source venv/bin/activate python src/client/main.py --interactive ``` **Batch mode** (for predefined queries): ```bash cd gemini-llm-integration source venv/bin/activate python src/client/main.py ``` ### Option 3: Standalone LLM Brain (No Server) The LLM Brain Interactive Client can run standalone without the MCP server: ```bash cd gemini-llm-integration source venv/bin/activate python scripts/interactive_client.py ``` This directly uses the tools without going through the MCP protocol. ## Available Tools ### 1. 🧠 Knowledge Base Tool (`get_knowledge_base`) - **Purpose**: Search company policies, benefits, and procedures - **Examples**: - "What is the vacation policy?" - "How many sick days do employees get?" - "What is the dress code?" - "What benefits does the company offer?" ### 2. 🧮 Calculator Tool (`calculate`) - **Purpose**: Mathematical calculations and expressions - **Examples**: - "What is 15 + 27?" - "Calculate sqrt(16)" - "What is the absolute value of -42?" - "Round 3.7 to the nearest integer" ### 3. 🌤️ Weather Tool (`get_weather`) - **Purpose**: Weather information for various cities - **Examples**: - "What's the weather in New York?" - "Temperature in Tokyo" - "Weather forecast for London" ## Testing ### Run Tests ```bash cd gemini-llm-integration source venv/bin/activate python tests/test_enhanced_implementation.py python tests/test_server_tools.py ``` ### Monitor Rate Limits ```bash cd gemini-llm-integration source venv/bin/activate python scripts/monitor_rate_limits.py ``` ## Usage Examples ### LLM Brain Interactive Client ``` 🧠 LLM Brain Interactive Client ================================================== 🧠 > What is the company's vacation policy? ================================================== 🧠 Processing: What is the company's vacation policy? -------------------------------------------------- 🧠 Response: Employees receive 15 days of paid vacation per year for the first 2 years, 20 days after 2 years of service, and 25 days after 5 years. Vacation days must be approved by your manager in advance. Unused vacation days can be carried over up to 10 days to the next year. ================================================== 🧠 > Calculate 15 + 27 * 3 ================================================== 🧠 Processing: Calculate 15 + 27 * 3 -------------------------------------------------- 🧠 Response: Result: 96 ================================================== ``` ### Enhanced MCP Client ``` === Enhanced Gemini MCP Interactive Client === > What is the dress code? [System] Processing query with LLM-based tool selection... Response: We have a business casual dress code. On Fridays, casual dress is acceptable. For client meetings, business professional attire is required. The dress code applies to both in-office and remote work when on video calls. Jeans are acceptable on casual Fridays. ``` ## Adding New Tools (Developer Guide) The system uses a dynamic tool registration system that makes it easy for developers to add new tools: ### 1. Create a New Tool Module Create a new Python file in `src/tools/` (e.g., `src/tools/calculator.py`): ```python from src.tools import ToolDefinition class CalculatorTool: """Example calculator tool.""" async def calculate(self, expression: str) -> str: """Calculate mathematical expressions.""" try: result = eval(expression) return f"Result: {result}" except Exception as e: return f"Error: {str(e)}" # Global instance calculator_tool = CalculatorTool() def register_tool() -> ToolDefinition: """Register the calculator tool.""" return ToolDefinition( name="calculate", description="Calculate mathematical expressions.", handler=calculator_tool.calculate, input_schema={ "type": "object", "properties": { "expression": { "type": "string", "description": "Mathematical expression to evaluate" } }, "required": ["expression"] } ) ``` ### 2. Tool Discovery The system automatically discovers and registers all tools in the `src/tools/` directory that have a `register_tool()` function. ### 3. Tool Registration Tools are automatically registered when the server starts. No additional configuration needed! ## Extending the Knowledge Base 1. Edit `data/knowledge_base.json` to add or modify Q&A pairs 2. The system will automatically pick up changes when the server restarts 3. Follow the existing JSON structure for consistency ## Architecture Benefits - **🧠 LLM Brain**: Real LLM-based tool selection and parameter extraction - **Modular Design**: Each tool is self-contained and can be developed independently - **Dynamic Discovery**: New tools are automatically discovered without code changes - **Type Safety**: Strong typing with dataclasses for tool definitions - **Error Handling**: Graceful fallbacks when tools fail to load - **Extensible**: Easy to add new capabilities without modifying existing code - **Rate Limiting**: Intelligent API rate limiting with persistent storage ## Troubleshooting - **API Key Issues**: Ensure your `GEMINI_API_KEY` is set in the `.env` file - **Connection Errors**: Make sure the server is running before starting the MCP client - **Module Not Found**: Verify all dependencies are installed in your virtual environment - **Tool Registration Issues**: Check that your tool module has a `register_tool()` function - **Rate Limiting**: Use the `status` command to check rate limit status ## License This project is licensed under the MIT License - see the LICENSE file for details.