goodday-mcp

# Goodday MCP Server A Model Context Protocol (MCP) server for integrating with Goodday project management platform. This server provides tools for managing projects, tasks, and users through the Goodday API v2. ## Features ### Project Management - **get_projects**: Retrieve list of projects (with options for archived and root-only filtering) - **get_project**: Get detailed information about a specific project - **create_project**: Create new projects with customizable templates and settings - **get_project_users**: Get users associated with a specific project ### Task Management - **get_project_tasks**: Retrieve tasks from specific projects (with options for closed tasks and subfolders) - **get_user_assigned_tasks**: Get tasks assigned to a specific user - **get_user_action_required_tasks**: Get action-required tasks for a user - **get_task**: Get detailed information about a specific task - **get_task_details**: Get comprehensive task details including subtasks, custom fields, and full metadata - **get_task_messages**: Retrieve all messages/comments for a specific task - **create_task**: Create new tasks with full customization (subtasks, assignments, dates, priorities) - **update_task_status**: Update task status with optional comments - **add_task_comment**: Add comments to tasks ### Sprint Management - **get_goodday_sprint_tasks**: Get tasks from specific sprints by project name and sprint name/number - **get_goodday_sprint_summary**: Generate comprehensive sprint summaries with task details, status distribution, and key metrics ### User Management - **get_users**: Retrieve list of organization users - **get_user**: Get detailed information about a specific user ### Smart Query & Search - **get_goodday_smart_query**: Natural language interface for common project management queries - **search_goodday_tasks**: Semantic search across tasks using VectorDB backend - **search_project_documents**: Search for documents within specific projects - **get_document_content**: Retrieve full content of specific documents ## OpenWebUI Integration This package also includes an OpenWebUI tool that provides a complete interface for Goodday project management directly in chat interfaces. The OpenWebUI tool includes: ### Features - **Project Management**: Get projects, project tasks, and project details - **Sprint Management**: Get tasks from specific sprints by name/number, comprehensive sprint summaries - **User Management**: Get tasks assigned to specific users, user details - **Task Details**: Get comprehensive task information including subtasks, custom fields, and metadata - **Task Messages**: Retrieve all messages and comments for tasks - **Smart Query**: Natural language interface for common project management requests - **Semantic Search**: Search across tasks using VectorDB backend with embeddings - **Document Management**: Search project documents and retrieve document content - **Advanced Filtering**: Support for archived projects, closed tasks, subfolders, and more ### Setup 1. Copy `openwebui/goodday_openwebui_complete_tool.py` to your OpenWebUI tools directory 2. Configure the valves with your API credentials: - `api_key`: Your Goodday API token - `search_url`: Your VectorDB search endpoint (optional) - `bearer_token`: Bearer token for search API (optional) ### Vector Database Setup (Optional) For semantic search functionality, you can set up a vector database using the provided n8n workflow (`openwebui/n8n-workflow-goodday-vectordb.json`). This workflow: - Fetches all Goodday projects and tasks - Extracts task messages and content - Creates embeddings using Ollama - Stores in Qdrant vector database - Provides search API endpoint See `openwebui/OPENWEBUI_TOOL_README.md` for detailed usage instructions. ## Installation ### From PyPI (Recommended) ```bash pip install goodday-mcp ``` ### From Source #### Prerequisites - Python 3.10 or higher - UV package manager (recommended) or pip - Goodday API token #### Setup with UV 1. **Install UV** (if not already installed): ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Clone and set up the project**: ```bash git clone https://github.com/cdmx1/goodday-mcp.git cd goodday-mcp # Create virtual environment and install dependencies uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv sync ``` #### Setup with pip ```bash git clone https://github.com/cdmx1/goodday-mcp.git cd goodday-mcp pip install -e . ``` ### Configuration 1. **Set up environment variables**: Create a `.env` file in your project root or export the variable: ```bash export GOODDAY_API_TOKEN=your_goodday_api_token_here ``` To get your Goodday API token: - Go to your Goodday organization - Navigate to Settings → API - Click the generate button to create a new token ## Usage ### Running the Server Standalone If installed from PyPI: ```bash goodday-mcp ``` If running from source with UV: ```bash uv run goodday-mcp ``` ### Using with Claude Desktop 1. **Configure Claude Desktop** by editing your configuration file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` 2. **Add the server configuration**: **Option A: If installed from PyPI:** ```json { "mcpServers": { "goodday": { "command": "goodday-mcp", "env": { "GOODDAY_API_TOKEN": "your_goodday_api_token_here" } } } } ``` **Option B: If running from source:** ```json { "mcpServers": { "goodday": { "command": "uv", "args": ["run", "goodday-mcp"], "env": { "GOODDAY_API_TOKEN": "your_goodday_api_token_here" } } } } ``` 3. **Restart Claude Desktop** to load the new server. ### Using with Other MCP Clients The server communicates via stdio transport and can be integrated with any MCP-compatible client. Refer to the [MCP documentation](https://modelcontextprotocol.io/) for client-specific integration instructions. ## API Reference ### Environment Variables | Variable | Description | Required | |----------|-------------|----------| | `GOODDAY_API_TOKEN` | Your Goodday API token | Yes | ### Tool Examples #### Get Projects ```python # Get all active projects get_projects() # Get archived projects get_projects(archived=True) # Get only root-level projects get_projects(root_only=True) ``` #### Create a Task ```python create_task( project_id="project_123", title="Implement new feature", from_user_id="user_456", message="Detailed description of the task", to_user_id="user_789", deadline="2025-06-30", priority=5 ) ``` #### Update Task Status ```python update_task_status( task_id="task_123", user_id="user_456", status_id="status_completed", message="Task completed successfully" ) ``` ## Data Formats ### Date Format All dates should be provided in `YYYY-MM-DD` format (e.g., `2025-06-16`). ### Priority Levels - 1-10: Normal priority levels - 50: Blocker - 100: Emergency ### Project Colors Project colors are specified as integers from 1-24, corresponding to Goodday's color palette. ## Error Handling The server includes comprehensive error handling: - **Authentication errors**: When API token is missing or invalid - **Network errors**: When Goodday API is unreachable - **Validation errors**: When required parameters are missing - **Permission errors**: When user lacks permissions for requested operations All errors are returned as descriptive strings to help with troubleshooting. ## Development ### Project Structure ``` goodday-mcp/ ├── goodday_mcp/ # Main package directory │ ├── __init__.py # Package initialization │ └── main.py # Main MCP server implementation ├── pyproject.toml # Project configuration and dependencies ├── README.md # This file ├── LICENSE # MIT license ├── uv.lock # Dependency lock file └── .env # Environment variables (create this) ``` ### Adding New Tools To add new tools to the server: 1. **Add the tool function** in `goodday_mcp/main.py` using the `@mcp.tool()` decorator: ```python @mcp.tool() async def your_new_tool(param1: str, param2: Optional[int] = None) -> str: """Description of what the tool does. Args: param1: Description of parameter 1 param2: Description of optional parameter 2 """ # Implementation here return "Result" ``` 2. **Test the tool** by running the server and testing with an MCP client. ### Testing Test the server by running it directly: ```bash # If installed from PyPI goodday-mcp # If running from source uv run goodday-mcp ``` The server will start and wait for MCP protocol messages via stdin/stdout. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Support For issues related to: - **MCP Server**: Create an issue in this repository - **Goodday API**: Refer to [Goodday API documentation](https://www.goodday.work/developers/api-v2) - **MCP Protocol**: Refer to [MCP documentation](https://modelcontextprotocol.io/) ## Changelog ### v1.1.0 (Current) - **Enhanced Task Management**: Added `get_task_details` and `get_task_messages` for comprehensive task information - **Sprint Management**: Added `get_goodday_sprint_tasks` and `get_goodday_sprint_summary` for sprint tracking - **Smart Query Interface**: Added `get_goodday_smart_query` for natural language project queries - **Semantic Search**: Added `search_goodday_tasks` with VectorDB integration for intelligent task search - **Document Management**: Added `search_project_documents` and `get_document_content` for document handling - **Improved Error Handling**: Enhanced error messages and status reporting - **Advanced Filtering**: Support for archived projects, closed tasks, and subfolder inclusion ### v1.0.0 - Initial release - Full project management capabilities - Task management with comments and status updates - User management - Comprehensive error handling - UV support with modern Python packaging