goodday-mcp

Instructions

Implementation Reference

• goodday_mcp/main.py:1240-1333 (handler)

  The handler function implementing the 'search_project_documents' MCP tool. It locates the project, retrieves and filters documents, optionally fetches and includes content, and returns formatted results.

  async def search_project_documents(project_name: str, document_name: Optional[str] = None, include_content: bool = False) -> str:
      """Search for documents in a specific project.
  
      Args:
          project_name: The name of the project to search in (case-insensitive)
          document_name: Optional document name to filter by (case-insensitive partial match)
          include_content: Whether to include the full content of each document
      """
      # Find project
      projects_data = await make_goodday_request("projects?archived=true")
      if not projects_data or not isinstance(projects_data, list):
          return "Unable to fetch projects."
  
      project_type_projects = [p for p in projects_data if isinstance(p, dict) and p.get('systemType') in ['PROJECT', 'FOLDER']]
      matching_projects = []
      search_term = project_name.lower()
      for project in project_type_projects:
          if isinstance(project, dict) and search_term in project.get('name', '').lower():
              matching_projects.append(project)
  
      if not matching_projects:
          return f"No projects found containing '{project_name}' in their name."
  
      target_project = matching_projects[0]
      actual_project_name = target_project.get('name')
      project_id = target_project.get('id')
  
      # Get documents
      documents_data = await make_goodday_request(f"project/{project_id}/documents")
      if not documents_data:
          return f"No documents found in project '{actual_project_name}'."
  
      if isinstance(documents_data, dict) and "error" in documents_data:
          return f"Unable to fetch documents: {documents_data.get('error', 'Unknown error')}"
  
      if not isinstance(documents_data, list):
          return f"Unexpected response format for documents: {str(documents_data)}"
  
      # Filter by document name if specified
      if document_name:
          filtered_documents = []
          for doc in documents_data:
              if isinstance(doc, dict) and document_name.lower() in doc.get('name', '').lower():
                  filtered_documents.append(doc)
          documents_data = filtered_documents
  
      if not documents_data:
          return f"No documents found matching '{document_name}' in project '{actual_project_name}'."
  
      # Get mappings
      user_id_to_name = await get_user_mapping()
      project_id_to_name = await get_project_mapping()
  
      # Format documents
      formatted_docs = []
      for doc in documents_data:
          if isinstance(doc, dict):
              doc_id = doc.get('id', 'N/A')
              doc_content = ""
              
              if include_content and doc_id != 'N/A':
                  try:
                      content_data = await make_goodday_request(f"document/{doc_id}")
                      if content_data:
                          if isinstance(content_data, dict):
                              doc_content = content_data.get('content', content_data.get('text', str(content_data)))
                          else:
                              doc_content = str(content_data)
                  except Exception as e:
                      doc_content = f"Error fetching content: {str(e)}"
              
              project_id_val = doc.get('projectId', 'N/A')
              project_name_val = project_id_to_name.get(project_id_val, f"Project {project_id_val}") if project_id_val != 'N/A' else 'N/A'
              
              created_by_id = doc.get('createdByUserId', 'N/A')
              created_by_name = user_id_to_name.get(created_by_id, f"User {created_by_id}") if created_by_id != 'N/A' else 'N/A'
              
              formatted_doc = f"""
  **Document ID:** {doc_id}
  **Name:** {doc.get('name', 'N/A')}
  **Project:** {project_name_val}
  **Created By:** {created_by_name}
  **Created:** {format_timestamp_ist(doc.get('momentCreated', 'N/A'))}
  **Updated:** {format_timestamp_ist(doc.get('momentUpdated', 'N/A'))}"""
              
              if include_content:
                  formatted_doc += f"\n**Content:**\n{doc_content}"
              
              formatted_docs.append(formatted_doc.strip())
  
      result = "\n---\n".join(formatted_docs)
      filter_text = f" matching '{document_name}'" if document_name else ""
      return f"**Documents in project '{actual_project_name}'{filter_text}:**\n\n{result}"

• goodday_mcp/main.py:1240-1240 (registration)

  The @mcp.tool() decorator registers the search_project_documents function as an MCP tool.

  async def search_project_documents(project_name: str, document_name: Optional[str] = None, include_content: bool = False) -> str:

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

  Helper function used by search_project_documents to make API requests to Goodday.

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

• goodday_mcp/main.py:176-183 (helper)

  Helper function providing project ID to name mapping, used in formatting documents.

  """Get mapping of project IDs to names."""
  data = await make_goodday_request("projects")
  project_id_to_name = {}
  if isinstance(data, list):
      for p in data:
          if isinstance(p, dict):
              project_id_to_name[p.get("id")] = p.get("name", "Unknown")
  return project_id_to_name

• goodday_mcp/main.py:166-173 (helper)

  Helper function providing user ID to name mapping, used in formatting documents.

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