goodday-mcp

Instructions

Implementation Reference

• goodday_mcp/main.py:287-319 (handler)

  The handler function for the get_projects MCP tool. It fetches projects from the Goodday API endpoint 'projects' with optional archived and root_only parameters, handles errors, formats each project using format_project helper, and returns a joined string of formatted projects.

  async def get_projects(archived: bool = False, root_only: bool = False) -> str:
      """Get list of projects from Goodday.
  
      Args:
          archived: Set to true to retrieve archived/closed projects
          root_only: Set to true to return only root projects
      """
      params = []
      if archived:
          params.append("archived=true")
      if root_only:
          params.append("rootOnly=true")
      
      endpoint = "projects"
      if params:
          endpoint += "?" + "&".join(params)
      
      data = await make_goodday_request(endpoint)
      
      if not data:
          return "No projects found."
          
      if isinstance(data, dict):
          if "error" in data:
              return f"Unable to fetch projects: {data.get('error', 'Unknown error')}"
      elif isinstance(data, str):
          return f"Unexpected string response from API: {data}"
      elif not isinstance(data, list):
          return f"Unexpected response format: {type(data).__name__} - {str(data)}"
      
      projects = [format_project(project) for project in data]
      return "\n---\n".join(projects)

• goodday_mcp/main.py:115-134 (helper)

  Helper function used by get_projects to format individual project data into a human-readable string, including defensive checks for nested dicts.

  def format_project(project: dict) -> str:
      """Format a project into a readable string with safe checks."""
      if not isinstance(project, dict):
          return f"Invalid project data: {repr(project)}"
  
      # Defensive defaults in case nested keys are not dicts
      status = project.get('status') if isinstance(project.get('status'), dict) else {}
      owner = project.get('owner') if isinstance(project.get('owner'), dict) else {}
  
      return f"""
  Project ID: {project.get('id', 'N/A')}
  Name: {project.get('name', 'N/A')}
  Health: {project.get('health', 'N/A')}
  Status: {status.get('name', 'N/A')}
  Start Date: {project.get('startDate', 'N/A')}
  End Date: {project.get('endDate', 'N/A')}
  Progress: {project.get('progress', 0)}%
  Owner: {owner.get('name', 'N/A')}
  """.strip()

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

  Core helper function for making authenticated requests to the Goodday API, used by get_projects to fetch the projects list from endpoint 'projects'.

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