goodday-mcp

Instructions

Implementation Reference

• goodday_mcp/main.py:1092-1237 (handler)

  The primary handler function for the 'search_goodday_tasks' MCP tool. It performs vector similarity search on Goodday tasks via an external search API (GOODDAY_SEARCH_URL), formats results with user/project mappings, and handles optional filters like project_name, user_name, and include_closed.
  @mcp.tool() async def search_goodday_tasks( query: str, limit: int = 10, project_name: Optional[str] = None, user_name: Optional[str] = None, include_closed: bool = False ) -> str: """Search for tasks using vector similarity search with optional filters. Args: query: Search query (natural language) limit: Maximum number of results to return (default: 10, max: 50) project_name: Optional project name filter (case-insensitive partial match) user_name: Optional user name/email filter for assigned tasks include_closed: Whether to include closed/completed tasks (default: False) """ # Validate limit if limit > 50: limit = 50 elif limit < 1: limit = 1 # Build search parameters search_params = { "query": query, "limit": limit, "include_closed": include_closed } # Add optional filters if project_name: search_params["project_name"] = project_name if user_name: search_params["user_name"] = user_name try: # Make search request search_results = await make_search_request("GET", search_params) if not search_results: return "No results found for your search query." if isinstance(search_results, dict) and "error" in search_results: return f"Search error: {search_results.get('error', 'Unknown error')}" # Handle different response formats results = [] if isinstance(search_results, dict): if "results" in search_results: results = search_results["results"] elif "tasks" in search_results: results = search_results["tasks"] else: # If it's a single result wrapped in a dict results = [search_results] elif isinstance(search_results, list): results = search_results else: return f"Unexpected search results format: {type(search_results)}" if not results: return "No tasks found matching your search criteria." # Get user mapping for display 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 results formatted_results = [] for i, task in enumerate(results, 1): if not isinstance(task, dict): continue # Extract task information task_id = task.get("shortId", task.get("id", "N/A")) task_name = task.get("name", "No title") # Handle status information status = task.get("status", {}) if isinstance(status, dict): status_name = status.get("name", "Unknown") else: status_name = str(status) if status else "Unknown" # Handle project information project = task.get("project", {}) if isinstance(project, dict): project_name = project.get("name", "Unknown Project") else: project_name = str(project) if project else "Unknown Project" # Handle assigned user assigned_user_id = task.get("assignedToUserId") assigned_user = user_display(assigned_user_id) # Handle priority priority = task.get("priority", "N/A") # Handle dates start_date = format_timestamp_ist(task.get("startDate")) if task.get("startDate") else "N/A" end_date = format_timestamp_ist(task.get("endDate")) if task.get("endDate") else "N/A" # Handle description/message description = task.get("message", task.get("description", "No description")) # Handle similarity score if available score_info = "" if "score" in task: score_info = f" (Similarity: {task['score']:.3f})" elif "_score" in task: score_info = f" (Similarity: {task['_score']:.3f})" formatted_result = f""" **{i}. {task_id}**: {task_name}{score_info} - **Project**: {project_name} - **Status**: {status_name} - **Assigned To**: {assigned_user} - **Priority**: {priority} - **Start Date**: {start_date} - **End Date**: {end_date} - **Description**: {description[:200]}{'...' if len(description) > 200 else ''} """.strip() formatted_results.append(formatted_result) result_text = "\n---\n".join(formatted_results) filter_info = [] if project_name: filter_info.append(f"Project: {project_name}") if user_name: filter_info.append(f"User: {user_name}") if include_closed: filter_info.append("Including closed tasks") filter_text = f" (Filters: {', '.join(filter_info)})" if filter_info else "" return f"**Search Results for '{query}'{filter_text}:**\nFound {len(results)} result(s)\n\n{result_text}" except Exception as e: return f"Search error: {str(e)}"
• goodday_mcp/main.py:58-93 (helper)

  Core helper function used by search_goodday_tasks to make authenticated HTTP requests to the external Goodday search API using GOODDAY_SEARCH_BEARER_TOKEN and GOODDAY_SEARCH_URL.
  async def make_search_request(method: str = "GET", params: dict = None) -> dict: """Make a request to the search API with bearer token authentication.""" search_url = os.getenv("GOODDAY_SEARCH_URL", "") bearer_token = os.getenv("GOODDAY_SEARCH_BEARER_TOKEN", "") if not bearer_token: raise ValueError("GOODDAY_SEARCH_BEARER_TOKEN environment variable is required for search API") if not search_url: raise ValueError("GOODDAY_SEARCH_URL environment variable is required for search API") headers = { "User-Agent": USER_AGENT, "Authorization": f"Bearer {bearer_token}", "Content-Type": "application/json" } url = str(search_url).strip() async with httpx.AsyncClient() as client: try: if method.upper() == "GET": response = await client.get(url, headers=headers, params=params, timeout=30.0) else: response = await client.request(method.upper(), url, headers=headers, params=params, timeout=30.0) response.raise_for_status() return response.json() except httpx.HTTPStatusError as e: raise Exception(f"Search API HTTP error {e.response.status_code}: {e.response.text}") except httpx.RequestError as e: raise Exception(f"Search API request error: {str(e)}") except Exception as e: raise Exception(f"Search API unexpected error: {str(e)}")
• goodday_mcp/main.py:165-173 (helper)

  Helper function called by search_goodday_tasks to resolve user IDs to human-readable names in search results.
  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:1092-1093 (registration)

  The @mcp.tool() decorator registers the search_goodday_tasks function with the FastMCP server.
  @mcp.tool() async def search_goodday_tasks(