MCP Git Server

Instructions

Implementation Reference

• src/mcp_server_git/github/api.py:430-520 (handler)

  The main handler function that executes the tool: calls GitHub API to list PRs with filtering/pagination, handles errors, formats output with emojis and details.

  async def github_list_pull_requests(
      repo_owner: str,
      repo_name: str,
      state: str = "open",
      head: str | None = None,
      base: str | None = None,
      sort: str = "created",
      direction: str = "desc",
      per_page: int = 30,
      page: int = 1,
  ) -> str:
      """List pull requests for a repository"""
      logger.debug(f"🔍 Starting github_list_pull_requests for {repo_owner}/{repo_name}")
  
      try:
          async with github_client_context() as client:
              logger.debug("✅ GitHub client obtained successfully")
              logger.debug(
                  f"🔗 Token prefix: {client.token[:8]}..."
                  if client.token
                  else "No token"
              )
  
              params = {
                  "state": state,
                  "sort": sort,
                  "direction": direction,
                  "per_page": per_page,
                  "page": page,
              }
  
              if head:
                  params["head"] = head
              if base:
                  params["base"] = base
  
              logger.debug(
                  f"📡 Making API call to /repos/{repo_owner}/{repo_name}/pulls with params: {params}"
              )
  
              response = await client.get(
                  f"/repos/{repo_owner}/{repo_name}/pulls", params=params
              )
  
              logger.debug(f"📨 GitHub API response status: {response.status}")
  
              if response.status == 401:
                  response_text = await response.text()
                  logger.error(
                      f"🔒 GitHub API authentication failed (401): {response_text}"
                  )
                  return f"❌ GitHub API error 401: {response_text}"
              elif response.status != 200:
                  response_text = await response.text()
                  logger.error(f"❌ GitHub API error {response.status}: {response_text}")
                  return f"❌ Failed to list pull requests: {response.status} - {response_text}"
  
              prs = await response.json()
  
              if not prs:
                  return f"No {state} pull requests found"
  
              output = [f"{state.title()} Pull Requests for {repo_owner}/{repo_name}:\n"]
  
              for pr in prs:
                  state_emoji = {"open": "🟢", "closed": "🔴", "merged": "🟣"}.get(
                      pr.get("state"), "❓"
                  )
                  output.append(f"{state_emoji} #{pr['number']}: {pr['title']}")
                  output.append(f"   Author: {pr.get('user', {}).get('login', 'N/A')}")
                  base_ref = pr.get("base", {}).get("ref", "N/A")
                  head_ref = pr.get("head", {}).get("ref", "N/A")
                  output.append(f"   Base: {base_ref} ← Head: {head_ref}")
                  output.append(f"   Created: {pr.get('created_at', 'N/A')}")
                  output.append("")
  
              return "\n".join(output)
  
      except ValueError as auth_error:
          logger.error(f"Authentication error listing pull requests: {auth_error}")
          return f"❌ {str(auth_error)}"
      except ConnectionError as conn_error:
          logger.error(f"Connection error listing pull requests: {conn_error}")
          return f"❌ Network connection failed: {str(conn_error)}"
      except Exception as e:
          logger.error(
              f"Unexpected error listing pull requests for {repo_owner}/{repo_name}: {e}",
              exc_info=True,
          )
          return f"❌ Error listing pull requests: {str(e)}"

• src/mcp_server_git/github/models.py:54-64 (schema)

  Pydantic input schema/model defining parameters for the github_list_pull_requests tool.

  class GitHubListPullRequests(BaseModel):
      repo_owner: str
      repo_name: str
      state: str = "open"
      head: str | None = None
      base: str | None = None
      sort: str = "created"
      direction: str = "desc"
      per_page: int = 30
      page: int = 1

• src/mcp_server_git/core/tools.py:383-391 (registration)

  Tool registration in the central ToolRegistry, defining name, description, schema, and metadata. Actual handler set later via router.

  ToolDefinition(
      name=GitTools.GITHUB_LIST_PULL_REQUESTS,
      category=ToolCategory.GITHUB,
      description="List pull requests for a repository",
      schema=GitHubListPullRequests,
      handler=placeholder_handler,
      requires_repo=False,
      requires_github_token=True,
  ),