goodday-mcp

Instructions

Implementation Reference

• goodday_mcp/main.py:941-1047 (handler)

  Core handler function implementing the get_goodday_sprint_summary tool. It finds the project and sprint, fetches tasks, analyzes status distribution, task assignments, fetches descriptions, and generates a formatted summary report.

  @mcp.tool()
  async def get_goodday_sprint_summary(project_name: str, sprint_name: str) -> str:
      """Generate a comprehensive sprint summary with task details, status distribution, and key metrics.
  
      Args:
          project_name: The name of the main project (e.g., "ASTRA")
          sprint_name: The name or number of the sprint (e.g., "Sprint 233", "233")
      """
      # Find main 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 ''}"
  
      main_project_id = matched_project.get("id")
      actual_project_name = matched_project.get("name")
  
      # Find sprint project
      sprint_project, available_sprints = await find_sprint_by_name(main_project_id, sprint_name)
      if not sprint_project:
          if available_sprints:
              return f"Sprint '{sprint_name}' not found. Available sprints: {', '.join(available_sprints)}"
          else:
              return f"No sprints found under project '{actual_project_name}'."
  
      sprint_id = sprint_project.get("id")
      actual_sprint_name = sprint_project.get("name")
  
      # Get all tasks with closed tasks included
      endpoint = f"project/{sprint_id}/tasks?closed=true"
      tasks_data = await make_goodday_request(endpoint)
      if not tasks_data:
          return f"No tasks found in sprint '{actual_sprint_name}'."
      
      if isinstance(tasks_data, dict) and "error" in tasks_data:
          return f"Unable to fetch sprint tasks: {tasks_data.get('error', 'Unknown error')}"
      
      if not isinstance(tasks_data, list):
          return f"Unexpected response format: {str(tasks_data)}"
  
      # Get user mapping
      user_id_to_name = await get_user_mapping()
      
      def user_display(user_id):
          if not user_id:
              return "Unassigned"
          name = user_id_to_name.get(user_id)
          return name if name else f"User {user_id}"
  
      # Analyze tasks
      status_counts = {}
      user_task_counts = {}
      task_summaries = []
  
      for task in tasks_data:
          if not isinstance(task, dict):
              continue
  
          task_short_id = task.get("shortId", "N/A")
          task_name = task.get("name", "No title")
          status = task.get("status", {}) if isinstance(task.get("status"), dict) else {}
          status_name = status.get("name", "Unknown Status")
          assigned_user_id = task.get("assignedToUserId")
          assigned_user = user_display(assigned_user_id)
  
          # Count statistics
          status_counts[status_name] = status_counts.get(status_name, 0) + 1
          user_task_counts[assigned_user] = user_task_counts.get(assigned_user, 0) + 1
  
          # Get task description
          task_description = "No description available"
          task_id = task.get("id")
          if task_id:
              try:
                  messages_endpoint = f"task/{task_id}/messages"
                  messages_data = await make_goodday_request(messages_endpoint)
                  if messages_data and isinstance(messages_data, list) and len(messages_data) > 0:
                      first_msg = messages_data[0]
                      if isinstance(first_msg, dict):
                          task_description = first_msg.get("message", "No description available")
              except Exception:
                  pass
  
          task_summary = f"""
  **{task_short_id}**: {task_name}
  - **Status**: {status_name}
  - **Assigned To**: {assigned_user}
  - **Description**: {task_description}
  """.strip()
          task_summaries.append(task_summary)
  
      # Build summary
      summary_parts = []
      summary_parts.append(f"**Sprint Overview:**\n- **Sprint**: {actual_sprint_name}\n- **Project**: {actual_project_name}\n- **Total Tasks**: {len(tasks_data)}")
  
      if status_counts:
          status_list = [f"  - {status}: {count}" for status, count in sorted(status_counts.items())]
          summary_parts.append(f"**Status Distribution:**\n{chr(10).join(status_list)}")
  
      if user_task_counts:
          user_list = [f"  - {user}: {count} tasks" for user, count in sorted(user_task_counts.items(), key=lambda x: x[1], reverse=True)]
          summary_parts.append(f"**Task Assignment:**\n{chr(10).join(user_list)}")
  
      if task_summaries:
          summary_parts.append(f"**Task Details:**\n{chr(10).join(['---'] + task_summaries)}")
  
      result = "\n\n".join(summary_parts)
      return f"**Sprint Summary for '{actual_sprint_name}' in '{actual_project_name}':**\n\n{result}"

• goodday_mcp/main.py:220-268 (helper)

  Helper function to locate the specific sprint project under a parent project by normalizing and matching sprint names/numbers.

  async def find_sprint_by_name(parent_project_id: str, sprint_name: str) -> tuple[Optional[dict], List[str]]:
      """Find sprint project by name within a parent project."""
      projects_data = await make_goodday_request("projects")
      if not projects_data or not isinstance(projects_data, list):
          return None, []
      
      normalized_sprint_name = sprint_name.lower().strip()
      if not normalized_sprint_name.startswith("sprint"):
          normalized_sprint_name = f"sprint {normalized_sprint_name}"
  
      available_sprints = []
      search_number = re.search(r"(\d+)", normalized_sprint_name)
      exact_match = None
      substring_match = None
  
      for proj in projects_data:
          if isinstance(proj, dict) and proj.get("systemType") == "PROJECT":
              sprint_proj_name = proj.get("name", "").lower().strip()
              if sprint_proj_name.startswith("sprint"):
                  available_sprints.append(proj.get("name", ""))
                  project_number = re.search(r"(\d+)", sprint_proj_name)
                  # Prefer exact number match
                  if (
                      search_number
                      and project_number
                      and search_number.group(1) == project_number.group(1)
                  ):
                      exact_match = proj
                  # Fallback: search number as substring anywhere in the sprint name
                  elif (
                      search_number and search_number.group(1) in sprint_proj_name
                  ):
                      if not substring_match:
                          substring_match = proj
                  elif normalized_sprint_name == sprint_proj_name:
                      if not exact_match:
                          exact_match = proj
                  elif (
                      normalized_sprint_name in sprint_proj_name
                      or sprint_proj_name in normalized_sprint_name
                  ):
                      if not substring_match:
                          substring_match = proj
  
      if exact_match:
          return exact_match, available_sprints
      if substring_match:
          return substring_match, available_sprints
      return None, available_sprints

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

  Helper function to find the main project by case-insensitive name matching.

  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-173 (helper)

  Helper to fetch and map user IDs to names, used for displaying assignee names in summaries.

  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:941-941 (registration)

  MCP tool registration decorator applied to the handler function.

  @mcp.tool()