# Fast MCP Server with Google Gemini Integration

A comprehensive Model Context Protocol (MCP) server built with FastAPI that integrates with Google Gemini CLI for AI-powered task management and data processing.

## 🚀 Features

- **FastAPI-based MCP Server**: High-performance async server running on port 5000
- **Google Gemini Integration**: Seamless integration with Gemini CLI for AI responses
- **Task Management Tools**: Complete CRUD operations for task management
- **Data Analytics**: Task statistics and CSV export capabilities
- **Comprehensive Logging**: JSON-based operation logging for tracking and debugging
- **CLI Interface**: Easy-to-use command-line tool for server interaction
- **RESTful API**: Full API documentation with Swagger UI
- **Production Ready**: Modular, clean, and well-documented code

## 📋 Prerequisites

- Python 3.8 or higher
- Google Gemini CLI installed and configured
- curl (for CLI operations)
- Git (for cloning the repository)

## 🛠️ Installation

### 1. Clone the Repository

```bash
git clone <repository-url>
cd FAST_MCP
```

### 2. Create Virtual Environment

```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

### 4. Install Google Gemini CLI

Follow the official Gemini CLI installation guide:
- [Gemini CLI Documentation](https://ai.google.dev/gemini-api/docs/quickstart)

Make sure Gemini CLI is properly configured with your API key.

## 🚀 Quick Start

### Start the Server

```bash
./mcp_cli.sh start
```

The server will start on `http://localhost:5000`

### Check Server Status

```bash
./mcp_cli.sh status
```

### List Available Tools

```bash
./mcp_cli.sh list
```

### Use MCP Tools

```bash
# List all tasks
./mcp_cli.sh run list_tasks

# Create a new task
./mcp_cli.sh run create_task "Implement authentication" "Add JWT-based auth" "high"

# Update task status
./mcp_cli.sh run update_task_status 1 "in_progress"

# Search tasks
./mcp_cli.sh run search_tasks "authentication"

# Get task statistics
./mcp_cli.sh run get_task_statistics

# Export tasks to CSV
./mcp_cli.sh run export_tasks_to_csv
```

### Interact with Gemini

```bash
./mcp_cli.sh gemini "What are the best practices for API security?"
```

### View Logs

```bash
./mcp_cli.sh logs
```

### Stop the Server

```bash
./mcp_cli.sh stop
```

## 📚 API Documentation

Once the server is running, visit:
- **Swagger UI**: http://localhost:5000/docs
- **ReDoc**: http://localhost:5000/redoc

## 🔧 Available MCP Tools

### 1. `list_tasks`
- **Description**: List all tasks with optional status filtering
- **Parameters**: 
  - `status_filter` (optional): Filter by status (pending, in_progress, completed)
- **Example**: `./mcp_cli.sh run list_tasks pending`

### 2. `create_task`
- **Description**: Create a new task
- **Parameters**:
  - `title` (required): Task title
  - `description` (required): Task description
  - `priority` (optional): Priority level (low, medium, high)
  - `assigned_to` (optional): User ID to assign the task
- **Example**: `./mcp_cli.sh run create_task "New Feature" "Implement user dashboard" "high" "dev1"`

### 3. `update_task_status`
- **Description**: Update the status of an existing task
- **Parameters**:
  - `task_id` (required): ID of the task to update
  - `new_status` (required): New status (pending, in_progress, completed)
- **Example**: `./mcp_cli.sh run update_task_status 1 "completed"`

### 4. `get_task_statistics`
- **Description**: Get comprehensive task statistics and analytics
- **Parameters**: None
- **Example**: `./mcp_cli.sh run get_task_statistics`

### 5. `search_tasks`
- **Description**: Search tasks by title or description
- **Parameters**:
  - `query` (required): Search query string
- **Example**: `./mcp_cli.sh run search_tasks "authentication"`

### 6. `export_tasks_to_csv`
- **Description**: Export all tasks to a CSV file
- **Parameters**: None
- **Example**: `./mcp_cli.sh run export_tasks_to_csv`

## 🤖 Gemini Integration

The server integrates with Google Gemini CLI to provide AI-powered responses:

### Features
- **Multi-turn Conversations**: Maintains context across interactions
- **Error Handling**: Graceful handling of CLI failures and timeouts
- **Logging**: All Gemini interactions are logged for tracking
- **Timeout Protection**: 30-second timeout to prevent hanging requests

### Usage Examples

```bash
# Technical questions
./mcp_cli.sh gemini "How do I implement JWT authentication in FastAPI?"

# Code review
./mcp_cli.sh gemini "Review this Python function for best practices"

# Documentation help
./mcp_cli.sh gemini "Generate API documentation for a task management system"
```

## 📁 Project Structure

```
FAST_MCP/
├── server.py              # Main FastAPI server
├── requirements.txt       # Python dependencies
├── mcp_cli.sh            # CLI interface script
├── sample_data.json      # Sample task data
├── README.md             # This file
├── venv/                 # Virtual environment (created during setup)
├── server.log            # Server logs (created when running)
├── mcp_logs.json         # MCP operation logs (created when running)
└── tasks_export_*.csv    # Exported CSV files (created when exporting)
```

## 🔍 Logging and Monitoring

### Operation Logs
All MCP tool calls and Gemini interactions are logged to `mcp_logs.json`:

```json
{
  "timestamp": "2024-01-17T10:30:00Z",
  "operation": "mcp_tool_call",
  "tool_name": "create_task",
  "success": true,
  "result": {...},
  "error": null
}
```

### Server Logs
Server logs are written to `server.log` and include:
- Server startup/shutdown events
- Request/response details
- Error messages and stack traces
- Performance metrics

### Health Monitoring
Check server health at any time:

```bash
./mcp_cli.sh health
```

## 🛡️ Error Handling

The server includes comprehensive error handling:

- **Tool Validation**: Validates tool names and parameters
- **Data Persistence**: Handles file I/O errors gracefully
- **Gemini CLI Integration**: Manages CLI failures and timeouts
- **HTTP Errors**: Proper HTTP status codes and error messages
- **Logging**: All errors are logged for debugging

## 🔧 Configuration

### Server Configuration
- **Port**: 5000 (configurable in `server.py`)
- **Host**: 0.0.0.0 (all interfaces)
- **Data File**: `sample_data.json`
- **Log File**: `mcp_logs.json`

### Gemini CLI Configuration
Ensure Gemini CLI is properly configured:
```bash
gemini config set api_key YOUR_API_KEY
```

## 🚀 Deployment

### Development
```bash
./mcp_cli.sh start
```

### Production
For production deployment, consider:
- Using a process manager like PM2 or systemd
- Setting up reverse proxy with Nginx
- Implementing proper authentication
- Adding rate limiting
- Setting up monitoring and alerting

## 🧪 Testing

### Manual Testing
1. Start the server: `./mcp_cli.sh start`
2. Test each tool: `./mcp_cli.sh run <tool_name>`
3. Test Gemini integration: `./mcp_cli.sh gemini "test prompt"`
4. Check logs: `./mcp_cli.sh logs`
5. Verify health: `./mcp_cli.sh health`

### API Testing
Use the Swagger UI at http://localhost:5000/docs to test API endpoints directly.

## 📊 Sample Data

The project includes `sample_data.json` with:
- **5 sample tasks** with different statuses and priorities
- **4 user profiles** with roles and departments
- **2 project definitions** with team assignments

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Test thoroughly
5. Commit your changes: `git commit -m "Add feature"`
6. Push to the branch: `git push origin feature-name`
7. Submit a pull request

## 📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🆘 Troubleshooting

### Common Issues

1. **Server won't start**
   - Check if port 5000 is available
   - Verify virtual environment is activated
   - Check `server.log` for error details

2. **Gemini CLI not found**
   - Install Gemini CLI: `pip install google-generativeai`
   - Configure API key: `gemini config set api_key YOUR_KEY`

3. **Permission denied on mcp_cli.sh**
   - Make executable: `chmod +x mcp_cli.sh`

4. **Data file errors**
   - Check file permissions
   - Verify JSON format in `sample_data.json`

### Getting Help

- Check the logs: `./mcp_cli.sh logs`
- Review server logs: `tail -f server.log`
- Test server health: `./mcp_cli.sh health`
- Check API documentation: http://localhost:5000/docs

## 🎯 Roadmap

- [ ] Add user authentication and authorization
- [ ] Implement real-time notifications
- [ ] Add more MCP tools (file processing, email, etc.)
- [ ] Create web dashboard
- [ ] Add unit and integration tests
- [ ] Implement caching for better performance
- [ ] Add Docker support
- [ ] Create CI/CD pipeline

## 📞 Support

For support and questions:
- Create an issue in the repository
- Check the troubleshooting section
- Review the API documentation

---

**Built with ❤️ using FastAPI and Google Gemini**