FastAPI + MCP + Gemini Integration

# FastAPI + MCP + Gemini Integration This project demonstrates how to integrate a FastAPI application with Google's Gemini AI using a simplified MCP (Model Context Protocol) server implementation. ## 🏗️ Architecture - **FastAPI App** (`app.py`): A sample REST API with user management, task management, and dice rolling - **Simple MCP Server** (`simple_mcp_server.py`): Simplified MCP server that exposes FastAPI endpoints as tools - **Gemini Integration** (`simple_gemini_integration.py`): Connects Gemini AI with the MCP server ## 🚀 Features ### FastAPI Application - User management (CRUD operations) - Task management with completion tracking - Dice rolling functionality - Health checks and statistics - RESTful API endpoints ### MCP Server Tools - `get_health_status()`: Check application health - `get_app_info()`: Get application information - `get_all_users()`: Retrieve all users - `create_user()`: Create new users - `get_user_by_id()`: Get specific user - `get_all_tasks()`: Retrieve all tasks - `create_task()`: Create new tasks - `complete_task()`: Mark tasks as completed - `roll_dice()`: Roll dice with custom parameters - `get_app_statistics()`: Get application statistics - `search_users_by_name()`: Search users by name - `get_pending_tasks()`: Get incomplete tasks - `get_completed_tasks()`: Get completed tasks ## 📋 Prerequisites - Python 3.8+ - Google Gemini API key (optional - demo works in simulation mode) - Basic Python packages (fastapi, uvicorn, aiohttp, google-generativeai) ## 🛠️ Installation 1. **Clone or download the project files** 2. **Install dependencies:** ```bash pip install fastapi uvicorn aiohttp google-generativeai python-dotenv requests ``` 3. **Set up environment variables (optional):** Create a `.env` file and add your Gemini API key: ``` GEMINI_API_KEY=your_actual_api_key_here ``` Note: The demo works without an API key in simulation mode. 4. **Get a Gemini API key:** - Visit [Google AI Studio](https://aistudio.google.com/app/apikey) - Create a new API key - Add it to your `.env` file ## 🎯 Usage ### 0. Look for the video demo You can look for the zip file in which screen recording is present. That includes a demo question and an answer. ### 1. Start the FastAPI Server ```bash python app.py ``` The FastAPI server will run on `http://localhost:8000` ### 2. Test the FastAPI Endpoints You can test the API directly: ```bash # Health check curl http://localhost:8000/health # Get app info curl http://localhost:8000/ # Create a user curl -X POST "http://localhost:8000/users?name=John&email=john@example.com&age=30" # Create a task curl -X POST "http://localhost:8000/tasks?title=Learn%20FastMCP&description=Study%20FastMCP%20integration" # Roll dice curl "http://localhost:8000/dice/roll?sides=6&count=3" ``` ### 3. Run the Gemini Integration #### Demo Mode (Predefined Queries) ```bash python simple_gemini_integration.py ``` #### Interactive Mode ```bash python simple_gemini_integration.py --interactive ``` #### Automated Demo ```bash python start_simple_demo.py ``` ### 4. Example Gemini Queries In interactive mode, you can ask questions like: - "Check the health status of the FastAPI application" - "Create a new user named 'Alice' with email 'alice@example.com' and age 25" - "Create a task called 'Learn Python' with description 'Study Python programming'" - "Roll 5 dice with 10 sides each" - "Show me all users and get the application statistics" - "Mark the first task as completed" - "Show me all pending tasks" ## 🔧 Configuration ### FastAPI Server - Default port: 8000 - Host: 0.0.0.0 (accessible from all interfaces) - Modify `app.py` to change these settings ### MCP Server - Connects to FastAPI server at `http://localhost:8000` - Modify `API_BASE_URL` in `mcp_server.py` if needed ### Gemini Integration - Uses Gemini 2.0 Flash model - Configure API key via environment variable - Modify model settings in `gemini_integration.py` ## 📁 Project Structure ``` . ├── app.py # FastAPI application ├── simple_mcp_server.py # Simplified MCP server with tools ├── simple_gemini_integration.py # Gemini + MCP integration ├── start_simple_demo.py # Automated startup script ├── test_simple_integration.py # Integration testing ├── requirements.txt # Python dependencies ├── .gitignore # Git ignore file └── README.md # This file ``` ## 🧪 Testing ### Test FastAPI Endpoints ```bash # Start the server python app.py # In another terminal, test endpoints curl http://localhost:8000/health curl http://localhost:8000/users curl http://localhost:8000/tasks ``` ### Test MCP Server ```bash python simple_mcp_server.py ``` ### Test Gemini Integration ```bash # Make sure FastAPI server is running python app.py # In another terminal, run integration python simple_gemini_integration.py ``` ### Test Everything ```bash python test_simple_integration.py ``` ## 🔍 Troubleshooting ### Common Issues 1. **"Please set GEMINI_API_KEY environment variable"** - Make sure you have a `.env` file with your API key - Check that the API key is valid 2. **"Error connecting to MCP server"** - Ensure the FastAPI server is running on port 8000 - Check that all dependencies are installed 3. **"ModuleNotFoundError"** - Run `pip install -r requirements.txt` - Make sure you're using Python 3.8+ ### Debug Mode To see more detailed error messages, you can modify the integration script to include more logging. ## 🚀 Next Steps - Add more FastAPI endpoints - Create additional MCP tools - Implement authentication - Add database persistence - Create a web interface - Deploy to cloud platforms ## 📚 Learn More - [FastAPI Documentation](https://fastapi.tiangolo.com/) - [FastMCP Documentation](https://fastmcp.dev/) - [Google Gemini API](https://ai.google.dev/) - [Model Context Protocol](https://modelcontextprotocol.io/) ## 🤝 Contributing Feel free to submit issues and enhancement requests! ## 📄 License This project is open source and available under the MIT License.