goodday-mcp

Instructions

Implementation Reference

• goodday_mcp/main.py:494-561 (handler)

  The handler function for the 'create_task' MCP tool. It constructs a POST request payload for the Goodday API endpoint '/tasks', sends it using make_goodday_request, handles errors, and formats the response using format_task.

  async def create_task(
      project_id: str,
      title: str,
      from_user_id: str,
      parent_task_id: Optional[str] = None,
      message: Optional[str] = None,
      to_user_id: Optional[str] = None,
      task_type_id: Optional[str] = None,
      start_date: Optional[str] = None,
      end_date: Optional[str] = None,
      deadline: Optional[str] = None,
      estimate: Optional[int] = None,
      story_points: Optional[int] = None,
      priority: Optional[int] = None
  ) -> str:
      """Create a new task in Goodday.
  
      Args:
          project_id: Task project ID
          title: Task title
          from_user_id: Task created by user ID  
          parent_task_id: Parent task ID to create a subtask
          message: Task description/initial message
          to_user_id: Assigned To/Action required user ID
          task_type_id: Task type ID
          start_date: Task start date (YYYY-MM-DD)
          end_date: Task end date (YYYY-MM-DD)
          deadline: Task deadline (YYYY-MM-DD)
          estimate: Task estimate in minutes
          story_points: Task story points estimate
          priority: Task priority (1-10), 50 - Blocker, 100 - Emergency
      """
      data = {
          "projectId": project_id,
          "title": title,
          "fromUserId": from_user_id
      }
      
      if parent_task_id:
          data["parentTaskId"] = parent_task_id
      if message:
          data["message"] = message
      if to_user_id:
          data["toUserId"] = to_user_id
      if task_type_id:
          data["taskTypeId"] = task_type_id
      if start_date:
          data["startDate"] = start_date
      if end_date:
          data["endDate"] = end_date
      if deadline:
          data["deadline"] = deadline
      if estimate:
          data["estimate"] = estimate
      if story_points:
          data["storyPoints"] = story_points
      if priority:
          data["priority"] = priority
      
      result = await make_goodday_request("tasks", "POST", data)
      
      if not result:
          return "Unable to create task: No response received"
      
      if isinstance(result, dict) and "error" in result:
          return f"Unable to create task: {result.get('error', 'Unknown error')}"
      
      return f"Task created successfully: {format_task(result)}"

• goodday_mcp/main.py:94-113 (helper)

  Helper function to format the task dictionary returned from the API into a human-readable string, used in the create_task response.

  def format_task(task: dict) -> str:
      """Format a task into a readable string with safe checks."""
      if not isinstance(task, dict):
          return f"Invalid task data: {repr(task)}"
  
      # Defensive defaults in case nested keys are not dicts
      status = task.get('status') if isinstance(task.get('status'), dict) else {}
      project = task.get('project') if isinstance(task.get('project'), dict) else {}
  
      return f"""
  **Task ID:** {task.get('shortId', 'N/A')}
  **Title:** {task.get('name', 'N/A')}
  **Status:** {status.get('name', 'N/A')}
  **Project:** {project.get('name', 'N/A')}
  **Assigned To:** {task.get('assignedToUserId', 'N/A')}
  **Priority:** {task.get('priority', 'N/A')}
  **Start Date:** {task.get('startDate', 'N/A')}
  **End Date:** {task.get('endDate', 'N/A')}
  **Description:** {task.get('message', 'No description')}
  """.strip()

• goodday_mcp/main.py:15-57 (helper)

  Core helper function that makes authenticated HTTP requests to the Goodday API, used by create_task to POST to the /tasks endpoint.

  async def make_goodday_request(endpoint: str, method: str = "GET", data: dict = None, subfolders: bool = True) -> dict[str, Any] | list[Any] | None:
      """Make a request to the Goodday API with proper error handling."""
      api_token = os.getenv("GOODDAY_API_TOKEN")
      if not api_token:
          raise ValueError("GOODDAY_API_TOKEN environment variable is required")
      
      headers = {
          "User-Agent": USER_AGENT,
          "gd-api-token": api_token,
          "Content-Type": "application/json"
      }
      
      # Automatically add subfolders=true for project task and document endpoints if not already present
      if subfolders and endpoint.startswith("project/") and ("/tasks" in endpoint or "/documents" in endpoint):
          if "?" in endpoint:
              if "subfolders=" not in endpoint:
                  endpoint += "&subfolders=true"
          else:
              endpoint += "?subfolders=true"
      
      url = f"{GOODDAY_API_BASE}/{endpoint.lstrip('/')}"
      
      async with httpx.AsyncClient() as client:
          try:
              if method.upper() == "POST":
                  response = await client.post(url, headers=headers, json=data, timeout=30.0)
              elif method.upper() == "PUT":
                  response = await client.put(url, headers=headers, json=data, timeout=30.0)
              elif method.upper() == "DELETE":
                  response = await client.delete(url, headers=headers, timeout=30.0)
              else:
                  response = await client.get(url, headers=headers, timeout=30.0)
  
              response.raise_for_status()
              return response.json()
  
          except httpx.HTTPStatusError as e:
              raise Exception(f"HTTP error {e.response.status_code}: {e.response.text}")
          except httpx.RequestError as e:
              raise Exception(f"Request error: {str(e)}")
          except Exception as e:
              raise Exception(f"Unexpected error: {str(e)}")