FastAPI MCP Server

# FastAPI + MCP Server Integration with Gemini CLI This project demonstrates how to build a FastAPI application, wrap it as an MCP (Model Context Protocol) Server, and integrate it with Gemini CLI for direct tool calling. ## Project Structure ``` ├── sample_app.py # FastAPI application with user and task management ├── mcp_server.py # MCP server that wraps the FastAPI app ├── requirements.txt # Python dependencies ├── setup.sh # Setup script ├── demo.sh # Interactive demonstration script ├── test_integration.py # Integration test script ├── venv/ # Python virtual environment └── README.md # This file ``` ## Features ### FastAPI Application (`sample_app.py`) - **User Management**: Create, read users with name, email, and age - **Task Management**: Create, read, update, delete tasks - **Statistics**: Get overview of users and tasks - **Health Check**: Basic health monitoring endpoint ### MCP Server (`mcp_server.py`) - **Tool Integration**: Exposes all FastAPI endpoints as MCP tools - **Error Handling**: Proper HTTP error handling and logging - **Type Safety**: Full type annotations and schema validation ### Available MCP Tools 1. `get_app_info` - Get basic app information 2. `get_health` - Check app health status 3. `get_users` - List all users 4. `create_user` - Create a new user 5. `get_user` - Get user by ID 6. `get_tasks` - List all tasks 7. `create_task` - Create a new task 8. `get_task` - Get task by ID 9. `update_task` - Update an existing task 10. `delete_task` - Delete a task 11. `get_stats` - Get user and task statistics ## Quick Start ### Option 1: Automated Demo ```bash ./demo.sh ``` This interactive script will guide you through the entire setup and testing process. ### Option 2: Manual Setup #### 1. Run Setup Script ```bash ./setup.sh ``` #### 2. Start the FastAPI Application ```bash source venv/bin/activate python sample_app.py ``` The FastAPI app will be available at `http://localhost:8000` #### 3. Start the MCP Server (in another terminal) ```bash source venv/bin/activate python mcp_server.py ``` #### 4. Install Gemini CLI ```bash npm install -g @google/gemini-cli@latest ``` #### 5. Add MCP Server to Gemini CLI ```bash gemini mcp add fastapi-sample stdio python $(pwd)/mcp_server.py ``` #### 6. Test the Integration ```bash # List available tools gemini mcp list # Call a tool gemini call fastapi-sample get_app_info # Create a user gemini call fastapi-sample create_user --name "John Doe" --email "john@example.com" --age 30 # Get all users gemini call fastapi-sample get_users # Create a task gemini call fastapi-sample create_task --title "Learn MCP" --description "Study Model Context Protocol" --user_id 1 # Get statistics gemini call fastapi-sample get_stats ``` ## Manual Setup If you prefer to set up manually: ### 1. Install Python Dependencies ```bash pip3 install -r requirements.txt ``` ### 2. Start Services - FastAPI app: `python3 sample_app.py` - MCP server: `python3 mcp_server.py` ### 3. Install and Configure Gemini CLI ```bash npm install -g @google/gemini-cli@latest gemini mcp add fastapi-sample stdio python3 /path/to/mcp_server.py ``` ## API Endpoints The FastAPI application provides the following REST endpoints: - `GET /` - App information - `GET /health` - Health check - `GET /users` - List users - `POST /users` - Create user - `GET /users/{user_id}` - Get user by ID - `GET /tasks` - List tasks - `POST /tasks` - Create task - `GET /tasks/{task_id}` - Get task by ID - `PUT /tasks/{task_id}` - Update task - `DELETE /tasks/{task_id}` - Delete task - `GET /stats` - Get statistics ## MCP Tool Examples ### Create and Manage Users ```bash # Create a user gemini call fastapi-sample create_user --name "Alice Smith" --email "alice@example.com" --age 25 # Get user by ID gemini call fastapi-sample get_user --user_id 1 # List all users gemini call fastapi-sample get_users ``` ### Create and Manage Tasks ```bash # Create a task gemini call fastapi-sample create_task --title "Complete project" --description "Finish the MCP integration" --user_id 1 # Update a task gemini call fastapi-sample update_task --task_id 1 --title "Complete project" --description "Finish the MCP integration" --user_id 1 --completed true # Delete a task gemini call fastapi-sample delete_task --task_id 1 ``` ### Get Statistics ```bash gemini call fastapi-sample get_stats ``` ## Troubleshooting ### Common Issues 1. **Port already in use**: Make sure port 8000 is available for the FastAPI app 2. **MCP server connection failed**: Ensure the FastAPI app is running before starting the MCP server 3. **Gemini CLI not found**: Make sure Node.js and npm are installed, then install Gemini CLI globally ### Debug Mode To run the FastAPI app in debug mode: ```bash uvicorn sample_app:app --reload --host 0.0.0.0 --port 8000 ``` ### Check MCP Server Status ```bash gemini mcp list ``` ## Development ### Adding New Endpoints 1. Add the endpoint to `sample_app.py` 2. Add the corresponding tool to `mcp_server.py` in the `handle_list_tools()` function 3. Add the tool handler in the `handle_call_tool()` function ### Testing You can test the FastAPI endpoints directly using curl: ```bash # Test app info curl http://localhost:8000/ # Create a user curl -X POST http://localhost:8000/users \ -H "Content-Type: application/json" \ -d '{"name": "Test User", "email": "test@example.com", "age": 30}' # Get users curl http://localhost:8000/users ``` ## License This project is for educational purposes and demonstrates MCP integration patterns.