goodday-mcp

Instructions

Implementation Reference

• goodday_mcp/main.py:673-771 (handler)

  The core handler function for the 'get_task_details' MCP tool. It resolves project by name, finds task by short ID, retrieves detailed data via Goodday API (task details, messages, subtasks, custom fields), maps users, and returns a richly formatted string with all task information.

  async def get_task_details(task_short_id: str, project_name: str) -> str:
      """Get comprehensive task details including subtasks, custom fields, and full metadata.
  
      Args:
          task_short_id: The short ID of the task (e.g., RAD-434)
          project_name: The name of the project containing the task (required, case-insensitive)
      """
      # Find the project
      matched_project, available_projects = await find_project_by_name(project_name)
      if not matched_project:
          return f"Project '{project_name}' not found. Available projects: {', '.join(available_projects[:10])}{'...' if len(available_projects) > 10 else ''}"
      
      project_id = matched_project.get("id")
      found_in_project = matched_project.get("name")
  
      # Find the task
      tasks_data = await make_goodday_request(f"project/{project_id}/tasks")
      if not tasks_data or not isinstance(tasks_data, list):
          return f"Unable to fetch tasks for project '{found_in_project}'."
      
      task_id = None
      task_data = None
      for task in tasks_data:
          if isinstance(task, dict) and task.get("shortId") == task_short_id:
              task_id = task.get("id")
              task_data = task
              break
      
      if not task_id or not task_data:
          return f"Task with short ID '{task_short_id}' not found in project '{found_in_project}'."
  
      # Get detailed task information
      detailed_data = await make_goodday_request(f"task/{task_id}")
      if not detailed_data:
          return f"No details found for task '{task_short_id}'."
      
      if isinstance(detailed_data, dict) and "error" in detailed_data:
          return f"Unable to fetch task details: {detailed_data.get('error', 'Unknown error')}"
  
      # Get task messages for description
      messages_data = await make_goodday_request(f"task/{task_id}/messages")
      first_message = "No description"
      if messages_data and isinstance(messages_data, list) and len(messages_data) > 0:
          first_msg = messages_data[0]
          if isinstance(first_msg, dict):
              first_message = first_msg.get("message", "No description")
  
      # Get user mapping
      user_id_to_name = await get_user_mapping()
      
      def user_display(user_id):
          if not user_id:
              return "N/A"
          name = user_id_to_name.get(user_id)
          return f"{name} ({user_id})" if name else user_id
  
      # Format comprehensive details
      status = detailed_data.get("status", {}) if isinstance(detailed_data.get("status"), dict) else {}
      task_type = detailed_data.get("taskType", {}) if isinstance(detailed_data.get("taskType"), dict) else {}
      custom_fields = detailed_data.get("customFieldsData", {}) if isinstance(detailed_data.get("customFieldsData"), dict) else {}
      subtasks = detailed_data.get("subtasks", []) if isinstance(detailed_data.get("subtasks"), list) else []
      users = detailed_data.get("users", []) if isinstance(detailed_data.get("users"), list) else []
  
      formatted_details = f"""
  **Task ID:** {detailed_data.get('shortId', 'N/A')}
  **Name:** {detailed_data.get('name', 'N/A')}
  **Project:** {found_in_project}
  **Status:** {status.get('name', 'N/A')}
  **Task Type:** {task_type.get('name', 'N/A')}
  **Priority:** {detailed_data.get('priority', 'N/A')}
  **Assigned To:** {user_display(detailed_data.get('assignedToUserId'))}
  **Action Required:** {user_display(detailed_data.get('actionRequiredUserId'))}
  **Created By:** {user_display(detailed_data.get('createdByUserId'))}
  **Start Date:** {detailed_data.get('startDate', 'N/A')}
  **End Date:** {detailed_data.get('endDate', 'N/A')}
  **Deadline:** {detailed_data.get('deadline', 'N/A')}
  **Estimate:** {detailed_data.get('estimate', 'N/A')}
  **Reported Time:** {detailed_data.get('reportedTime', 'N/A')}
  **Users:** {', '.join([user_display(uid) for uid in users]) if users else 'N/A'}
  **Subtasks Count:** {len(subtasks)}
  **Description:** {first_message}
  """.strip()
  
      # Add custom fields if they exist
      if custom_fields:
          formatted_details += "\n\n**Custom Fields:**"
          for field_id, field_value in custom_fields.items():
              formatted_details += f"\n- {field_id}: {field_value}"
  
      # Add subtasks if they exist
      if subtasks:
          formatted_details += f"\n\n**Subtasks ({len(subtasks)}):**"
          for i, subtask in enumerate(subtasks[:10]):
              if isinstance(subtask, dict):
                  formatted_details += f"\n- {subtask.get('shortId', 'N/A')}: {subtask.get('name', 'N/A')}"
          if len(subtasks) > 10:
              formatted_details += f"\n... and {len(subtasks) - 10} more subtasks"
  
      return f"**Task Details for '{task_short_id}' in project '{found_in_project}':**\n\n{formatted_details}"

• goodday_mcp/main.py:185-219 (helper)

  Helper function used by get_task_details to locate the project by name from all projects, filtering out system projects like sprints.

  async def find_project_by_name(project_name: str) -> tuple[Optional[dict], List[str]]:
      """Find project by name (case-insensitive)."""
      projects_data = await make_goodday_request("projects")
      if not projects_data or not isinstance(projects_data, list):
          return None, []
      
      # Filter out system projects (like sprints) to avoid overwhelming the AI
      filtered_projects = [
          proj for proj in projects_data 
          if isinstance(proj, dict) and proj.get("systemType") != "PROJECT"
      ]
      
      project_name_lower = project_name.lower().strip()
      matched_project = None
      for proj in filtered_projects:
          if not isinstance(proj, dict):
              continue
          current_project_name = proj.get("name", "").lower().strip()
          if current_project_name == project_name_lower:
              matched_project = proj
              break
          if (
              project_name_lower in current_project_name
              or current_project_name in project_name_lower
          ):
              matched_project = proj
              break
      
      available_projects = [
          p.get("name", "Unknown")
          for p in projects_data
          if isinstance(p, dict)
      ]
      return matched_project, available_projects

• goodday_mcp/main.py:165-174 (helper)

  Helper that fetches all users and creates a mapping from user ID to name, used for displaying user info in task details.

  async def get_user_mapping() -> dict:
      """Get mapping of user IDs to names."""
      data = await make_goodday_request("users")
      user_id_to_name = {}
      if isinstance(data, list):
          for u in data:
              if isinstance(u, dict):
                  user_id_to_name[u.get("id")] = u.get("name", "Unknown")
      return user_id_to_name

• goodday_mcp/main.py:673-673 (registration)

  The @mcp.tool() decorator registers the get_task_details function as an MCP tool with the name 'get_task_details'.

  async def get_task_details(task_short_id: str, project_name: str) -> str: