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

mcp_github_crunchtools/tools/__init__.py

@@ -0,0 +1,48 @@
+"""GitHub MCP tools.
+
+This package contains all the MCP tool implementations for GitHub operations.
+"""
+
+from .actions import (
+    list_workflow_runs,
+    rerun_failed_jobs,
+    rerun_workflow_run,
+    trigger_workflow,
+)
+from .files import get_file_content, list_repo_tree
+from .issues import (
+    create_issue,
+    create_issue_comment,
+    get_issue,
+    list_issues,
+    update_issue,
+)
+from .pull_requests import (
+    get_pull_request,
+    get_pull_request_checks,
+    get_pull_request_diff,
+    list_pull_requests,
+    update_pull_request,
+)
+from .search import search_code, search_issues
+
+__all__ = [
+    "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",
+]

mcp_github_crunchtools/tools/actions.py

@@ -0,0 +1,187 @@
+"""GitHub Actions tools.
+
+Tools for listing workflow runs, triggering fresh runs, and re-running CI
+on GitHub Actions.
+"""
+
+from typing import Any
+
+from ..client import get_client
+from ..models import (
+    clamp_per_page,
+    resolve_owner,
+    validate_name,
+    validate_positive_int,
+    validate_ref,
+    validate_workflow_inputs,
+)
+
+
+async def list_workflow_runs(
+    owner: str | None,
+    repo: str,
+    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:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        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 pagination info
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+
+    params: dict[str, Any] = {
+        "per_page": clamp_per_page(per_page),
+        "page": validate_positive_int(page, "page"),
+    }
+    if branch:
+        params["branch"] = branch
+    if status:
+        params["status"] = status
+
+    client = get_client()
+    result = await client.get(
+        f"/repos/{owner}/{repo}/actions/runs", params=params
+    )
+
+    runs = result.get("workflow_runs", [])
+    items = [
+        {
+            "id": run.get("id"),
+            "name": run.get("name"),
+            "head_branch": run.get("head_branch"),
+            "event": run.get("event"),
+            "status": run.get("status"),
+            "conclusion": run.get("conclusion"),
+            "html_url": run.get("html_url"),
+            "created_at": run.get("created_at"),
+        }
+        for run in runs
+    ]
+
+    return {
+        "total_count": result.get("total_count", len(items)),
+        "items": items,
+    }
+
+
+async def trigger_workflow(
+    owner: str | None,
+    repo: str,
+    workflow_id: str,
+    ref: str | None = None,
+    inputs: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Trigger a fresh GitHub Actions run via the workflow_dispatch event.
+
+    Unlike ``rerun_workflow_run`` (which re-runs an *existing* run and is
+    rejected by GitHub with a 403 for runs created more than 30 days ago),
+    this dispatches a brand-new run, so it works no matter how long ago the
+    workflow last ran. The target workflow's YAML must declare an
+    ``on: workflow_dispatch`` trigger.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        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. Defaults to the
+            repository's default branch when omitted.
+        inputs: Optional workflow_dispatch inputs as name/value pairs
+
+    Returns:
+        A confirmation dict:
+        {"status": "dispatch_requested", "workflow": ..., "ref": ...}
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    workflow_id = validate_name(workflow_id, "workflow_id")
+
+    client = get_client()
+
+    if ref is None or not ref.strip():
+        repo_info = await client.get(f"/repos/{owner}/{repo}")
+        ref = repo_info.get("default_branch", "main")
+    ref = validate_ref(ref)
+
+    body: dict[str, Any] = {"ref": ref}
+    if inputs:
+        body["inputs"] = validate_workflow_inputs(inputs)
+
+    await client.post(
+        f"/repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches",
+        json_data=body,
+    )
+    return {"status": "dispatch_requested", "workflow": workflow_id, "ref": ref}
+
+
+async def rerun_workflow_run(
+    owner: str | None,
+    repo: str,
+    run_id: int,
+) -> dict[str, Any]:
+    """Re-run all jobs in a GitHub Actions workflow run.
+
+    GitHub rejects re-runs of runs created more than 30 days ago with a 403
+    ("Unable to retry this workflow run because it was created over a month
+    ago"). That is NOT a permission problem: it surfaces as a GitHubApiError
+    carrying GitHub's message, not a PermissionDeniedError (which is reserved
+    for 401). To force a fresh build regardless of age, use trigger_workflow.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        run_id: Workflow run ID
+
+    Returns:
+        A confirmation dict: {"status": "rerun_requested", "run_id": run_id}
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    run_id = validate_positive_int(run_id, "run_id")
+
+    client = get_client()
+    await client.post(f"/repos/{owner}/{repo}/actions/runs/{run_id}/rerun")
+    return {"status": "rerun_requested", "run_id": run_id}
+
+
+async def rerun_failed_jobs(
+    owner: str | None,
+    repo: str,
+    run_id: int,
+) -> dict[str, Any]:
+    """Re-run only the failed jobs in a GitHub Actions workflow run.
+
+    As with rerun_workflow_run, GitHub rejects re-runs of runs older than 30
+    days with a 403 that surfaces as a GitHubApiError (GitHub's message
+    preserved), not a PermissionDeniedError. Use trigger_workflow to force a
+    fresh build regardless of age.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        run_id: Workflow run ID
+
+    Returns:
+        A confirmation dict: {"status": "rerun_requested", "run_id": run_id}
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    run_id = validate_positive_int(run_id, "run_id")
+
+    client = get_client()
+    await client.post(
+        f"/repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs"
+    )
+    return {"status": "rerun_requested", "run_id": run_id}

mcp_github_crunchtools/tools/files.py

@@ -0,0 +1,124 @@
+"""Repository file tools.
+
+Tools for reading file content and listing the git tree of a repository.
+"""
+
+import base64
+import binascii
+from typing import Any
+from urllib.parse import quote
+
+from ..client import get_client
+from ..errors import ValidationError
+from ..models import (
+    MAX_PATH_LENGTH,
+    resolve_owner,
+    validate_name,
+)
+
+MAX_DECODE_SIZE = 1024 * 1024
+
+
+async def get_file_content(
+    owner: str | None,
+    repo: str,
+    path: str,
+    ref: str | None = None,
+) -> dict[str, Any]:
+    """Get the decoded text content of a file in a repository.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        path: Path to the file within the repository
+        ref: Branch, tag, or commit SHA (default: the repository's default branch)
+
+    Returns:
+        File metadata plus the decoded text under "text", or a notice if the
+        content is binary or too large to decode
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+
+    if not path or not path.strip():
+        raise ValidationError("path must not be empty")
+    if len(path) > MAX_PATH_LENGTH:
+        raise ValidationError("path is too long")
+    if ".." in path:
+        raise ValidationError("path must not contain '..'")
+
+    encoded_path = quote(path.strip(), safe="/")
+
+    client = get_client()
+    params = {"ref": ref} if ref else None
+    result = await client.get(
+        f"/repos/{owner}/{repo}/contents/{encoded_path}", params=params
+    )
+
+    if isinstance(result.get("content"), list):
+        raise ValidationError("path refers to a directory, not a file")
+
+    encoding = result.get("encoding")
+    raw_content = result.get("content", "")
+    size = result.get("size", 0)
+
+    summary: dict[str, Any] = {
+        "name": result.get("name"),
+        "path": result.get("path"),
+        "sha": result.get("sha"),
+        "size": size,
+        "encoding": encoding,
+        "html_url": result.get("html_url"),
+        "download_url": result.get("download_url"),
+    }
+
+    if encoding != "base64" or not raw_content:
+        summary["text"] = None
+        summary["notice"] = "Content not available as base64 (binary or empty)."
+        return summary
+
+    if size and size > MAX_DECODE_SIZE:
+        summary["text"] = None
+        summary["notice"] = "File too large to decode; use download_url."
+        return summary
+
+    try:
+        decoded = base64.b64decode(raw_content)
+        summary["text"] = decoded.decode("utf-8")
+    except (binascii.Error, UnicodeDecodeError):
+        summary["text"] = None
+        summary["notice"] = "Content is binary; use download_url."
+
+    return summary
+
+
+async def list_repo_tree(
+    owner: str | None,
+    repo: str,
+    tree_sha: str = "HEAD",
+    recursive: bool = False,
+) -> dict[str, Any]:
+    """List the git tree (files and directories) of a repository.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        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
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+
+    if not tree_sha or not tree_sha.strip():
+        raise ValidationError("tree_sha must not be empty")
+
+    encoded_sha = quote(tree_sha.strip(), safe="")
+
+    client = get_client()
+    params = {"recursive": "1"} if recursive else None
+    return await client.get(
+        f"/repos/{owner}/{repo}/git/trees/{encoded_sha}", params=params
+    )

mcp_github_crunchtools/tools/issues.py

@@ -0,0 +1,224 @@
+"""Issue management tools.
+
+Tools for listing, fetching, and commenting on GitHub issues.
+"""
+
+from typing import Any
+
+from ..client import get_client
+from ..errors import ValidationError
+from ..models import (
+    ISSUE_STATES,
+    CreateIssueCommentInput,
+    CreateIssueInput,
+    clamp_per_page,
+    resolve_owner,
+    validate_name,
+    validate_positive_int,
+)
+
+
+async def list_issues(
+    owner: str | None,
+    repo: str,
+    state: str = "open",
+    labels: str | None = None,
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """List issues for a repository.
+
+    Pull requests are filtered out (the GitHub issues endpoint includes PRs).
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        state: Filter by state (open, closed, all)
+        labels: Comma-separated label names
+        per_page: Results per page (max 100)
+        page: Page number
+
+    Returns:
+        List of issues with pagination info
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    if state not in ISSUE_STATES:
+        allowed = ", ".join(sorted(ISSUE_STATES))
+        raise ValidationError(f"Invalid state. Allowed: {allowed}")
+
+    client = get_client()
+
+    params: dict[str, Any] = {
+        "state": state,
+        "per_page": clamp_per_page(per_page),
+        "page": validate_positive_int(page, "page"),
+    }
+    if labels:
+        params["labels"] = labels
+
+    result = await client.get(f"/repos/{owner}/{repo}/issues", params=params)
+
+    items = result.get("items", [])
+    result["items"] = [item for item in items if "pull_request" not in item]
+
+    return result
+
+
+async def get_issue(
+    owner: str | None,
+    repo: str,
+    issue_number: int,
+) -> dict[str, Any]:
+    """Get a single issue by number.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        issue_number: Issue number (the value shown in the UI, e.g., #42)
+
+    Returns:
+        Issue details
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    issue_number = validate_positive_int(issue_number, "issue_number")
+
+    client = get_client()
+    return await client.get(f"/repos/{owner}/{repo}/issues/{issue_number}")
+
+
+async def create_issue(
+    owner: str | None,
+    repo: str,
+    title: str,
+    body: str = "",
+    labels: list[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new issue in a repository.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        title: Issue title (required, non-empty)
+        body: Issue body (Markdown)
+        labels: Optional list of label names to apply
+
+    Returns:
+        Created issue details (number, html_url, title)
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    if not title or not title.strip():
+        raise ValidationError("title must not be empty")
+    validated = CreateIssueInput(title=title.strip(), body=body)
+
+    json_data: dict[str, Any] = {
+        "title": validated.title,
+        "body": validated.body,
+    }
+    if labels:
+        json_data["labels"] = labels
+
+    client = get_client()
+    result = await client.post(
+        f"/repos/{owner}/{repo}/issues",
+        json_data=json_data,
+    )
+    return {
+        "number": result.get("number"),
+        "html_url": result.get("html_url"),
+        "title": result.get("title"),
+    }
+
+
+async def update_issue(
+    owner: str | None,
+    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,
+) -> dict[str, Any]:
+    """Update an existing issue — including closing or reopening it.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        issue_number: Issue number
+        state: "open" or "closed" (set "closed" to close the issue)
+        state_reason: When closing, one of "completed" or "not_planned";
+            when reopening, "reopened"
+        title: New title (optional)
+        body: New body (optional)
+        labels: Replacement list of label names (optional)
+
+    Returns:
+        Updated issue details (number, state, html_url, title)
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    issue_number = validate_positive_int(issue_number, "issue_number")
+
+    json_data: dict[str, Any] = {}
+    if state is not None:
+        if state not in ("open", "closed"):
+            raise ValidationError("state must be 'open' or 'closed'")
+        json_data["state"] = state
+    if state_reason is not None:
+        if state_reason not in ("completed", "not_planned", "reopened"):
+            raise ValidationError(
+                "state_reason must be 'completed', 'not_planned', or 'reopened'"
+            )
+        json_data["state_reason"] = state_reason
+    if title is not None:
+        json_data["title"] = title
+    if body is not None:
+        json_data["body"] = body
+    if labels is not None:
+        json_data["labels"] = labels
+    if not json_data:
+        raise ValidationError("no fields to update")
+
+    client = get_client()
+    result = await client.patch(
+        f"/repos/{owner}/{repo}/issues/{issue_number}",
+        json_data=json_data,
+    )
+    return {
+        "number": result.get("number"),
+        "state": result.get("state"),
+        "html_url": result.get("html_url"),
+        "title": result.get("title"),
+    }
+
+
+async def create_issue_comment(
+    owner: str | None,
+    repo: str,
+    issue_number: int,
+    body: str,
+) -> dict[str, Any]:
+    """Create a comment on an issue or pull request.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        issue_number: Issue or pull request number
+        body: Comment body (Markdown)
+
+    Returns:
+        Created comment details
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    issue_number = validate_positive_int(issue_number, "issue_number")
+    validated = CreateIssueCommentInput(body=body)
+
+    client = get_client()
+    return await client.post(
+        f"/repos/{owner}/{repo}/issues/{issue_number}/comments",
+        json_data={"body": validated.body},
+    )