goodday-mcp

Instructions

Implementation Reference

• goodday_mcp/main.py:864-940 (handler)

  Primary handler for the 'get_goodday_sprint_tasks' MCP tool. Locates sprint by project and sprint names, fetches tasks via API, formats with user mappings, returns structured output. Includes registration via @mcp.tool() decorator.

  @mcp.tool()
  async def get_goodday_sprint_tasks(project_name: str, sprint_name: str, include_closed: bool = True) -> str:
      """Get tasks from a specific sprint by project name and sprint name/number.
  
      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")
          include_closed: Whether to include closed tasks (default: True)
      """
      # 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 tasks from sprint
      params = []
      if include_closed:
          params.append("closed=true")
      endpoint = f"project/{sprint_id}/tasks"
      if params:
          endpoint += "?" + "&".join(params)
  
      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}"
  
      # Format tasks
      formatted_tasks = []
      for task in tasks_data:
          if not isinstance(task, dict):
              continue
  
          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)
  
          formatted_task = f"""
  **{task.get('shortId', 'N/A')}**: {task.get('name', 'No title')}
  - **Status**: {status_name}
  - **Assigned To**: {assigned_user}
  - **Priority**: {task.get('priority', 'N/A')}
  """.strip()
          formatted_tasks.append(formatted_task)
  
      result = "\n---\n".join(formatted_tasks)
      return f"**Tasks in Sprint '{actual_sprint_name}' (Project: '{actual_project_name}') - {len(tasks_data)} tasks:**\n\n{result}"

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

  Helper function to find the main project by name using fuzzy matching, filters out sprint projects, returns project data and list of available projects. Used by the tool to locate the parent project.

  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:220-269 (helper)

  Key helper to locate sprint sub-project by name or number under parent project using number matching and fuzzy search. Returns sprint data and available sprints list. Critical for tool's sprint identification.

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

  Helper to fetch and cache user ID to name mapping from API, used for displaying assignee names in task outputs.

  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:15-57 (helper)

  Core API client helper for all Goodday requests, handles auth, auto-subfolders param, error handling, used by tool to fetch projects, sprints, tasks.

  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)}")