github-mcp 1.1.0__py3-none-any.whl

github_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""GitHub MCP Server — exposes GitHub REST API via FastMCP stdio transport."""
+
+__version__ = "0.1.0"

github_mcp/app.py

@@ -0,0 +1,3 @@
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("github_mcp")

github_mcp/client.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+# MARK: Constants
+
+GITHUB_API_BASE = "https://api.github.com"
+GITHUB_API_VERSION = "2022-11-28"
+DEFAULT_ACCEPT = "application/vnd.github+json"
+TIMEOUT = 30.0  # seconds
+
+# MARK: Lazy-initialised shared client
+
+_client: httpx.AsyncClient | None = None
+
+
+def _get_token() -> str:
+    """Return the GitHub PAT from environment variables.
+    Checks ``GITHUB_TOKEN`` first, then falls back to ``GITHUB_PAT``.
+
+    Returns:
+        str: The GitHub token string.
+
+    Raises:
+        RuntimeError: If neither env var is set, with instructions on how to
+            set the token.
+    """
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GITHUB_PAT")
+    if not token:
+        raise RuntimeError(
+            "GitHub token not found. "
+            "Set GITHUB_TOKEN (or GITHUB_PAT) to a fine-grained Personal Access Token. "
+            "Create one at https://github.com/settings/tokens?type=beta with the "
+            "required permissions (Contents, Issues, Pull requests, Metadata)."
+        )
+    return token
+
+
+def _get_client() -> httpx.AsyncClient:
+    """Return (lazily creating) the shared ``httpx.AsyncClient``
+
+    Returns:
+        httpx.AsyncClient: The shared HTTP client instance.
+    """
+    global _client
+    if _client is None or _client.is_closed:
+        token = _get_token()
+        _client = httpx.AsyncClient(
+            base_url=GITHUB_API_BASE,
+            headers={
+                "Accept": DEFAULT_ACCEPT,
+                "Authorization": f"Bearer {token}",
+                "X-GitHub-Api-Version": GITHUB_API_VERSION,
+                "User-Agent": "github-mcp/0.1.0",
+            },
+            timeout=TIMEOUT,
+            follow_redirects=True,
+        )
+    return _client
+
+
+# MARK: Core request helpers
+
+
+async def github_request(
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json: Any = None,
+    accept: str | None = None,
+) -> httpx.Response:
+    """Perform a single authenticated GitHub REST API request.
+
+    Args:
+        method (str): HTTP method (GET, POST, PUT, PATCH, DELETE).
+        path (str): API path, e.g. ``/repos/owner/repo``.
+        params (dict[str, Any] | None): Optional query parameters dict.
+        json (Any): Optional request body to serialise as JSON.
+        accept (str | None): Override the ``Accept`` header (e.g. for diff responses).
+
+    Returns:
+        httpx.Response: The raw ``httpx.Response`` (caller can call ``.json()`` or ``.text``).
+
+    Raises:
+        httpx.HTTPStatusError: On 4xx/5xx responses (raised by
+            ``raise_for_status()``).
+    """
+    client = _get_client()
+    headers = {}
+    if accept:
+        headers["Accept"] = accept
+
+    response = await client.request(
+        method,
+        path,
+        params=params,
+        json=json,
+        headers=headers,
+    )
+    response.raise_for_status()
+    return response
+
+
+async def github_paginated(
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    max_items: int = 100,
+) -> list[Any]:
+    """Fetch all pages of a GitHub list endpoint up to *max_items*.
+
+    Follows the ``Link: rel="next"`` header automatically.
+
+    Args:
+        path (str): API path for the first page.
+        params (dict[str, Any] | None): Base query parameters (``per_page`` will be added/capped).
+        max_items (int): Hard cap on total items collected.
+
+    Returns:
+        list[Any]: A flat list of items from all fetched pages.
+    """
+    params = dict(params or {})
+    params.setdefault("per_page", min(100, max_items))
+
+    items: list[Any] = []
+    client = _get_client()
+    url: str | None = path
+
+    while url and len(items) < max_items:
+        response = await client.get(url, params=params)
+        response.raise_for_status()
+        page_items = response.json()
+        if isinstance(page_items, dict):
+            # Search responses wrap items under a key like "items"
+            page_items = page_items.get("items", [])
+        items.extend(page_items)
+
+        # After the first request, clear per-page params — Link header is absolute
+        params = {}
+        next_url = _parse_next_link(response.headers.get("link", ""))
+        url = next_url
+
+    return items[:max_items]
+
+
+def _parse_next_link(link_header: str) -> str | None:
+    """Extract the ``rel="next"`` URL from a GitHub ``Link`` header.
+
+    Args:
+        link_header (str): Raw ``Link`` header value.
+
+    Returns:
+        str | None: The next-page URL, or ``None`` if absent.
+    """
+    for part in link_header.split(","):
+        segments = [s.strip() for s in part.split(";")]
+        if len(segments) == 2 and segments[1] == 'rel="next"':
+            return segments[0].strip("<>")
+    return None
+
+
+# MARK: Error handling
+def handle_github_error(e: Exception) -> str:
+    """Convert a GitHub API exception into a human-readable, actionable message.
+
+    Handles the most common error classes:
+    - 401 — invalid or expired token
+    - 403 + rate-limit header — rate limit exceeded (shows reset time)
+    - 403 (other) — permission/scope issue
+    - 404 — resource not found
+    - 409 — merge conflict or state conflict
+    - 422 — validation error (surfaces GitHub's ``errors`` body)
+    - Timeout — connection/read timeout
+
+    Args:
+        e (Exception): The caught exception.
+
+    Returns:
+        str: A human-readable error string suitable for returning directly from a
+        tool.
+    """
+    if isinstance(e, httpx.HTTPStatusError):
+        status = e.response.status_code
+        if status == 401:
+            return (
+                "Error 401 Unauthorized: Your GITHUB_TOKEN is invalid or has expired. "
+                "Generate a new fine-grained PAT at https://github.com/settings/tokens?type=beta "
+                "and update the GITHUB_TOKEN environment variable."
+            )
+        if status == 403:
+            remaining = e.response.headers.get("X-RateLimit-Remaining", "")
+            reset_ts = e.response.headers.get("X-RateLimit-Reset", "")
+            if remaining == "0" and reset_ts:
+                try:
+                    reset_dt = datetime.fromtimestamp(int(reset_ts), tz=timezone.utc)
+                    reset_str = reset_dt.strftime("%Y-%m-%d %H:%M UTC")
+                except (ValueError, OSError):
+                    reset_str = reset_ts
+                return (
+                    f"Error 403 Rate Limit Exceeded: GitHub API rate limit reached. "
+                    f"Resets at {reset_str}. "
+                    "Consider using a GITHUB_TOKEN to get a higher rate limit (5 000 req/h vs 60)."
+                )
+            return (
+                "Error 403 Forbidden: You do not have permission for this operation. "
+                "Check that your GITHUB_TOKEN has the required scopes "
+                "(Contents, Issues, Pull requests, Metadata)."
+            )
+        if status == 404:
+            return (
+                "Error 404 Not Found: The requested resource does not exist. "
+                "Verify the owner, repo, number, or path is correct and that your "
+                "token has access to the repository."
+            )
+        if status == 409:
+            return (
+                "Error 409 Conflict: The operation could not be completed due to a conflict. "
+                "For merges: the branch may have conflicts that must be resolved first. "
+                "For file updates: the sha you provided may be stale — fetch the current sha "
+                "with github_get_file_contents first."
+            )
+        if status == 422:
+            try:
+                body = e.response.json()
+                msgs: list[str] = []
+                if "message" in body:
+                    msgs.append(body["message"])
+                for err in body.get("errors", []):
+                    if isinstance(err, dict):
+                        msgs.append(err.get("message") or str(err))
+                    else:
+                        msgs.append(str(err))
+                detail = " | ".join(msgs) if msgs else e.response.text
+            except Exception:
+                detail = e.response.text
+            return f"Error 422 Unprocessable Entity: {detail}"
+        return f"Error {status}: {e.response.text[:400]}"
+
+    if isinstance(e, httpx.TimeoutException):
+        return (
+            "Error: Request to GitHub timed out after 30 seconds. "
+            "Try again; if the problem persists the GitHub API may be experiencing issues."
+        )
+    if isinstance(e, RuntimeError):
+        # Re-surface our own token errors unchanged
+        return f"Configuration Error: {e}"
+    return f"Error: Unexpected error — {type(e).__name__}: {e}"

github_mcp/formatting.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class ResponseFormat(str, Enum):
+    """Output format for tool responses."""
+
+    MARKDOWN = "markdown"
+    JSON = "json"
+
+
+# MARK: Timestamp formatting
+
+
+def fmt_timestamp(value: str | int | float | None) -> str:
+    """Convert a GitHub timestamp to "YYYY-MM-DD HH:MM UTC".
+    Accepts:
+    - ISO 8601 strings (``"2024-01-15T10:30:00Z"``)
+    - Unix epoch ints/floats
+
+    Args:
+        value (str | int | float | None): Timestamp string, epoch time, or None.
+    Returns:
+        str: Formatted string, or the original value as-is if conversion fails.
+    """
+    if value is None:
+        return "N/A"
+    try:
+        if isinstance(value, (int, float)):
+            dt = datetime.fromtimestamp(value, tz=timezone.utc)
+        else:
+            # Handle both "Z" and "+00:00" suffixes
+            cleaned = str(value).replace("Z", "+00:00")
+            dt = datetime.fromisoformat(cleaned)
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+        return dt.strftime("%Y-%m-%d %H:%M UTC")
+    except (ValueError, OSError, OverflowError):
+        return str(value)
+
+
+# MARK: List / item formatting helpers
+
+# Fields that should always be rendered as timestamps when present
+_TIMESTAMP_FIELDS = frozenset(
+    {
+        "created_at",
+        "updated_at",
+        "pushed_at",
+        "closed_at",
+        "merged_at",
+        "committed_date",
+    }
+)
+
+
+def _fmt_field(key: str, value: Any) -> str:
+    """Format a single field value for markdown output.
+
+    Args:
+        key (str): The field name.
+        value (Any): The field value.
+
+    Returns:
+        str: The formatted value.
+    """
+    if key in _TIMESTAMP_FIELDS:
+        return fmt_timestamp(value)
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if value is None:
+        return "N/A"
+    return str(value)
+
+
+def fmt_list_markdown(
+    items: list[dict[str, Any]],
+    *,
+    title: str = "",
+    fields: list[str],
+    name_field: str = "name",
+) -> str:
+    """Render a compact markdown list from a sequence of dicts.
+
+    Each item becomes a bullet with the ``name_field`` as the heading and
+    one sub-bullet per entry in ``fields`` (if the field is present and
+    non-empty).  A ``html_url`` field is always appended if present.
+
+    Args:
+        items (list[dict[str, Any]]): List of item dicts (e.g. from a GitHub API list endpoint).
+        title (str): Optional markdown heading (rendered as ``## title``).
+        fields (list[str]): Field names to include in each item's detail lines.
+        name_field (str): Key to use as the item's "name" / primary label.
+
+    Returns:
+        str: Formatted markdown string.
+    """
+    lines: list[str] = []
+    if title:
+        lines.append(f"## {title}")
+        lines.append("")
+
+    if not items:
+        lines.append("*No items found.*")
+        return "\n".join(lines)
+
+    for item in items:
+        name = (
+            item.get(name_field)
+            or item.get("title")
+            or item.get("login")
+            or item.get("sha", "")[:7]
+            or "—"
+        )
+        url = item.get("html_url", "")
+        if url:
+            lines.append(f"- **[{name}]({url})**")
+        else:
+            lines.append(f"- **{name}**")
+
+        for field in fields:
+            val = item.get(field)
+            if val is None or val == "":
+                continue
+            pretty_key = field.replace("_", " ").title()
+            lines.append(f"  - {pretty_key}: {_fmt_field(field, val)}")
+
+    return "\n".join(lines)
+
+
+def fmt_json(data: Any) -> str:
+    """Serialise *data* to a pretty-printed JSON string.
+
+    Args:
+        data (Any): Any JSON-serialisable value.
+
+    Returns:
+        str: Indented JSON string.
+    """
+    return json.dumps(data, indent=2, default=str)

github_mcp/server.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+# Import tool modules to register all tools on the shared `mcp` instance.
+import github_mcp.tools.issues  # noqa: F401
+import github_mcp.tools.pulls  # noqa: F401
+import github_mcp.tools.repos  # noqa: F401
+import github_mcp.tools.search  # noqa: F401
+from github_mcp.app import mcp
+
+
+def main() -> None:
+    """Run the GitHub MCP server over stdio transport."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

github_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool sub-package — each module registers tools with the shared FastMCP instance."""