github-projects-mcp

Instructions

Implementation Reference

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

  The main tool handler: @mcp.tool()-decorated async function list_projects(owner: str) -> str that fetches projects via GitHubClient.get_projects and formats the list or error into a response 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)

  Supporting GitHubClient.get_projects(owner: str) method: determines if owner is user or org via GraphQL, then queries projectsV2 accordingly, returning list of project dicts.
  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}")