github-mcp 1.1.0__py3-none-any.whl

github_mcp/tools/repos.py

@@ -0,0 +1,686 @@
+from __future__ import annotations
+
+import base64
+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_list_markdown,
+    fmt_timestamp,
+)
+
+# MARK: Input models
+
+
+class ListReposInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: Optional[str] = Field(
+        default=None,
+        description=(
+            "GitHub username or org whose repos to list. "
+            "Leave empty to list repos for the authenticated user."
+        ),
+    )
+    type: Optional[str] = Field(
+        default="all",
+        description="Filter by type: 'all', 'public', 'private', 'forks', 'sources', 'member'. Default 'all'.",
+    )
+    sort: Optional[str] = Field(
+        default="updated",
+        description="Sort key: 'created', 'updated', 'pushed', 'full_name'. Default 'updated'.",
+    )
+    limit: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Maximum repos 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: 'markdown' (default) or 'json'.",
+    )
+
+
+class GetRepoInput(BaseModel):
+    model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
+
+    owner: str = Field(
+        ...,
+        description="Repository owner (username or org, e.g. 'octocat').",
+        min_length=1,
+    )
+    repo: str = Field(
+        ..., description="Repository name (e.g. 'Hello-World').", min_length=1
+    )
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class ListBranchesInput(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)
+    limit: int = Field(
+        default=20, ge=1, le=100, description="Maximum branches to return."
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class ListCommitsInput(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)
+    sha: Optional[str] = Field(
+        default=None,
+        description="Branch, tag, or commit SHA to list commits from. Defaults to the repo's default branch.",
+    )
+    path: Optional[str] = Field(
+        default=None,
+        description="Only return commits that touch this file/directory path.",
+    )
+    since: Optional[str] = Field(
+        default=None,
+        description="ISO 8601 timestamp — return commits after this date (e.g. '2024-01-01T00:00:00Z').",
+    )
+    limit: int = Field(
+        default=20, ge=1, le=100, description="Maximum commits to return."
+    )
+    page: int = Field(default=1, ge=1, description="Page number.")
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class GetFileContentsInput(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)
+    path: str = Field(
+        ...,
+        description="Path to the file within the repository (e.g. 'src/main.py').",
+        min_length=1,
+    )
+    ref: Optional[str] = Field(
+        default=None,
+        description="Branch, tag, or commit SHA to read from. Defaults to the repo's default branch.",
+    )
+
+
+class ListDirectoryInput(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)
+    path: str = Field(
+        default="",
+        description="Directory path within the repo. Use '' or '.' for the root.",
+    )
+    ref: Optional[str] = Field(
+        default=None,
+        description="Branch, tag, or commit SHA. Defaults to the repo's default branch.",
+    )
+    response_format: ResponseFormat = Field(
+        default=ResponseFormat.MARKDOWN, description="Output format."
+    )
+
+
+class CreateOrUpdateFileInput(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)
+    path: str = Field(
+        ...,
+        description="Path of the file to create or update (e.g. 'docs/guide.md').",
+        min_length=1,
+    )
+    message: str = Field(..., description="Commit message.", min_length=1)
+    content: str = Field(
+        ...,
+        description="New file content (plain text — will be base64-encoded automatically).",
+    )
+    sha: Optional[str] = Field(
+        default=None,
+        description=(
+            "Blob SHA of the existing file (required when updating). "
+            "Obtain via github_get_file_contents. Omit when creating a new file."
+        ),
+    )
+    branch: Optional[str] = Field(
+        default=None,
+        description="Branch to commit to. Defaults to the repo's default branch.",
+    )
+
+
+class CreateBranchInput(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)
+    branch: str = Field(
+        ..., description="Name of the new branch to create.", min_length=1
+    )
+    base_ref: str = Field(
+        ...,
+        description="Branch, tag, or commit SHA to branch from (e.g. 'main', 'v1.2.0').",
+        min_length=1,
+    )
+
+
+# MARK: Tools
+
+
+@mcp.tool(
+    name="github_list_repos",
+    annotations=ToolAnnotations(
+        title="List GitHub Repositories",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_list_repos(params: ListReposInput) -> str:
+    """List repositories for the authenticated user or a specific owner/org.
+
+    Returns a paginated list of repositories with key metadata.
+
+    Args:
+        params (ListReposInput): Validated input containing:
+            - owner (Optional[str]): GitHub username or org. Empty = authenticated user.
+            - type (Optional[str]): Filter type ('all', 'public', 'private', etc.)
+            - sort (Optional[str]): Sort key ('updated', 'created', etc.)
+            - limit (int): Max repos to return (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted list of repositories. Markdown includes name, description,
+            language, stars, forks, visibility, and URL. JSON is the raw API array.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        if params.owner:
+            path = f"/users/{params.owner}/repos"
+        else:
+            path = "/user/repos"
+
+        query: dict = {
+            "type": params.type,
+            "sort": params.sort,
+            "per_page": params.limit,
+            "page": params.page,
+        }
+        resp = await github_request(
+            "GET", path, params={k: v for k, v in query.items() if v is not None}
+        )
+        repos = resp.json()
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(repos)
+
+        return fmt_list_markdown(
+            repos,
+            title=f"Repositories for {params.owner or 'you'}",
+            fields=[
+                "description",
+                "language",
+                "stargazers_count",
+                "forks_count",
+                "visibility",
+                "updated_at",
+            ],
+            name_field="full_name",
+        )
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_get_repo",
+    annotations=ToolAnnotations(
+        title="Get GitHub Repository",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_get_repo(params: GetRepoInput) -> str:
+    """Get full metadata for a single GitHub repository.
+
+    Args:
+        params (GetRepoInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Repository details. Markdown shows name, description, language,
+            stars, forks, open issues, default branch, topics, license, and URL.
+            JSON is the full raw API object.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        resp = await github_request("GET", f"/repos/{params.owner}/{params.repo}")
+        repo = resp.json()
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(repo)
+
+        lines = [
+            f"## {repo.get('full_name', '')}",
+            "",
+            f"{repo.get('description') or '*No description*'}",
+            "",
+            f"- **URL**: {repo.get('html_url', '')}",
+            f"- **Language**: {repo.get('language') or 'N/A'}",
+            f"- **Stars**: {repo.get('stargazers_count', 0):,}",
+            f"- **Forks**: {repo.get('forks_count', 0):,}",
+            f"- **Open Issues**: {repo.get('open_issues_count', 0):,}",
+            f"- **Default Branch**: {repo.get('default_branch', 'main')}",
+            f"- **Visibility**: {repo.get('visibility', 'N/A')}",
+            f"- **Created**: {fmt_timestamp(repo.get('created_at'))}",
+            f"- **Updated**: {fmt_timestamp(repo.get('updated_at'))}",
+            f"- **Pushed**: {fmt_timestamp(repo.get('pushed_at'))}",
+        ]
+        if repo.get("license"):
+            lines.append(
+                f"- **License**: {repo['license'].get('spdx_id', repo['license'].get('name', 'N/A'))}"
+            )
+        topics = repo.get("topics", [])
+        if topics:
+            lines.append(f"- **Topics**: {', '.join(topics)}")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_list_branches",
+    annotations=ToolAnnotations(
+        title="List Repository Branches",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_list_branches(params: ListBranchesInput) -> str:
+    """List branches in a GitHub repository.
+
+    Args:
+        params (ListBranchesInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - limit (int): Max branches to return (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted branch list. Markdown shows branch name and latest commit SHA.
+            JSON is the raw API array.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/branches",
+            params={"per_page": params.limit, "page": params.page},
+        )
+        branches = resp.json()
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(branches)
+
+        lines = [f"## Branches: {params.owner}/{params.repo}", ""]
+        if not branches:
+            lines.append("*No branches found.*")
+        else:
+            for branch in branches:
+                sha = branch.get("commit", {}).get("sha", "")[:7]
+                protected = " 🔒" if branch.get("protected") else ""
+                lines.append(f"- **{branch['name']}**{protected} — `{sha}`")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_list_commits",
+    annotations=ToolAnnotations(
+        title="List Repository Commits",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_list_commits(params: ListCommitsInput) -> str:
+    """List commits in a repository, optionally filtered by branch/path/date.
+
+    Args:
+        params (ListCommitsInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - sha (Optional[str]): Branch, tag, or commit SHA to start from.
+            - path (Optional[str]): Only commits touching this path.
+            - since (Optional[str]): ISO 8601 date — commits after this time.
+            - limit (int): Max commits (1–100).
+            - page (int): Page number.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Formatted commit list. Markdown shows SHA (short), author, date,
+            and commit message. JSON is the raw API array.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        query: dict = {"per_page": params.limit, "page": params.page}
+        if params.sha:
+            query["sha"] = params.sha
+        if params.path:
+            query["path"] = params.path
+        if params.since:
+            query["since"] = params.since
+
+        resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/commits",
+            params=query,
+        )
+        commits = resp.json()
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(commits)
+
+        lines = [f"## Commits: {params.owner}/{params.repo}", ""]
+        if not commits:
+            lines.append("*No commits found.*")
+        else:
+            for commit in commits:
+                sha = commit["sha"][:7]
+                msg = commit["commit"]["message"].split("\n")[0][:80]
+                author = commit["commit"]["author"].get("name", "unknown")
+                date = fmt_timestamp(commit["commit"]["author"].get("date"))
+                url = commit.get("html_url", "")
+                if url:
+                    lines.append(f"- [`{sha}`]({url}) {msg}")
+                else:
+                    lines.append(f"- `{sha}` {msg}")
+                lines.append(f"  - Author: {author} — {date}")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_get_file_contents",
+    annotations=ToolAnnotations(
+        title="Get File Contents from Repository",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_get_file_contents(params: GetFileContentsInput) -> str:
+    """Read the decoded text content of a file in a GitHub repository.
+
+    Also returns the blob SHA needed for subsequent updates.
+
+    Args:
+        params (GetFileContentsInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - path (str): File path within the repo (e.g. 'src/main.py').
+            - ref (Optional[str]): Branch, tag, or commit SHA.
+
+    Returns:
+        str: A header line with path, ref, SHA and size, followed by the
+            decoded file content. Format:
+            ```
+            # path/to/file (ref: main | sha: abc1234 | size: 1234 bytes)
+            <file content>
+            ```
+
+        Error response: "Error <code>: <message>" string.
+        "Error: Path ... is a directory" if path points to a directory.
+    """
+    try:
+        query: dict = {}
+        if params.ref:
+            query["ref"] = params.ref
+
+        resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/contents/{params.path.lstrip('/')}",
+            params=query or None,
+        )
+        data = resp.json()
+
+        if isinstance(data, list):
+            return f"Error: Path '{params.path}' is a directory. Use github_list_directory instead."
+
+        if data.get("type") != "file":
+            return f"Error: Path '{params.path}' is not a regular file (type: {data.get('type')})."
+
+        encoded = data.get("content", "")
+        decoded = base64.b64decode(encoded).decode("utf-8", errors="replace")
+        sha = data.get("sha", "")
+        size = data.get("size", 0)
+        used_ref = params.ref or "default branch"
+
+        header = f"# {params.path} (ref: {used_ref} | sha: {sha} | size: {size} bytes)"
+        return f"{header}\n\n{decoded}"
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_list_directory",
+    annotations=ToolAnnotations(
+        title="List Repository Directory",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=True,
+    ),
+)
+async def github_list_directory(params: ListDirectoryInput) -> str:
+    """List files and subdirectories at a path in a GitHub repository.
+
+    Args:
+        params (ListDirectoryInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - path (str): Directory path (use '' or '.' for root).
+            - ref (Optional[str]): Branch, tag, or commit SHA.
+            - response_format (ResponseFormat): 'markdown' or 'json'.
+
+    Returns:
+        str: Markdown or JSON listing. Markdown shows each entry as a bullet
+            with name, type (file/dir), and size for files.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        query: dict = {}
+        if params.ref:
+            query["ref"] = params.ref
+
+        # Normalize path
+        clean_path = params.path.strip("/").strip() or ""
+        api_path = (
+            f"/repos/{params.owner}/{params.repo}/contents/{clean_path}"
+            if clean_path
+            else f"/repos/{params.owner}/{params.repo}/contents"
+        )
+
+        resp = await github_request("GET", api_path, params=query or None)
+        entries = resp.json()
+
+        if not isinstance(entries, list):
+            return f"Error: Path '{params.path}' is a file, not a directory. Use github_get_file_contents instead."
+
+        if params.response_format == ResponseFormat.JSON:
+            return fmt_json(entries)
+
+        display_path = params.path or "/"
+        lines = [
+            f"## Directory listing: {params.owner}/{params.repo} @ {display_path}",
+            "",
+        ]
+        if not entries:
+            lines.append("*Empty directory.*")
+        else:
+            dirs = [e for e in entries if e.get("type") == "dir"]
+            files = [e for e in entries if e.get("type") == "file"]
+            for entry in sorted(dirs, key=lambda x: x.get("name", "")):
+                lines.append(f"- 📁 **{entry['name']}/**")
+            for entry in sorted(files, key=lambda x: x.get("name", "")):
+                size = entry.get("size", 0)
+                lines.append(f"- 📄 {entry['name']} ({size:,} bytes)")
+        return "\n".join(lines)
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_create_or_update_file",
+    annotations=ToolAnnotations(
+        title="Create or Update a File in Repository",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_create_or_update_file(params: CreateOrUpdateFileInput) -> str:
+    """Create a new file or update an existing file in a GitHub repository.
+
+    For updates, the current blob SHA (from github_get_file_contents) must be
+    provided to prevent accidental overwrites.
+
+    Args:
+        params (CreateOrUpdateFileInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - path (str): File path to create/update.
+            - message (str): Commit message.
+            - content (str): New plain-text content (auto base64-encoded).
+            - sha (Optional[str]): Existing blob SHA (required for updates).
+            - branch (Optional[str]): Target branch (defaults to repo default).
+
+    Returns:
+        str: Confirmation with commit SHA, URL, and file path on success.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        encoded_content = base64.b64encode(params.content.encode("utf-8")).decode(
+            "ascii"
+        )
+        body: dict = {"message": params.message, "content": encoded_content}
+        if params.sha:
+            body["sha"] = params.sha
+        if params.branch:
+            body["branch"] = params.branch
+
+        resp = await github_request(
+            "PUT",
+            f"/repos/{params.owner}/{params.repo}/contents/{params.path.lstrip('/')}",
+            json=body,
+        )
+        data = resp.json()
+        commit = data.get("commit", {})
+        commit_sha = commit.get("sha", "")[:7]
+        commit_url = commit.get("html_url", "")
+        action = "Updated" if params.sha else "Created"
+        return (
+            f"{action} file `{params.path}` on branch `{params.branch or 'default'}`.\n"
+            f"Commit: [{commit_sha}]({commit_url}) — {params.message}"
+        )
+    except Exception as e:
+        return handle_github_error(e)
+
+
+@mcp.tool(
+    name="github_create_branch",
+    annotations=ToolAnnotations(
+        title="Create a New Branch",
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+)
+async def github_create_branch(params: CreateBranchInput) -> str:
+    """Create a new branch from an existing branch, tag, or commit SHA.
+
+    Args:
+        params (CreateBranchInput): Validated input containing:
+            - owner (str): Repository owner.
+            - repo (str): Repository name.
+            - branch (str): New branch name.
+            - base_ref (str): Existing branch/tag/SHA to branch from.
+
+    Returns:
+        str: Confirmation with the new branch name and the SHA it points to.
+
+        Error response: "Error <code>: <message>" string.
+    """
+    try:
+        # Resolve the base ref to a commit SHA
+        ref_resp = await github_request(
+            "GET",
+            f"/repos/{params.owner}/{params.repo}/git/ref/heads/{params.base_ref}",
+        )
+        sha = ref_resp.json()["object"]["sha"]
+    except Exception:
+        # Might be a tag or direct SHA — try tags
+        try:
+            ref_resp = await github_request(
+                "GET",
+                f"/repos/{params.owner}/{params.repo}/git/ref/tags/{params.base_ref}",
+            )
+            sha = ref_resp.json()["object"]["sha"]
+        except Exception:
+            # Treat base_ref as a raw SHA
+            sha = params.base_ref
+
+    try:
+        resp = await github_request(
+            "POST",
+            f"/repos/{params.owner}/{params.repo}/git/refs",
+            json={"ref": f"refs/heads/{params.branch}", "sha": sha},
+        )
+        data = resp.json()
+        created_sha = data.get("object", {}).get("sha", sha)[:7]
+        return (
+            f"Branch `{params.branch}` created in {params.owner}/{params.repo} "
+            f"from `{params.base_ref}` (SHA: {created_sha})."
+        )
+    except Exception as e:
+        return handle_github_error(e)