github-mcp 1.1.0__py3-none-any.whl

github_mcp/tools/issues.py

@@ -0,0 +1,375 @@
+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 ListIssuesInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: str = Field(..., description="Repository owner (username or org).", min_length=1)
+    repo: str = Field(..., description="Repository name.", min_length=1)
+    state: Optional[str] = Field(
+        default="open",
+        description="Issue state filter: 'open' (default), 'closed', or 'all'.",
+    )
+    labels: Optional[str] = Field(
+        default=None,
+        description="Comma-separated list of label names to filter by (e.g. 'bug,help wanted').",
+    )
+    assignee: Optional[str] = Field(
+        default=None,
+        description="Filter by assignee username. Use 'none' for unassigned, '*' for any.",
+    )
+    limit: int = Field(default=20, ge=1, le=100, description="Maximum issues to return (1–100, default 20).")
+    page: int = Field(default=1, ge=1, description="Page number for pagination (default 1).")
+    response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN, description="Output format.")
+
+
+class GetIssueInput(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)
+    issue_number: int = Field(..., description="Issue number.", ge=1)
+    response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN, description="Output format.")
+
+
+class CreateIssueInput(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="Issue title.", min_length=1, max_length=256)
+    body: Optional[str] = Field(default=None, description="Issue body (Markdown supported).")
+    labels: Optional[list[str]] = Field(default=None, description="List of label names to apply.")
+    assignees: Optional[list[str]] = Field(default=None, description="List of GitHub usernames to assign.")
+    milestone: Optional[int] = Field(default=None, description="Milestone number to associate.", ge=1)
+
+
+class UpdateIssueInput(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)
+    issue_number: int = Field(..., description="Issue number to update.", ge=1)
+    title: Optional[str] = Field(default=None, description="New issue title.", max_length=256)
+    body: Optional[str] = Field(default=None, description="New issue body (replaces existing).")
+    state: Optional[str] = Field(
+        default=None,
+        description="Change issue state: 'open' to reopen, 'closed' to close.",
+    )
+    labels: Optional[list[str]] = Field(default=None, description="Replace all labels with this list.")
+    assignees: Optional[list[str]] = Field(default=None, description="Replace all assignees with this list.")
+    milestone: Optional[int] = Field(default=None, description="Set milestone number (0 to clear).", ge=0)
+
+
+class AddIssueCommentInput(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)
+    issue_number: int = Field(..., description="Issue number to comment on.", ge=1)
+    body: str = Field(..., description="Comment text (Markdown supported).", min_length=1)
+
+
+# MARK: Tools
+
+@mcp.tool(
+    name="github_list_issues",
+    annotations=ToolAnnotations(
+        title="List Repository Issues",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_list_issues(params: ListIssuesInput) -> str:
+    """List issues in a GitHub repository with optional filters.
+
+    Note: GitHub's issues endpoint also returns pull requests. This tool
+    filters to only return true issues (not PRs).
+
+    Args:
+        params (ListIssuesInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - state (Optional[str]): 'open', 'closed', or 'all'.
+            - labels (Optional[str]): Comma-separated label names.
+            - assignee (Optional[str]): Filter by assignee.
+            - limit (int): Max issues (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted issue list. Markdown shows number, title, state, labels,
+            assignees, and URL. JSON is the raw API array.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        query: dict = {"state": params.state, "per_page": params.limit, "page": params.page}
+        if params.labels:
+            query["labels"] = params.labels
+        if params.assignee:
+            query["assignee"] = params.assignee
+
+        resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/issues",
+            params=query,
+        )
+        all_items = resp.json()
+        # Filter out pull requests
+        issues = [i for i in all_items if "pull_request" not in i]
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(issues)
+
+        lines = [f"## Issues: {params.owner}/{params.repo} ({params.state})", ""]
+        if not issues:
+            lines.append("*No issues found.*")
+        else:
+            for issue in issues:
+                num = issue.get("number", "?")
+                title = issue.get("title", "")
+                url = issue.get("html_url", "")
+                state = issue.get("state", "")
+                labels = ", ".join(lbl["name"] for lbl in issue.get("labels", []))
+                assignees = ", ".join(a["login"] for a in issue.get("assignees", []))
+                created = fmt_timestamp(issue.get("created_at"))
+                label_str = f" [{labels}]" if labels else ""
+                line = f"- **#{num}** [{title}]({url}){label_str} — {state}"
+                lines.append(line)
+                if assignees:
+                    lines.append(f"  - Assignees: {assignees}")
+                lines.append(f"  - Created: {created}")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_get_issue",
+    annotations=ToolAnnotations(
+        title="Get GitHub Issue",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_get_issue(params: GetIssueInput) -> str:
+    """Get full details for a single GitHub issue including body and metadata.
+
+    Args:
+        params (GetIssueInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - issue_number (int): Issue number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Full issue details. Markdown shows title, number, state, author,
+            assignees, labels, milestone, dates, and body. JSON is the raw
+            API object.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/issues/{params.issue_number}",
+        )
+        issue = resp.json()
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(issue)
+
+        labels = ", ".join(lbl["name"] for lbl in issue.get("labels", []))
+        assignees = ", ".join(a["login"] for a in issue.get("assignees", []))
+        milestone = issue.get("milestone", {})
+        milestone_str = milestone.get("title", "None") if milestone else "None"
+        author = issue.get("user", {}).get("login", "unknown")
+        lines = [
+            f"## Issue #{issue.get('number')}: {issue.get('title')}",
+            "",
+            f"- **State**: {issue.get('state')}",
+            f"- **Author**: {author}",
+            f"- **Assignees**: {assignees or 'None'}",
+            f"- **Labels**: {labels or 'None'}",
+            f"- **Milestone**: {milestone_str}",
+            f"- **Comments**: {issue.get('comments', 0)}",
+            f"- **Created**: {fmt_timestamp(issue.get('created_at'))}",
+            f"- **Updated**: {fmt_timestamp(issue.get('updated_at'))}",
+            f"- **Closed**: {fmt_timestamp(issue.get('closed_at'))}",
+            f"- **URL**: {issue.get('html_url', '')}",
+            "",
+            "### Body",
+            "",
+            issue.get("body") or "*No description provided.*",
+        ]
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_create_issue",
+    annotations=ToolAnnotations(
+        title="Create a GitHub Issue",
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_create_issue(params: CreateIssueInput) -> str:
+    """Create a new issue in a GitHub repository.
+
+    Args:
+        params (CreateIssueInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - title (str): Issue title.
+            - body (Optional[str]): Issue body (Markdown).
+            - labels (Optional[list[str]]): Label names to apply.
+            - assignees (Optional[list[str]]): Usernames to assign.
+            - milestone (Optional[int]): Milestone number.
+
+    Returns:
+        str: Confirmation with issue number and URL.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        body: dict = {"title": params.title}
+        if params.body:
+            body["body"] = params.body
+        if params.labels:
+            body["labels"] = params.labels
+        if params.assignees:
+            body["assignees"] = params.assignees
+        if params.milestone:
+            body["milestone"] = params.milestone
+
+        resp = await github_request(
+            "POST",
+            f"/repos/{params.owner}/{params.repo}/issues",
+            json=body,
+        )
+        issue = resp.json()
+        return (
+            f"Created issue #{issue['number']}: {issue['title']}\n"
+            f"URL: {issue.get('html_url', '')}"
+        )
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_update_issue",
+    annotations=ToolAnnotations(
+        title="Update a GitHub Issue",
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_update_issue(params: UpdateIssueInput) -> str:
+    """Update an existing GitHub issue — edit title/body, change state, labels, or assignees.
+
+    Args:
+        params (UpdateIssueInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - issue_number (int): Issue number to update.
+            - title (Optional[str]): New title.
+            - body (Optional[str]): New body (replaces existing).
+            - state (Optional[str]): 'open' or 'closed'.
+            - labels (Optional[list[str]]): Replacement label list.
+            - assignees (Optional[list[str]]): Replacement assignees list.
+            - milestone (Optional[int]): Milestone number (0 to clear).
+
+    Returns:
+        str: Confirmation with updated issue number, state, and URL.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        body: dict = {}
+        if params.title is not None:
+            body["title"] = params.title
+        if params.body is not None:
+            body["body"] = params.body
+        if params.state is not None:
+            body["state"] = params.state
+        if params.labels is not None:
+            body["labels"] = params.labels
+        if params.assignees is not None:
+            body["assignees"] = params.assignees
+        if params.milestone is not None:
+            body["milestone"] = params.milestone if params.milestone > 0 else None
+
+        resp = await github_request(
+            "PATCH",
+            f"/repos/{params.owner}/{params.repo}/issues/{params.issue_number}",
+            json=body,
+        )
+        issue = resp.json()
+        return (
+            f"Updated issue #{issue['number']}: {issue['title']} — state: {issue['state']}\n"
+            f"URL: {issue.get('html_url', '')}"
+        )
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_add_issue_comment",
+    annotations=ToolAnnotations(
+        title="Add a Comment to a GitHub Issue",
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_add_issue_comment(params: AddIssueCommentInput) -> str:
+    """Add a comment to an existing GitHub issue.
+
+    Args:
+        params (AddIssueCommentInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - issue_number (int): Issue to comment on.
+            - 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",
+            f"/repos/{params.owner}/{params.repo}/issues/{params.issue_number}/comments",
+            json={"body": params.body},
+        )
+        comment = resp.json()
+        return (
+            f"Comment added to issue #{params.issue_number} (comment ID: {comment['id']}).\n"
+            f"URL: {comment.get('html_url', '')}"
+        )
+    except Exception as e:
+        return handle_github_error(e)