# 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.