github-projects-mcp

Instructions

Args:
    owner: The GitHub organization or user name

Returns:
    A formatted string with project details

Implementation Reference

• src/github_projects_mcp/server.py:41-69 (handler)

  The handler function for the 'list_projects' tool, decorated with @mcp.tool() for registration. It fetches projects using the GitHubClient helper and formats the results as a string.

  @mcp.tool()
  async def list_projects(owner: str) -> str:
      """List GitHub Projects V2 for a given organization or user.
  
      Args:
          owner: The GitHub organization or user name
  
      Returns:
          A formatted string with project details
      """
      try:
          projects = await github_client.get_projects(owner)
  
          if not projects:
              return f"No projects found for {owner}"
  
          result = f"Projects for {owner}:\n\n"
          for project in projects:
              result += f"- ID: {project['id']}\n"
              result += f"  Number: {project['number']}\n"
              result += f"  Title: {project['title']}\n"
              result += f"  URL: {project['url']}\n"
              result += "\n"
  
          return result
      except GitHubClientError as e:
          logger.error(f"Error listing projects for {owner}: {e}")
          return f"Error: Could not list projects for {owner}. Details: {e}"

• src/github_projects_mcp/github_client.py:120-240 (helper)

  The helper method in GitHubClient class that implements the core logic for retrieving GitHub Projects V2 via GraphQL queries, distinguishing between organization and user owners.

  async def get_projects(self, owner: str) -> List[Dict[str, Any]]:
      """Get Projects V2 for an organization or user.
  
      Args:
          owner: The GitHub organization or user name
  
      Returns:
          List of projects
  
      Raises:
          GitHubClientError: If the owner is not found or projects cannot be retrieved.
      """
      # First determine if this is a user or organization
      query = """
      query GetOwnerType($login: String!) {
        organization(login: $login) {
          id
          login
          __typename
        }
        user(login: $login) {
          id
          login
          __typename
        }
      }
      """
  
      variables = {"login": owner}
  
      try:
          result = await self.execute_query(query, variables)
      except GitHubClientError as e:
          logger.error(f"Failed to determine owner type for {owner}: {e}")
          raise  # Re-raise the error
  
      # Determine if the owner is a user or organization
      owner_type = None
      owner_id = None
  
      if result.get("organization"):
          owner_type = "organization"
          owner_id = result["organization"]["id"]
      elif result.get("user"):
          owner_type = "user"
          owner_id = result["user"]["id"]
      else:
          error_message = f"Owner {owner} not found or type could not be determined."
          logger.error(error_message)
          raise GitHubClientError(error_message)
  
      # Now get the projects based on owner type
      if owner_type == "organization":
          query = """
          query GetOrgProjects($login: String!, $first: Int!) {
            organization(login: $login) {
              projectsV2(first: $first) {
                nodes {
                  id
                  number
                  title
                  shortDescription
                  url
                  closed
                  public
                }
              }
            }
          }
          """
  
          variables = {"login": owner, "first": 50}
  
          try:
              result = await self.execute_query(query, variables)
              if not result.get("organization") or not result["organization"].get(
                  "projectsV2"
              ):
                  raise GitHubClientError(
                      f"Could not retrieve projects for organization {owner}"
                  )
              return result["organization"]["projectsV2"]["nodes"]
          except GitHubClientError as e:
              logger.error(f"Failed to get projects for organization {owner}: {e}")
              raise
  
      elif owner_type == "user":
          query = """
          query GetUserProjects($login: String!, $first: Int!) {
            user(login: $login) {
              projectsV2(first: $first) {
                nodes {
                  id
                  number
                  title
                  shortDescription
                  url
                  closed
                  public
                }
              }
            }
          }
          """
  
          variables = {"login": owner, "first": 50}
  
          try:
              result = await self.execute_query(query, variables)
              if not result.get("user") or not result["user"].get("projectsV2"):
                  raise GitHubClientError(
                      f"Could not retrieve projects for user {owner}"
                  )
              return result["user"]["projectsV2"]["nodes"]
          except GitHubClientError as e:
              logger.error(f"Failed to get projects for user {owner}: {e}")
              raise
  
      # This part should be unreachable if owner_type is determined correctly
      raise GitHubClientError(f"Unexpected error retrieving projects for {owner}")