MCP Git Server

Instructions

Implementation Reference

• src/mcp_server_git/github/api.py:163-261 (handler)

  Core async function implementing the github_get_failing_jobs tool logic: fetches PR details, check-runs for the head commit, filters failing jobs, retrieves annotations and provides log links.

  async def github_get_failing_jobs(
      repo_owner: str,
      repo_name: str,
      pr_number: int,
      include_logs: bool = True,
      include_annotations: bool = True,
  ) -> str:
      """Get detailed information about failing jobs in a PR"""
      try:
          async with github_client_context() as client:
              # Get PR details
              pr_response = await client.get(
                  f"/repos/{repo_owner}/{repo_name}/pulls/{pr_number}"
              )
              if pr_response.status != 200:
                  return f"❌ Failed to get PR #{pr_number}: {pr_response.status}"
  
              pr_data = await pr_response.json()
              head_sha = pr_data["head"]["sha"]
  
              # Get check runs and filter for failures
              checks_response = await client.get(
                  f"/repos/{repo_owner}/{repo_name}/commits/{head_sha}/check-runs"
              )
              if checks_response.status != 200:
                  return f"❌ Failed to get check runs: {checks_response.status}"
  
              checks_data = await checks_response.json()
  
              failing_runs = [
                  run
                  for run in checks_data.get("check_runs", [])
                  if run["status"] == "completed"
                  and run.get("conclusion") in ["failure", "cancelled", "timed_out"]
              ]
  
              if not failing_runs:
                  return f"No failing jobs found for PR #{pr_number}"
  
              output = [f"Failing jobs for PR #{pr_number}:\n"]
  
              for run in failing_runs:
                  output.append(f"❌ {run['name']}")
                  output.append(f"   Conclusion: {run['conclusion']}")
                  output.append(f"   Started: {run.get('started_at', 'N/A')}")
                  output.append(f"   Completed: {run.get('completed_at', 'N/A')}")
  
                  # Get annotations if requested
                  if include_annotations and run.get("id"):
                      try:
                          annotations_response = await client.get(
                              f"/repos/{repo_owner}/{repo_name}/check-runs/{run['id']}/annotations"
                          )
                          if annotations_response.status == 200:
                              annotations_data = await annotations_response.json()
                              if annotations_data:
                                  output.append("   Annotations:")
                                  for annotation in annotations_data[
                                      :5
                                  ]:  # Limit to first 5
                                      output.append(
                                          f"     • {annotation.get('title', 'Error')}: {annotation.get('message', 'No message')}"
                                      )
                                      if annotation.get("path"):
                                          output.append(
                                              f"       File: {annotation['path']} (line {annotation.get('start_line', 'unknown')})"
                                          )
                      except (ConnectionError, ValueError) as annotation_error:
                          # Log specific annotation errors but continue processing
                          logger.warning(
                              f"Failed to get annotations for run {run.get('id')}: {annotation_error}"
                          )
                      except Exception as annotation_error:
                          # Annotations might not be available - log but continue
                          logger.debug(
                              f"Annotations unavailable for run {run.get('id')}: {annotation_error}"
                          )
  
                  # Get logs if requested (simplified)
                  if include_logs and run.get("html_url"):
                      output.append(f"   Details: {run['html_url']}")
  
                  output.append("")
  
              return "\n".join(output)
  
      except ValueError as auth_error:
          logger.error(f"Authentication error getting failing jobs: {auth_error}")
          return f"❌ {str(auth_error)}"
      except ConnectionError as conn_error:
          logger.error(f"Connection error getting failing jobs: {conn_error}")
          return f"❌ Network connection failed: {str(conn_error)}"
      except Exception as e:
          logger.error(
              f"Unexpected error getting failing jobs for PR #{pr_number}: {e}",
              exc_info=True,
          )
          return f"❌ Error getting failing jobs: {str(e)}"

• src/mcp_server_git/github/models.py:14-20 (schema)

  Pydantic input schema/model for the github_get_failing_jobs tool defining required repo_owner, repo_name, pr_number and optional flags for logs/annotations.

  class GitHubGetFailingJobs(BaseModel):
      repo_owner: str
      repo_name: str
      pr_number: int
      include_logs: bool = True
      include_annotations: bool = True

• src/mcp_server_git/core/tools.py:348-355 (registration)

  ToolDefinition registration in ToolRegistry for github_get_failing_jobs including name, category, description, schema, and flags.

      name=GitTools.GITHUB_GET_FAILING_JOBS,
      category=ToolCategory.GITHUB,
      description="Get detailed information about failing jobs in a PR",
      schema=GitHubGetFailingJobs,
      handler=placeholder_handler,
      requires_repo=False,
      requires_github_token=True,
  ),

• src/mcp_server_git/core/handlers.py:198-207 (registration)

  Handler registration in _get_github_handlers: creates GitHub handler wrapper around imported github_get_failing_jobs function with specific arg order.

  "github_get_failing_jobs": self._create_github_handler(
      github_get_failing_jobs,
      [
          "repo_owner",
          "repo_name",
          "pr_number",
          "include_logs",
          "include_annotations",
      ],
  ),

• src/mcp_server_git/core/tools.py:42-42 (helper)

  Enum constant definition for the tool name in GitTools.

  GITHUB_GET_FAILING_JOBS = "github_get_failing_jobs"