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

git clone <repository-url>
cd FAST_MCP

2. Create Virtual Environment

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

3. Install Dependencies

pip install -r requirements.txt

4. Install Google Gemini CLI

Follow the official Gemini CLI installation guide:

• Gemini CLI Documentation

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

🚀 Quick Start

Start the Server

./mcp_cli.sh start

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

Check Server Status

./mcp_cli.sh status

List Available Tools

./mcp_cli.sh list

Use MCP Tools

# 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

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

View Logs

./mcp_cli.sh logs

Stop the Server

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

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

{
  "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:

./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:

gemini config set api_key YOUR_API_KEY

🚀 Deployment

Development

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