mcp-github-crunchtools 1.0.1__py3-none-any.whl

mcp_github_crunchtools/models.py

@@ -0,0 +1,215 @@
+"""Pydantic models and validation helpers for input validation.
+
+All tool inputs are validated through these helpers to prevent injection
+attacks and ensure data integrity before making API calls.
+"""
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .config import get_config
+
+SAFE_NAME_PATTERN = re.compile(r"^[A-Za-z0-9._-]+$")
+SAFE_REF_PATTERN = re.compile(r"^[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$")
+
+ISSUE_STATES = frozenset({"open", "closed", "all"})
+PR_STATES = frozenset({"open", "closed", "all"})
+
+MAX_NAME_LENGTH = 100
+MAX_PATH_LENGTH = 1000
+MAX_COMMENT_LENGTH = 65536
+MAX_QUERY_LENGTH = 1000
+MAX_PER_PAGE = 100
+MAX_TITLE_LENGTH = 256
+MAX_BODY_LENGTH = 65536
+MAX_REF_LENGTH = 255
+MAX_WORKFLOW_INPUTS = 32
+
+
+def resolve_owner(owner: str | None) -> str:
+    """Resolve and validate a repository owner.
+
+    Falls back to GITHUB_DEFAULT_ORG when no owner is supplied.
+
+    Args:
+        owner: Owner login (user or organization), or None.
+
+    Returns:
+        A validated owner login.
+
+    Raises:
+        ValueError: If no owner is available or the value is invalid.
+    """
+    if owner is None or not owner.strip():
+        default = get_config().default_org
+        if not default:
+            raise ValueError(
+                "owner is required (or set GITHUB_DEFAULT_ORG)"
+            )
+        owner = default
+
+    return validate_name(owner, "owner")
+
+
+def validate_name(value: str, field: str) -> str:
+    """Validate an owner or repository name against a safe allowlist.
+
+    Args:
+        value: The value to validate.
+        field: Field name for error messages.
+
+    Returns:
+        The stripped, validated value.
+
+    Raises:
+        ValueError: If the value is empty or contains disallowed characters.
+    """
+    if not value or not value.strip():
+        raise ValueError(f"{field} must not be empty")
+
+    value = value.strip()
+
+    if len(value) > MAX_NAME_LENGTH:
+        raise ValueError(f"{field} is too long")
+
+    if not SAFE_NAME_PATTERN.match(value):
+        raise ValueError(
+            f"{field} must contain only letters, digits, dots, hyphens, "
+            "and underscores"
+        )
+
+    return value
+
+
+def validate_positive_int(value: int, field: str) -> int:
+    """Validate that a value is a positive integer.
+
+    Args:
+        value: The value to validate.
+        field: Field name for error messages.
+
+    Returns:
+        The validated integer.
+
+    Raises:
+        ValueError: If the value is not a positive integer.
+    """
+    if not isinstance(value, int) or value < 1:
+        raise ValueError(f"{field} must be a positive integer")
+    return value
+
+
+def clamp_per_page(per_page: int) -> int:
+    """Clamp per_page to GitHub's allowed range (1-100)."""
+    return max(1, min(per_page, MAX_PER_PAGE))
+
+
+def validate_ref(value: str, field: str = "ref") -> str:
+    """Validate a git ref (branch or tag name).
+
+    Unlike names, refs may contain slashes between non-empty segments (e.g.
+    "release/1.2"), but must reject whitespace, control characters, ".."
+    traversal, empty "//" segments, and leading/trailing "." or "/" — in
+    line with git's check-ref-format rules, so invalid refs are caught here
+    rather than as a GitHub 422.
+
+    Args:
+        value: The ref to validate.
+        field: Field name for error messages.
+
+    Returns:
+        The stripped, validated ref.
+
+    Raises:
+        ValueError: If the ref is empty, too long, malformed, or contains
+            disallowed characters.
+    """
+    if not value or not value.strip():
+        raise ValueError(f"{field} must not be empty")
+
+    value = value.strip()
+
+    if len(value) > MAX_REF_LENGTH:
+        raise ValueError(f"{field} is too long")
+
+    if (
+        ".." in value
+        or "//" in value
+        or "./" in value
+        or value.startswith((".", "/"))
+        or value.endswith((".", "/"))
+    ):
+        raise ValueError(f"{field} is not a valid git ref")
+
+    if not SAFE_REF_PATTERN.match(value):
+        raise ValueError(
+            f"{field} must contain only letters, digits, dots, hyphens, "
+            "underscores, and slashes"
+        )
+
+    return value
+
+
+def validate_workflow_inputs(inputs: dict[str, object]) -> dict[str, object]:
+    """Validate workflow_dispatch inputs before sending them to GitHub.
+
+    Args:
+        inputs: Mapping of input name to a primitive value.
+
+    Returns:
+        The validated inputs mapping.
+
+    Raises:
+        ValueError: If there are too many inputs, a key is not a safe name,
+            or a value is not a string, number, or boolean.
+    """
+    is_mapping = isinstance(inputs, dict)
+    if not is_mapping:
+        raise ValueError("inputs must be an object of name/value pairs")
+
+    if len(inputs) > MAX_WORKFLOW_INPUTS:
+        raise ValueError(
+            f"inputs may not exceed {MAX_WORKFLOW_INPUTS} entries"
+        )
+
+    for key, value in inputs.items():
+        validate_name(key, "inputs key")
+        is_primitive = isinstance(value, (str, int, float, bool))
+        if not is_primitive:
+            raise ValueError(
+                f"inputs value for '{key}' must be a string, number, or boolean"
+            )
+
+    return inputs
+
+
+class CreateIssueCommentInput(BaseModel):
+    """Validated input for creating an issue comment."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    body: str = Field(
+        ...,
+        min_length=1,
+        max_length=MAX_COMMENT_LENGTH,
+        description="Comment body (Markdown)",
+    )
+
+
+class CreateIssueInput(BaseModel):
+    """Validated input for creating an issue."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    title: str = Field(
+        ...,
+        min_length=1,
+        max_length=MAX_TITLE_LENGTH,
+        description="Issue title",
+    )
+    body: str = Field(
+        default="",
+        max_length=MAX_BODY_LENGTH,
+        description="Issue body (Markdown)",
+    )

mcp_github_crunchtools/server.py

@@ -0,0 +1,496 @@
+"""FastMCP server setup for GitHub MCP.
+
+This module creates and configures the MCP server with all tools.
+"""
+
+import logging
+from typing import Any
+
+from fastmcp import FastMCP
+
+from .tools import (
+    create_issue,
+    create_issue_comment,
+    get_file_content,
+    get_issue,
+    get_pull_request,
+    get_pull_request_checks,
+    get_pull_request_diff,
+    list_issues,
+    list_pull_requests,
+    list_repo_tree,
+    list_workflow_runs,
+    rerun_failed_jobs,
+    rerun_workflow_run,
+    search_code,
+    search_issues,
+    trigger_workflow,
+    update_issue,
+    update_pull_request,
+)
+
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP(
+    name="mcp-github",
+    version="1.0.1",
+    instructions=(
+        "Secure MCP server for GitHub repositories: issues, pull requests "
+        "(diffs and CI checks), repository files, and code/issue search. "
+        "Works with github.com and GitHub Enterprise Server."
+    ),
+)
+
+
+@mcp.tool()
+async def list_issues_tool(
+    repo: str,
+    owner: str | None = None,
+    state: str = "open",
+    labels: str | None = None,
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """List issues for a GitHub repository (pull requests excluded).
+
+    Args:
+        repo: Repository name
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        state: Filter by state (open, closed, all)
+        labels: Comma-separated label names
+        per_page: Results per page, max 100 (default: 30)
+        page: Page number (default: 1)
+
+    Returns:
+        List of issues with pagination info
+    """
+    return await list_issues(
+        owner=owner,
+        repo=repo,
+        state=state,
+        labels=labels,
+        per_page=per_page,
+        page=page,
+    )
+
+
+@mcp.tool()
+async def get_issue_tool(
+    repo: str,
+    issue_number: int,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Get a single GitHub issue by number.
+
+    Args:
+        repo: Repository name
+        issue_number: Issue number (e.g., #42)
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        Issue details
+    """
+    return await get_issue(owner=owner, repo=repo, issue_number=issue_number)
+
+
+@mcp.tool()
+async def create_issue_tool(
+    repo: str,
+    title: str,
+    body: str = "",
+    labels: list[str] | None = None,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Create a new issue in a GitHub repository.
+
+    Args:
+        repo: Repository name
+        title: Issue title (required, non-empty)
+        body: Issue body (Markdown)
+        labels: Optional list of label names to apply
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        Created issue details (number, html_url, title)
+    """
+    return await create_issue(owner=owner, repo=repo, title=title, body=body, labels=labels)
+
+
+@mcp.tool()
+async def create_issue_comment_tool(
+    repo: str,
+    issue_number: int,
+    body: str,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Create a comment on a GitHub issue or pull request.
+
+    Args:
+        repo: Repository name
+        issue_number: Issue or pull request number
+        body: Comment body (Markdown)
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        Created comment details
+    """
+    return await create_issue_comment(owner=owner, repo=repo, issue_number=issue_number, body=body)
+
+
+@mcp.tool()
+async def update_issue_tool(
+    repo: str,
+    issue_number: int,
+    state: str | None = None,
+    state_reason: str | None = None,
+    title: str | None = None,
+    body: str | None = None,
+    labels: list[str] | None = None,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Update a GitHub issue, including closing or reopening it.
+
+    Set state="closed" to close an issue. Set state="open" with
+    state_reason="reopened" to reopen.
+
+    Args:
+        repo: Repository name
+        issue_number: Issue number
+        state: "open" or "closed"
+        state_reason: "completed", "not_planned", or "reopened"
+        title: New title (optional)
+        body: New body (optional)
+        labels: Replacement list of label names (optional)
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        Updated issue details (number, state, html_url, title)
+    """
+    return await update_issue(
+        owner=owner,
+        repo=repo,
+        issue_number=issue_number,
+        state=state,
+        state_reason=state_reason,
+        title=title,
+        body=body,
+        labels=labels,
+    )
+
+
+@mcp.tool()
+async def list_pull_requests_tool(
+    repo: str,
+    owner: str | None = None,
+    state: str = "open",
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """List pull requests for a GitHub repository.
+
+    Args:
+        repo: Repository name
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        state: Filter by state (open, closed, all)
+        per_page: Results per page, max 100 (default: 30)
+        page: Page number (default: 1)
+
+    Returns:
+        List of pull requests with pagination info
+    """
+    return await list_pull_requests(
+        owner=owner,
+        repo=repo,
+        state=state,
+        per_page=per_page,
+        page=page,
+    )
+
+
+@mcp.tool()
+async def get_pull_request_tool(
+    repo: str,
+    pull_number: int,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Get a single GitHub pull request by number.
+
+    Args:
+        repo: Repository name
+        pull_number: Pull request number
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        Pull request details including head/base refs and merge status
+    """
+    return await get_pull_request(owner=owner, repo=repo, pull_number=pull_number)
+
+
+@mcp.tool()
+async def get_pull_request_diff_tool(
+    repo: str,
+    pull_number: int,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Get the unified diff for a GitHub pull request.
+
+    Args:
+        repo: Repository name
+        pull_number: Pull request number
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        Dictionary with the diff text under the "content" key
+    """
+    return await get_pull_request_diff(owner=owner, repo=repo, pull_number=pull_number)
+
+
+@mcp.tool()
+async def get_pull_request_checks_tool(
+    repo: str,
+    pull_number: int,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Get a CI verdict for a PR that distinguishes skipped from failed.
+
+    Classifies every check-run and commit-status context into passed,
+    failing, pending, or skipped. SKIPPED checks are NOT failures. Use the
+    returned ``ready_to_merge`` boolean as the signal for whether the PR is
+    clear to merge (True only when nothing is failing or pending and the PR
+    is not known-unmergeable).
+
+    Args:
+        repo: Repository name
+        pull_number: Pull request number
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        A verdict with head SHA, mergeability, ready_to_merge, a summary
+        count, and per-bucket check lists
+    """
+    return await get_pull_request_checks(owner=owner, repo=repo, pull_number=pull_number)
+
+
+@mcp.tool()
+async def update_pull_request_tool(
+    repo: str,
+    pull_number: int,
+    state: str | None = None,
+    title: str | None = None,
+    body: str | None = None,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Update a GitHub pull request, including closing or reopening it.
+
+    This does NOT merge. Set state="closed" to close a PR without merging.
+
+    Args:
+        repo: Repository name
+        pull_number: Pull request number
+        state: "open" or "closed"
+        title: New title (optional)
+        body: New body (optional)
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        Updated PR details (number, state, html_url, title)
+    """
+    return await update_pull_request(
+        owner=owner,
+        repo=repo,
+        pull_number=pull_number,
+        state=state,
+        title=title,
+        body=body,
+    )
+
+
+@mcp.tool()
+async def get_file_content_tool(
+    repo: str,
+    path: str,
+    owner: str | None = None,
+    ref: str | None = None,
+) -> dict[str, Any]:
+    """Get the decoded text content of a file in a GitHub repository.
+
+    Args:
+        repo: Repository name
+        path: Path to the file within the repository
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        ref: Branch, tag, or commit SHA (default: the default branch)
+
+    Returns:
+        File metadata plus decoded text (or a notice if binary/too large)
+    """
+    return await get_file_content(owner=owner, repo=repo, path=path, ref=ref)
+
+
+@mcp.tool()
+async def list_repo_tree_tool(
+    repo: str,
+    owner: str | None = None,
+    tree_sha: str = "HEAD",
+    recursive: bool = False,
+) -> dict[str, Any]:
+    """List the git tree (files and directories) of a GitHub repository.
+
+    Args:
+        repo: Repository name
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        tree_sha: Tree SHA, branch name, or "HEAD" (default: HEAD)
+        recursive: Recurse into subtrees (default: false)
+
+    Returns:
+        Tree listing with entries and a truncation flag
+    """
+    return await list_repo_tree(owner=owner, repo=repo, tree_sha=tree_sha, recursive=recursive)
+
+
+@mcp.tool()
+async def search_code_tool(
+    query: str,
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """Search for code across GitHub.
+
+    Uses GitHub code search syntax (e.g., "addClass repo:jquery/jquery").
+
+    Args:
+        query: Search query string
+        per_page: Results per page, max 100 (default: 30)
+        page: Page number (default: 1)
+
+    Returns:
+        Search results with total count and matched code items
+    """
+    return await search_code(query=query, per_page=per_page, page=page)
+
+
+@mcp.tool()
+async def search_issues_tool(
+    query: str,
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """Search for issues and pull requests across GitHub.
+
+    Uses GitHub issue search syntax (e.g., "is:open is:pr author:octocat").
+
+    Args:
+        query: Search query string
+        per_page: Results per page, max 100 (default: 30)
+        page: Page number (default: 1)
+
+    Returns:
+        Search results with total count and matched issues/PRs
+    """
+    return await search_issues(query=query, per_page=per_page, page=page)
+
+
+@mcp.tool()
+async def list_workflow_runs_tool(
+    repo: str,
+    owner: str | None = None,
+    branch: str | None = None,
+    status: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> dict[str, Any]:
+    """List GitHub Actions workflow runs for a repository.
+
+    Args:
+        repo: Repository name
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        branch: Filter by head branch name
+        status: Filter by status or conclusion (e.g., "completed",
+            "in_progress", "queued", "failure", "success")
+        per_page: Results per page, max 100 (default: 20)
+        page: Page number (default: 1)
+
+    Returns:
+        Trimmed list of workflow runs with total count
+    """
+    return await list_workflow_runs(
+        owner=owner,
+        repo=repo,
+        branch=branch,
+        status=status,
+        per_page=per_page,
+        page=page,
+    )
+
+
+@mcp.tool()
+async def trigger_workflow_tool(
+    repo: str,
+    workflow_id: str,
+    ref: str | None = None,
+    inputs: dict[str, Any] | None = None,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Trigger a fresh GitHub Actions run via the workflow_dispatch event.
+
+    Use this to force a new build. Unlike rerun_workflow_run_tool (which
+    re-runs an existing run and is rejected by GitHub for runs older than 30
+    days), this starts a brand-new run regardless of when the workflow last
+    ran. The target workflow must declare an ``on: workflow_dispatch`` trigger.
+
+    Args:
+        repo: Repository name
+        workflow_id: Workflow file name (e.g. "build.yml") or its numeric ID
+        ref: Git ref (branch or tag) to run on (default: the repo's
+            default branch)
+        inputs: Optional workflow_dispatch inputs as name/value pairs
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        A confirmation dict:
+        {"status": "dispatch_requested", "workflow": ..., "ref": ...}
+    """
+    return await trigger_workflow(
+        owner=owner,
+        repo=repo,
+        workflow_id=workflow_id,
+        ref=ref,
+        inputs=inputs,
+    )
+
+
+@mcp.tool()
+async def rerun_workflow_run_tool(
+    repo: str,
+    run_id: int,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Re-run all jobs in a GitHub Actions workflow run.
+
+    Args:
+        repo: Repository name
+        run_id: Workflow run ID
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        A confirmation dict: {"status": "rerun_requested", "run_id": run_id}
+    """
+    return await rerun_workflow_run(owner=owner, repo=repo, run_id=run_id)
+
+
+@mcp.tool()
+async def rerun_failed_jobs_tool(
+    repo: str,
+    run_id: int,
+    owner: str | None = None,
+) -> dict[str, Any]:
+    """Re-run only the failed jobs in a GitHub Actions workflow run.
+
+    Args:
+        repo: Repository name
+        run_id: Workflow run ID
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+
+    Returns:
+        A confirmation dict: {"status": "rerun_requested", "run_id": run_id}
+    """
+    return await rerun_failed_jobs(owner=owner, repo=repo, run_id=run_id)