goodday-mcp

Instructions

Implementation Reference

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

  The core handler function for the 'get_projects' MCP tool. It is registered via @mcp.tool() decorator, fetches projects from the Goodday API endpoint 'projects' (with optional params), handles errors, and formats the results using format_project helper.
  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-133 (helper)

  Helper function used by get_projects to format individual project data into a human-readable markdown string.
  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 API request helper used by get_projects to make authenticated HTTP requests to Goodday API endpoints, specifically called with 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)}")