Freedcamp MCP Server

# 🚀 Enhanced Freedcamp MCP Server A comprehensive **Model Context Protocol (MCP) server** for seamless integration with the **Freedcamp API**. This server provides enterprise-level project management capabilities with advanced filtering, full CRUD operations, and extensive customization options. ## ✨ Features ### 🏗️ **Project Management** - **List projects** with optional recent project tracking - **Detailed project information** including users, notifications, and capabilities - **Create/Update/Delete projects** with user management - **Manage project teams** (add, update, remove users) - **Group management** and project organization ### 📋 **Advanced Task Management** - **Comprehensive task filtering** with 15+ filter options: - Status filtering (not started, completed, in progress) - User assignment filtering (assigned to, created by) - Date range filtering (due dates, creation dates) - Priority-based filtering and ordering - Custom fields and tags support - **Full task lifecycle** - Create, Read, Update, Delete - **Subtask support** with parent-child relationships - **File attachments** and media management - **Recurring tasks** with iCalendar format support - **Pagination and ordering** for large datasets ### 👥 **User Management** - **Complete user profiles** with detailed information - **Current user management** and profile updates - **User task assignments** and workload tracking - **Email and password management** with secure token handling ### 💬 **Comment System** - **Add/Update/Delete comments** on tasks and items - **File attachments** in comments - **Rich text support** with HTML formatting - **Comment threading** and user attribution ### 📁 **File Management** - **File details** and metadata access - **File deletion** and cleanup - **Multi-format support** (images, documents, etc.) - **Temporary file handling** for uploads ## 🛠️ Installation & Setup ### Prerequisites - Docker and Docker Compose - Freedcamp API credentials (API Key) ### Quick Start 1. **Clone the repository:** ```bash git clone https://github.com/BluePointDigital/freedcamp-mcp-server.git cd freedcamp-mcp-server ``` 2. **Set up environment variables:** ```bash cp env-example.sh .env # Edit .env and add your Freedcamp credentials ``` 3. **Start the services:** ```bash docker-compose up -d ``` 4. **Access the API:** - **MCP Server**: http://localhost:8000/mcp/ - **OpenAPI Proxy**: http://localhost:8111 - **API Documentation**: http://localhost:8111/docs ## 🔧 Configuration ### Environment Variables Create a `.env` file with your Freedcamp credentials: ```bash FREEDCAMP_API_KEY=your_api_key_here FREEDCAMP_API_SECRET=your_api_secret_here # Optional for some endpoints ``` ### Docker Configuration The included `docker-compose.yml` provides: - **Health checks** for service monitoring - **Restart policies** for reliability - **Resource limits** for optimal performance - **Network isolation** for security ## 🔥 Workflow Instructions for LLMs **IMPORTANT**: This MCP server includes comprehensive workflow guidance to ensure proper usage: 1. **Server Description**: Built-in instructions provided when LLMs first connect 2. **`get_workflow_help()` Tool**: Contextual workflow guidance for specific operations 3. **Enhanced Tool Docstrings**: Workflow reminders in critical tools like `create_task()` 4. **Workflow Documentation**: See `freedcamp-workflow-instructions.md` for detailed guidance **Key Rule**: Always call `get_projects()` and `get_users()` first to look up IDs before using them in operations! ## 📚 API Reference ### 🏗️ Project Tools | Tool | Description | Parameters | |------|-------------|------------| | `get_projects` | List all projects with grouping | `include_recent: bool` | | `get_project_details` | Detailed project information | `project_id: str` | | `create_project` | Create new project with team | `name, description, color, users...` | | `update_project` | Update project and manage users | `project_id, name, users_to_add...` | | `delete_project` | Remove project | `project_id: str` | ### 📋 Task Tools | Tool | Description | Key Features | |------|-------------|--------------| | `get_all_tasks` | Advanced task filtering | 15+ filter options, pagination | | `get_project_tasks` | Project-specific tasks | Status filtering, custom fields | | `get_user_tasks` | User assignment tracking | Completed task inclusion | | `get_task_details` | Complete task information | Comments, files, custom fields | | `create_task` | Enhanced task creation | Subtasks, files, recurring rules | | `update_task` | Full task modification | All properties, custom fields | | `delete_task` | Task removal | Cascade handling | ### 👥 User Tools | Tool | Description | Capabilities | |------|-------------|--------------| | `get_users` | List all workspace users | Full profile data | | `get_current_user` | Current user information | Profile details | | `get_user_details` | Specific user data | `user_id: str` | | `update_current_user` | Profile management | Email, password, timezone | ### 💬 Comment Tools | Tool | Description | Features | |------|-------------|----------| | `add_comment` | Create comments | File attachments, HTML support | | `update_comment` | Modify comments | Rich text editing | | `delete_comment` | Remove comments | Clean deletion | ### 📁 File Tools | Tool | Description | Capabilities | |------|-------------|--------------| | `get_file_details` | File information | Metadata, URLs, thumbnails | | `delete_file` | File removal | Clean deletion | ## 🔍 Usage Examples ### Advanced Task Filtering ```python # Get overdue high-priority tasks assigned to specific users await get_all_tasks( status_filter=["0", "2"], # Not started or in progress assigned_to_ids=["123", "456"], due_date_to="2024-01-01", # Overdue order_by="priority", order_direction="desc", limit=50 ) ``` ### Project Team Management ```python # Add users to a project await update_project( project_id="789", users_to_add=[ {"email": "user@example.com", "first_name": "John", "last_name": "Doe"}, {"email": "admin@example.com", "first_name": "Jane", "last_name": "Admin"} ] ) ``` ### Task Creation with Subtasks ```python # Create a parent task with subtasks and files parent_task = await create_task( title="Main Project Phase", project_id="123", priority=3, # High priority due_date="2024-12-31" ) # Create subtask await create_task( title="Subtask 1", project_id="123", parent_task_id=parent_task["task"]["id"], attached_file_ids=[456, 789] ) ``` ## 🏗️ Architecture ### Components - **FastMCP Core**: High-performance MCP server framework - **Freedcamp API Client**: Secure, authenticated API wrapper - **MCPO Proxy**: OpenAPI generation and REST interface - **Docker Environment**: Containerized deployment with health monitoring ### Key Features - **Robust Error Handling**: Comprehensive error management and logging - **Data Formatting**: Consistent response structures across all endpoints - **Security**: Secure credential management and API authentication - **Performance**: Optimized queries with pagination and filtering - **Reliability**: Health checks, restart policies, and connection management ## 🐳 Deployment ### Production Deployment 1. **Environment Setup:** ```bash # Production environment file FREEDCAMP_API_KEY=prod_api_key FREEDCAMP_API_SECRET=prod_api_secret ``` 2. **Service Scaling:** ```bash docker-compose up -d --scale freedcamp-fastapi=3 ``` 3. **Health Monitoring:** ```bash docker-compose ps # Check service health docker-compose logs -f # Monitor logs ``` ### Development Mode ```bash # Start with hot-reload docker-compose -f docker-compose.yml -f docker-compose.dev.yml up ``` ## 🔧 Development ### Project Structure ``` freedcamp-mcp-server/ ├── freedcamp_mcp.py # Main MCP server implementation ├── docker-compose.yml # Docker services configuration ├── Dockerfile # Container definition ├── requirements.txt # Python dependencies ├── healthcheck.py # Health monitoring ├── .env # Environment variables ├── .gitignore # Git ignore rules └── README.md # This file ``` ### Adding New Features 1. **Implement the method** in `FreedcampMCP` class 2. **Add the tool decorator** in `_setup_tools()` 3. **Update documentation** and examples 4. **Test with Docker Compose** ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🆘 Support - **Issues**: [GitHub Issues](https://github.com/yourusername/freedcamp-mcp-server/issues) - **Documentation**: [Freedcamp API Docs](https://freedcamp.com/api-docs) - **MCP Protocol**: [Model Context Protocol](https://github.com/modelcontextprotocol/specification) ## 🎯 Roadmap - [ ] **File Upload Support**: Direct file upload capabilities - [ ] **Webhook Integration**: Real-time notifications - [ ] **Advanced Reporting**: Analytics and reporting tools - [ ] **Bulk Operations**: Mass task and project management - [ ] **Custom Field Templates**: Dynamic custom field management - [ ] **Integration Tests**: Comprehensive test suite - [ ] **Performance Optimization**: Query caching and optimization --- **⭐ Star this repository if it helps you manage your Freedcamp projects more effectively!** Made with ❤️ for the Freedcamp and MCP communities.