github-projects-mcp

Instructions

Args:
    owner: The GitHub organization or user name
    project_number: The project number

Returns:
    A formatted string with field details.

Implementation Reference

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

  The main MCP tool handler for 'get_project_fields', decorated with @mcp.tool() which also serves as registration. It calls the GitHub client helper and formats the output.

  @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 method in GitHubClient that performs the GraphQL query to fetch detailed project fields information, including options for single-select and iteration fields, and structures it into a dictionary.

  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.

  @mcp.tool()