github_list_pull_requests

Retrieve and filter pull requests from a GitHub repository with options to sort, paginate, and filter by state, head, and base branch using the MCP Git Server.

Instructions

List pull requests for a repository with filtering and pagination

Input Schema

TableJSON Schema

Name	Required	Default
`base`	No
`direction`	No	desc
`head`	No
`page`	No
`per_page`	No
`repo_name`	Yes
`repo_owner`	Yes
`sort`	No	created
`state`	No	open

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,
),

MCP Git Server