Fast MCP Task Manager

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