github-projects-mcp

Instructions

Implementation Reference

• src/github_projects_mcp/server.py:71-113 (handler)

  The main handler function for the 'get_project_fields' tool, decorated with @mcp.tool() for automatic registration in FastMCP. It takes owner and project_number, calls the GitHub client helper, processes the fields details, and returns a formatted string with field names, IDs, types, and options for SingleSelect fields.
  @mcp.tool() async def get_project_fields(owner: str, project_number: int) -> str: """Get fields available in a GitHub Project V2, including options for SingleSelect fields. Args: owner: The GitHub organization or user name project_number: The project number Returns: A formatted string with field details. """ try: # Use the new method that returns structured data fields_details = await github_client.get_project_fields_details( owner, project_number ) if not fields_details: return f"No fields found for project #{project_number} in {owner}" result = f"Fields for project #{project_number} in {owner}:\n\n" for field_name, details in fields_details.items(): result += f"- Name: {field_name}\n" result += f" ID: {details['id']}\n" result += f" Type: {details['type']}\n" # Show options if it's a SingleSelect field if details["type"] == "ProjectV2SingleSelectField" and details.get( "options" ): result += " Options (Name: ID):\n" for opt_name, opt_id in details["options"].items(): result += f" - {opt_name}: {opt_id}\n" # TODO: Add similar display for Iteration fields if needed result += "\n" return result except GitHubClientError as e: logger.error(f"Error getting fields for project {owner}/{project_number}: {e}") return f"Error: Could not get fields for project {owner}/{project_number}. Details: {e}"
• src/github_projects_mcp/github_client.py:289-383 (helper)

  Supporting helper function in GitHubClient class that retrieves detailed project fields via GraphQL query, including field IDs, types, single-select options (name to ID map), and iteration configurations. Called by the main handler.
  async def get_project_fields_details( self, owner: str, project_number: int ) -> Dict[str, Dict[str, Any]]: """ Get fields for a GitHub Project V2, returning a structured dictionary. Args: owner: The GitHub organization or user name project_number: The project number Returns: Dictionary mapping field name to its details (id, type, options). Raises: GitHubClientError: If project or fields cannot be retrieved. """ try: project_id = await self.get_project_node_id(owner, project_number) except GitHubClientError as e: logger.error(f"Cannot get fields details: {e}") raise query = """ query GetProjectFields($projectId: ID!) { node(id: $projectId) { ... on ProjectV2 { fields(first: 50) { nodes { ... on ProjectV2Field { id name __typename } ... on ProjectV2IterationField { id name __typename configuration { iterations { id title startDate duration } } } ... on ProjectV2SingleSelectField { id name __typename options { id name color description } } # Add other field types if needed } } } } } """ variables = {"projectId": project_id} try: result = await self.execute_query(query, variables) if not result.get("node") or not result["node"].get("fields"): raise GitHubClientError( f"Could not retrieve fields for project {owner}/{project_number}" ) fields_nodes = result["node"]["fields"]["nodes"] field_details_map: Dict[str, Dict[str, Any]] = {} for field in fields_nodes: field_name = field.get("name") if field_name: options_map = {} if field.get("options"): options_map = { opt["name"]: opt["id"] for opt in field["options"] } iterations_map = {} if field.get( "__typename" ) == "ProjectV2IterationField" and field.get( "configuration", {} ).get( "iterations" ): iterations = field.get("configuration", {}).get( "iterations", [] ) iterations_map = { iter["title"]: iter["id"] for iter in iterations } field_details_map[field_name] = { "id": field.get("id"), "type": field.get("__typename"), "options": options_map, # Map Name -> ID "iterations": iterations_map, } return field_details_map except GitHubClientError as e: logger.error( f"Failed to get fields details for project {owner}/{project_number}: {e}" ) raise except Exception as e: # Catch potential errors during processing logger.error( f"Unexpected error processing fields for project {owner}/{project_number}: {e}" ) raise GitHubClientError( f"Could not process fields for project {owner}/{project_number}" )
• src/github_projects_mcp/server.py:71-71 (registration)

  The @mcp.tool() decorator registers the get_project_fields function as an MCP tool in the FastMCP server.
  @mcp.tool()
• src/github_projects_mcp/server.py:73-81 (schema)

  Docstring providing input parameters (owner: str, project_number: int) and output description, used by FastMCP for tool schema inference.
  """Get fields available in a GitHub Project V2, including options for SingleSelect fields. Args: owner: The GitHub organization or user name project_number: The project number Returns: A formatted string with field details. """