MCP Git Server

Instructions

Implementation Reference

• src/mcp_server_git/github/api.py:79-161 (handler)

  Main handler function that implements the github_get_pr_checks tool by fetching the PR head SHA, retrieving check runs from GitHub API, optionally filtering by status/conclusion, and formatting a readable output with emojis and details.

  async def github_get_pr_checks(
      repo_owner: str,
      repo_name: str,
      pr_number: int,
      status: str | None = None,
      conclusion: str | None = None,
  ) -> str:
      """Get check runs for a pull request"""
      try:
          async with github_client_context() as client:
              # First get the PR to get the head SHA
              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 for the head commit
              params = {}
              if status:
                  params["status"] = status
  
              checks_response = await client.get(
                  f"/repos/{repo_owner}/{repo_name}/commits/{head_sha}/check-runs",
                  params=params,
              )
              if checks_response.status != 200:
                  return f"❌ Failed to get check runs: {checks_response.status}"
  
              checks_data = await checks_response.json()
  
              # Filter by conclusion if specified
              check_runs = checks_data.get("check_runs", [])
              if conclusion:
                  check_runs = [
                      run for run in check_runs if run.get("conclusion") == conclusion
                  ]
  
              # Format the output
              if not check_runs:
                  return f"No check runs found for PR #{pr_number}"
  
              output = [f"Check runs for PR #{pr_number} (commit {head_sha[:8]}):\n"]
  
              for run in check_runs:
                  status_emoji = {
                      "completed": "✅" if run.get("conclusion") == "success" else "❌",
                      "in_progress": "🔄",
                      "queued": "⏳",
                  }.get(run["status"], "❓")
  
                  output.append(f"{status_emoji} {run['name']}")
                  output.append(f"   Status: {run['status']}")
                  if run.get("conclusion"):
                      output.append(f"   Conclusion: {run['conclusion']}")
                  output.append(f"   Started: {run.get('started_at', 'N/A')}")
                  if run.get("completed_at"):
                      output.append(f"   Completed: {run['completed_at']}")
                  if run.get("html_url"):
                      output.append(f"   URL: {run['html_url']}")
                  output.append("")
  
              return "\n".join(output)
  
      except ValueError as auth_error:
          # Handle authentication/configuration errors specifically
          logger.error(f"Authentication error getting PR checks: {auth_error}")
          return f"❌ {str(auth_error)}"
      except ConnectionError as conn_error:
          # Handle network connectivity issues
          logger.error(f"Connection error getting PR checks: {conn_error}")
          return f"❌ Network connection failed: {str(conn_error)}"
      except Exception as e:
          # Log unexpected errors with full context for debugging
          logger.error(
              f"Unexpected error getting PR checks for PR #{pr_number}: {e}",
              exc_info=True,
          )
          return f"❌ Error getting PR checks: {str(e)}"

• src/mcp_server_git/github/models.py:6-12 (schema)

  Pydantic model defining the input schema for the github_get_pr_checks tool, including required repo details, PR number, and optional filters for status and conclusion.

  class GitHubGetPRChecks(BaseModel):
      repo_owner: str
      repo_name: str
      pr_number: int
      status: str | None = None
      conclusion: str | None = None

• src/mcp_server_git/core/tools.py:338-346 (registration)

  ToolDefinition registration in the central tool registry, specifying name, category, description, schema, placeholder handler, and requirements (no repo needed, requires GitHub token).

  ToolDefinition(
      name=GitTools.GITHUB_GET_PR_CHECKS,
      category=ToolCategory.GITHUB,
      description="Get check runs for a pull request",
      schema=GitHubGetPRChecks,
      handler=placeholder_handler,
      requires_repo=False,
      requires_github_token=True,
  ),

• src/mcp_server_git/core/handlers.py:194-196 (registration)

  Handler wrapper creation and registration in the GitToolRouter, binding the actual github_get_pr_checks function from github.api with expected argument order and error handling decorators.

  "github_get_pr_checks": self._create_github_handler(
      github_get_pr_checks,
      ["repo_owner", "repo_name", "pr_number", "status", "conclusion"],