MCP with Gemini Integration

# Project Structure Documentation ## Overview The Gemini LLM Integration project has been organized into a clean, maintainable structure that separates concerns and makes the codebase easy to navigate and extend. The project follows a modular architecture with clear separation between client, server, tools, and utilities. ## Directory Structure ``` gemini-llm-integration/ ├── approach/ # High-level approach documentation │ ├── overall_approach.md # Complete project methodology │ └── rate_limiting_approach.md # Rate limiting strategy ├── data/ # Data and configuration files │ ├── kb.json # Knowledge base data │ └── knowledge_base.json # Company knowledge base (Q&A format) ├── db/ # Database files │ └── rate_limit_tracker.db # SQLite database for rate limiting ├── docs/ # Technical documentation │ └── project_structure.md # This file ├── scripts/ # Utility scripts │ ├── interactive_client.py # Interactive client for testing │ └── monitor_rate_limits.py # Rate limit monitoring tool ├── src/ # Source code │ ├── client/ # Client implementation │ │ └── main.py # Main client with interactive/batch modes │ ├── server/ # Server implementation │ │ ├── main.py # Main server entry point │ │ ├── logging_config.py # Logging configuration │ │ ├── tool_registration.py # Tool registration and management │ │ └── validation.py # Input validation utilities │ ├── tools/ # MCP tools implementation │ │ ├── __init__.py # Tool initialization and registration │ │ ├── calculator.py # Mathematical calculation tool │ │ ├── knowledge_base.py # Knowledge base search tool │ │ └── weather.py # Weather information tool │ └── utils/ # Utility modules │ ├── gemini_client.py # Gemini API client wrapper │ └── persistent_rate_limiter.py # Rate limiting implementation ├── tests/ # Test files │ ├── test_enhanced_implementation.py # Enhanced implementation tests │ └── test_server_tools.py # Server tools testing ├── .gitignore # Git ignore rules ├── README.md # Main project documentation ├── RATE_LIMITING_IMPLEMENTATION.md # Rate limiting documentation └── requirements.txt # Python dependencies ``` ## Component Details ### 1. Approach Documentation (`approach/`) **Purpose**: High-level strategic documentation that explains the overall methodology and design decisions. **Contents**: - `overall_approach.md`: Complete project methodology, architecture decisions, and implementation strategy - `rate_limiting_approach.md`: Detailed rate limiting strategy and methodology **Audience**: Project stakeholders, architects, and developers who need to understand the strategic decisions. ### 2. Data Layer (`data/`) **Purpose**: Stores all data files and configuration that the application uses. **Contents**: - `kb.json`: Knowledge base data in structured format - `knowledge_base.json`: Structured Q&A format knowledge base containing company policies, benefits, and procedures **Features**: - Easy to update and maintain - Structured format for consistent processing - Version controlled for change tracking ### 3. Database (`db/`) **Purpose**: Persistent storage for application state and tracking. **Contents**: - `rate_limit_tracker.db`: SQLite database for tracking API rate limits and usage **Features**: - Persistent rate limiting across application restarts - Efficient storage and retrieval of usage data - Automatic cleanup and maintenance ### 4. Documentation (`docs/`) **Purpose**: Technical documentation for developers and maintainers. **Contents**: - `project_structure.md`: This file explaining the organization **Features**: - Comprehensive technical details - Implementation guides - Best practices and patterns ### 5. Scripts (`scripts/`) **Purpose**: Utility scripts for development, testing, and monitoring. **Contents**: - `interactive_client.py`: Interactive client for testing and development - `monitor_rate_limits.py`: Tool for monitoring rate limit usage and status **Features**: - Development and testing utilities - Monitoring and debugging tools - Standalone execution capabilities ### 6. Source Code (`src/`) **Purpose**: Main application code organized by functionality. #### Client Implementation (`client/`): - `main.py`: Enhanced client with interactive and batch modes, comprehensive error handling #### Server Implementation (`server/`): - `main.py`: Clean server entry point with modular architecture - `logging_config.py`: Centralized logging configuration - `tool_registration.py`: Tool registration and management system - `validation.py`: Input validation utilities #### Tools Implementation (`tools/`): - `__init__.py`: Tool initialization and registration system - `calculator.py`: Mathematical calculation tool with comprehensive operations - `knowledge_base.py`: Knowledge base search tool with semantic search - `weather.py`: Weather information tool with location-based data #### Utility Modules (`utils/`): - `gemini_client.py`: Gemini API client wrapper with rate limiting integration - `persistent_rate_limiter.py`: Comprehensive rate limiting implementation with SQLite persistence **Features**: - Clean separation of concerns - Modular design for easy maintenance - Reusable utility components - Comprehensive error handling ### 7. Testing (`tests/`) **Purpose**: Comprehensive testing suite to validate functionality and performance. **Contents**: - `test_enhanced_implementation.py`: Enhanced implementation functionality tests - `test_server_tools.py`: Server tools integration testing **Features**: - Unit testing for individual components - Integration testing for end-to-end workflows - Automated validation of functionality ## File Organization Principles ### 1. Separation of Concerns **Code vs. Documentation**: Clear separation between implementation and documentation - Source code in `src/` with modular organization - Documentation in `docs/` and `approach/` - Data files in `data/` - Database files in `db/` - Tests in `tests/` - Scripts in `scripts/` ### 2. Modular Design **Component Isolation**: Each component has a specific responsibility - Client handles user interaction and communication - Server manages MCP protocol and tool coordination - Tools provide specific functionality (calculator, weather, knowledge base) - Rate limiter ensures API compliance - Utilities provide shared functionality ### 3. Scalability Considerations **Extensible Structure**: Easy to add new components - New tools can be added to `src/tools/` - Additional utilities can be added to `src/utils/` - New tests can be added to `tests/` - Additional documentation can be added to appropriate folders - Additional data sources can be added to `data/` ### 4. Maintainability Focus **Clear Organization**: Easy to find and modify components - Logical grouping of related files - Consistent naming conventions - Comprehensive documentation - Clear dependency relationships ## Development Workflow ### 1. Adding New Features **Source Code**: Add new modules to appropriate `src/` subdirectories **Documentation**: Update relevant files in `docs/` or `approach/` **Testing**: Add tests to `tests/` **Data**: Add configuration to `data/` if needed **Scripts**: Add utility scripts to `scripts/` if needed ### 2. Modifying Existing Features **Locate**: Find the relevant component in the appropriate directory **Update**: Modify the implementation **Test**: Run relevant tests in `tests/` **Document**: Update documentation if needed ### 3. Rate Limiting Changes **Implementation**: Modify `src/utils/persistent_rate_limiter.py` **Configuration**: Update limits or behavior **Testing**: Use `tests/` for validation **Monitoring**: Use `scripts/monitor_rate_limits.py` for monitoring ## Configuration Management ### 1. Environment Variables **Location**: `.env` file in project root **Contents**: API keys, configuration settings **Security**: Never committed to version control ### 2. Knowledge Base **Location**: `data/knowledge_base.json` and `data/kb.json` **Format**: Structured Q&A pairs **Updates**: Version controlled, easy to modify ### 3. Rate Limiting Configuration **Location**: `src/utils/persistent_rate_limiter.py` **Settings**: Limits, safety margins, token estimation **Database**: `db/rate_limit_tracker.db` **Customization**: Easy to modify for different requirements ## Deployment Considerations ### 1. File Organization **Production**: All files in their designated locations **Dependencies**: Clear separation of requirements **Configuration**: Environment-specific settings ### 2. Security **API Keys**: Stored in environment variables **Data**: Knowledge base can be customized per environment **Access**: Proper file permissions and access controls ### 3. Monitoring **Logs**: Application logs for debugging **Metrics**: Rate limiting status and performance **Health Checks**: System availability monitoring ## Benefits of This Structure ### 1. Developer Experience **Easy Navigation**: Clear file organization **Quick Understanding**: Logical component grouping **Simple Maintenance**: Modular design **Comprehensive Documentation**: Detailed guides and explanations ### 2. Project Scalability **Extensible Design**: Easy to add new features **Modular Architecture**: Independent component development **Clear Dependencies**: Well-defined relationships **Testing Support**: Comprehensive test organization ### 3. Operational Excellence **Deployment Ready**: Production-ready structure **Monitoring Support**: Built-in observability **Maintenance Friendly**: Easy troubleshooting **Documentation Rich**: Complete operational guides ## Future Enhancements ### 1. Additional Components **Web Interface**: Could be added to `src/web/` **Database Integration**: Could be added to `src/database/` **API Extensions**: Could be added to `src/api/` ### 2. Advanced Testing **Performance Tests**: Could be added to `tests/performance/` **Integration Tests**: Could be added to `tests/integration/` **End-to-End Tests**: Could be added to `tests/e2e/` ### 3. Documentation Expansion **API Documentation**: Could be added to `docs/api/` **User Guides**: Could be added to `docs/user/` **Deployment Guides**: Could be added to `docs/deployment/` This organized structure provides a solid foundation for current development and future growth, ensuring that the project remains maintainable, scalable, and well-documented as it evolves.