github-mcp 1.1.0__py3-none-any.whl

github_mcp/tools/pulls.py

@@ -0,0 +1,429 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from github_mcp.app import mcp
+from mcp.types import ToolAnnotations
+from github_mcp.client import github_request, handle_github_error
+from github_mcp.formatting import ResponseFormat, fmt_json, fmt_timestamp
+
+# MARK: Input models
+
+
+class ListPullRequestsInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: str = Field(..., description="Repository owner.", min_length=1)
+    repo: str = Field(..., description="Repository name.", min_length=1)
+    state: Optional[str] = Field(
+        default="open",
+        description="PR state: 'open' (default), 'closed', or 'all'.",
+    )
+    base: Optional[str] = Field(
+        default=None,
+        description="Filter by base branch name (e.g. 'main').",
+    )
+    head: Optional[str] = Field(
+        default=None,
+        description="Filter by head branch (format: 'user:branch' or just 'branch').",
+    )
+    sort: Optional[str] = Field(
+        default="updated",
+        description="Sort by: 'created', 'updated' (default), 'popularity', 'long-running'.",
+    )
+    limit: int = Field(
+        default=20, ge=1, le=100, description="Max PRs to return (1–100, default 20)."
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class GetPullRequestInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: str = Field(..., description="Repository owner.", min_length=1)
+    repo: str = Field(..., description="Repository name.", min_length=1)
+    pull_number: int = Field(..., description="Pull request number.", ge=1)
+    include_diff: bool = Field(
+        default=False,
+        description=(
+            "If true, append the unified diff of the PR's changes. "
+            "May be large for PRs with many file changes."
+        ),
+    )
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class CreatePullRequestInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: str = Field(..., description="Repository owner.", min_length=1)
+    repo: str = Field(..., description="Repository name.", min_length=1)
+    title: str = Field(..., description="PR title.", min_length=1, max_length=256)
+    head: str = Field(
+        ...,
+        description="Branch containing changes (format: 'branch' or 'owner:branch').",
+        min_length=1,
+    )
+    base: str = Field(
+        ..., description="Branch to merge into (e.g. 'main').", min_length=1
+    )
+    body: Optional[str] = Field(
+        default=None, description="PR description (Markdown supported)."
+    )
+    draft: bool = Field(default=False, description="Open as a draft PR.")
+    maintainer_can_modify: bool = Field(
+        default=True,
+        description="Allow maintainers to push to the head branch.",
+    )
+
+
+class MergePullRequestInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: str = Field(..., description="Repository owner.", min_length=1)
+    repo: str = Field(..., description="Repository name.", min_length=1)
+    pull_number: int = Field(..., description="PR number to merge.", ge=1)
+    commit_title: Optional[str] = Field(
+        default=None,
+        description="Title for the merge commit (defaults to PR title).",
+    )
+    commit_message: Optional[str] = Field(
+        default=None,
+        description="Extra detail for the merge commit message.",
+    )
+    merge_method: Optional[str] = Field(
+        default="merge",
+        description="Merge strategy: 'merge' (default), 'squash', or 'rebase'.",
+    )
+
+
+class AddPRCommentInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: str = Field(..., description="Repository owner.", min_length=1)
+    repo: str = Field(..., description="Repository name.", min_length=1)
+    pull_number: int = Field(..., description="Pull request number.", ge=1)
+    body: str = Field(
+        ..., description="Comment text (Markdown supported).", min_length=1
+    )
+
+
+# MARK: Tools
+
+
+@mcp.tool(
+    name="github_list_pull_requests",
+    annotations=ToolAnnotations(
+        title="List Pull Requests",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_list_pull_requests(params: ListPullRequestsInput) -> str:
+    """List pull requests in a GitHub repository.
+
+    Args:
+        params (ListPullRequestsInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - state (Optional[str]): 'open', 'closed', or 'all'.
+            - base (Optional[str]): Filter by base branch.
+            - head (Optional[str]): Filter by head branch.
+            - sort (Optional[str]): Sort key.
+            - limit (int): Max PRs (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted PR list. Markdown shows number, title, author, head/base
+            branches, draft status, and URL. JSON is the raw API array.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        query: dict = {
+            "state": params.state,
+            "sort": params.sort,
+            "per_page": params.limit,
+            "page": params.page,
+        }
+        if params.base:
+            query["base"] = params.base
+        if params.head:
+            query["head"] = params.head
+
+        resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/pulls",
+            params=query,
+        )
+        prs = resp.json()
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(prs)
+
+        lines = [f"## Pull Requests: {params.owner}/{params.repo} ({params.state})", ""]
+        if not prs:
+            lines.append("*No pull requests found.*")
+        else:
+            for pr in prs:
+                num = pr.get("number", "?")
+                title = pr.get("title", "")
+                url = pr.get("html_url", "")
+                author = pr.get("user", {}).get("login", "unknown")
+                head_label = pr.get("head", {}).get("label", "?")
+                base_label = pr.get("base", {}).get("label", "?")
+                draft = " [DRAFT]" if pr.get("draft") else ""
+                updated = fmt_timestamp(pr.get("updated_at"))
+                lines.append(f"- **#{num}**{draft} [{title}]({url})")
+                lines.append(f"  - Author: {author} | {head_label} → {base_label}")
+                lines.append(f"  - Updated: {updated}")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_get_pull_request",
+    annotations=ToolAnnotations(
+        title="Get Pull Request Details",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_get_pull_request(params: GetPullRequestInput) -> str:
+    """Get full details for a single pull request, optionally including the unified diff.
+
+    Args:
+        params (GetPullRequestInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - pull_number (int): PR number.
+            - include_diff (bool): If true, append the unified diff.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Full PR details. Markdown shows title, state, author, branches,
+            labels, reviewers, checks status, body, and optionally the diff.
+            JSON is the raw API object (diff excluded in JSON mode).
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/pulls/{params.pull_number}",
+        )
+        pr = resp.json()
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(pr)
+
+        author = pr.get("user", {}).get("login", "unknown")
+        head_label = pr.get("head", {}).get("label", "?")
+        base_label = pr.get("base", {}).get("label", "?")
+        labels = ", ".join(lbl["name"] for lbl in pr.get("labels", []))
+        reviewers = ", ".join(r["login"] for r in pr.get("requested_reviewers", []))
+        draft = " (DRAFT)" if pr.get("draft") else ""
+        merged = pr.get("merged", False)
+        state_str = "merged" if merged else pr.get("state", "")
+
+        lines = [
+            f"## PR #{pr.get('number')}: {pr.get('title')}{draft}",
+            "",
+            f"- **State**: {state_str}",
+            f"- **Author**: {author}",
+            f"- **Branch**: {head_label} → {base_label}",
+            f"- **Labels**: {labels or 'None'}",
+            f"- **Reviewers**: {reviewers or 'None'}",
+            f"- **Commits**: {pr.get('commits', 0)}",
+            f"- **Changed files**: {pr.get('changed_files', 0)}",
+            f"- **Additions**: +{pr.get('additions', 0)} / Deletions: -{pr.get('deletions', 0)}",
+            f"- **Mergeable**: {pr.get('mergeable', 'unknown')}",
+            f"- **Created**: {fmt_timestamp(pr.get('created_at'))}",
+            f"- **Updated**: {fmt_timestamp(pr.get('updated_at'))}",
+        ]
+        if merged:
+            lines.append(f"- **Merged**: {fmt_timestamp(pr.get('merged_at'))}")
+        lines += [
+            f"- **URL**: {pr.get('html_url', '')}",
+            "",
+            "### Description",
+            "",
+            pr.get("body") or "*No description provided.*",
+        ]
+
+        if params.include_diff:
+            try:
+                diff_resp = await github_request(
+                    "GET",
+                    f"/repos/{params.owner}/{params.repo}/pulls/{params.pull_number}",
+                    accept="application/vnd.github.diff",
+                )
+                lines += ["", "### Unified Diff", "", "```diff", diff_resp.text, "```"]
+            except Exception as diff_err:
+                lines += ["", f"*(Could not fetch diff: {diff_err})*"]
+
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_create_pull_request",
+    annotations=ToolAnnotations(
+        title="Create a Pull Request",
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_create_pull_request(params: CreatePullRequestInput) -> str:
+    """Create a new pull request in a GitHub repository.
+
+    Args:
+        params (CreatePullRequestInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - title (str): PR title.
+            - head (str): Source branch with changes.
+            - base (str): Target branch to merge into.
+            - body (Optional[str]): PR description.
+            - draft (bool): Open as draft (default False).
+            - maintainer_can_modify (bool): Allow maintainer pushes (default True).
+
+    Returns:
+        str: Confirmation with PR number and URL.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        body: dict = {
+            "title": params.title,
+            "head": params.head,
+            "base": params.base,
+            "draft": params.draft,
+            "maintainer_can_modify": params.maintainer_can_modify,
+        }
+        if params.body:
+            body["body"] = params.body
+
+        resp = await github_request(
+            "POST",
+            f"/repos/{params.owner}/{params.repo}/pulls",
+            json=body,
+        )
+        pr = resp.json()
+        draft_str = " (draft)" if pr.get("draft") else ""
+        return (
+            f"Created PR #{pr['number']}{draft_str}: {pr['title']}\n"
+            f"URL: {pr.get('html_url', '')}"
+        )
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_merge_pull_request",
+    annotations=ToolAnnotations(
+        title="Merge a Pull Request",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_merge_pull_request(params: MergePullRequestInput) -> str:
+    """Merge an open, mergeable pull request.
+
+    Args:
+        params (MergePullRequestInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - pull_number (int): PR number.
+            - commit_title (Optional[str]): Override merge commit title.
+            - commit_message (Optional[str]): Additional commit message detail.
+            - merge_method (Optional[str]): 'merge', 'squash', or 'rebase'.
+
+    Returns:
+        str: Confirmation with merge commit SHA or a descriptive error.
+
+        Error response: "Error <code>: <message>" string.
+        "Error 405: PR not mergeable" if the PR has conflicts or is already merged.
+    """
+    try:
+        body: dict = {"merge_method": params.merge_method or "merge"}
+        if params.commit_title:
+            body["commit_title"] = params.commit_title
+        if params.commit_message:
+            body["commit_message"] = params.commit_message
+
+        resp = await github_request(
+            "PUT",
+            f"/repos/{params.owner}/{params.repo}/pulls/{params.pull_number}/merge",
+            json=body,
+        )
+        data = resp.json()
+        sha = data.get("sha", "")[:7]
+        return (
+            f"PR #{params.pull_number} merged successfully "
+            f"(method: {params.merge_method}, commit: {sha}).\n"
+            f"{data.get('message', '')}"
+        )
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_add_pr_comment",
+    annotations=ToolAnnotations(
+        title="Add a Comment to a Pull Request",
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_add_pr_comment(params: AddPRCommentInput) -> str:
+    """Add a general comment to a pull request (as an issue comment, visible in the Conversation tab).
+
+    For inline code review comments on specific lines, use the GitHub Reviews API directly.
+
+    Args:
+        params (AddPRCommentInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - pull_number (int): PR number.
+            - body (str): Comment text (Markdown supported).
+
+    Returns:
+        str: Confirmation with comment ID and URL.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        resp = await github_request(
+            "POST",
+            # PRs share the issues comment endpoint for conversation-level comments
+            f"/repos/{params.owner}/{params.repo}/issues/{params.pull_number}/comments",
+            json={"body": params.body},
+        )
+        comment = resp.json()
+        return (
+            f"Comment added to PR #{params.pull_number} (comment ID: {comment['id']}).\n"
+            f"URL: {comment.get('html_url', '')}"
+        )
+    except Exception as e:
+        return handle_github_error(e)