github-mcp 1.1.0__tar.gz

github_mcp-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

github_mcp-1.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: github-mcp
+Version: 1.1.0
+Summary: Local GitHub MCP server exposing GitHub REST API via FastMCP stdio transport
+License: MIT License
+         
+         Copyright (c) 2026 Lucas
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+License-File: LICENSE
+Keywords: github,mcp,fastmcp,stdio,rest api,search
+Author: Lucas Waetzig
+Author-email: development@waetzig.net
+Requires-Python: >=3.12
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: mcp[cli] (>=1.0.0)
+Requires-Dist: pydantic (>=2.13.4,<3.0.0)
+Project-URL: Documentation, https://personal-public-packages.gitlab.io/github-mcp
+Project-URL: Homepage, https://github.com/LWaetzig/github-mcp
+Project-URL: Issues, https://github.com/LWaetzig/github-mcp/issues
+Project-URL: Repository, https://github.com/LWaetzig/github-mcp
+Description-Content-Type: text/markdown
+
+# github-mcp
+
+An MCP (Model COntext Protocol) server that gives AI assistants direct access to GitHub. Exposing ~22 GitHub REST tools
+covering repos, files, issues, pull requests, as well as searching.
+
+## Table of Contents
+
+1. [Features](#features)
+2. [Installation](#installation)
+3. [Usage]()
+4. [Contributing]()
+
+## Features
+
+A single stdio MCP server (built on [FastMCP](https://github.com/modelcontextprotocol/python-sdk)) exposing **23 GitHub REST tools** grouped into four areas:
+
+- **Repositories & files** — `github_list_repos`, `github_get_repo`, `github_list_branches`, `github_list_commits`, `github_get_file_contents`, `github_list_directory`, `github_create_or_update_file`, `github_create_branch`
+- **Issues** — `github_list_issues`, `github_get_issue`, `github_create_issue`, `github_update_issue`, `github_add_issue_comment`
+- **Pull requests** — `github_list_pull_requests`, `github_get_pull_request`, `github_create_pull_request`, `github_merge_pull_request`, `github_add_pr_comment`
+- **Search** — `github_search_repositories`, `github_search_code`, `github_search_issues`, `github_search_users`, `github_search_commits`
+
+Under the hood:
+
+- **Async HTTP** via a shared, lazily-initialised `httpx.AsyncClient` against the pinned GitHub API version (`2022-11-28`).
+- **Automatic pagination** — list endpoints follow the `Link: rel="next"` header up to a configurable item cap.
+- **Typed inputs** — every tool validates its arguments with Pydantic models.
+- **Actionable errors** — common GitHub failures (401, 403/rate-limit with reset time, 404, 409, 422, timeouts) are translated into clear, human-readable messages.
+- **Flexible auth** — reads a fine-grained PAT from `GITHUB_TOKEN`, falling back to `GITHUB_PAT`.
+
+## Installation
+
+### Prerequisites
+
+- `Python 3.12` or later
+- Dependencies `mcp[cli]>=1.0.0`, `httpx>=0.27.0`, `pydantic>=2.0.0` (see [pyproject.toml](pyproject.toml)) (project uses `poetry` for dependency management)
+
+
+### Install from PyPi
+
+```bash
+pip install github-mcp
+
+# or using poetry
+poetry add github-mcp
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/LWaetzig/github-mcp.git
+cd github-mcp
+pip install -e .
+```
+
+## Usage
+
+- Detailed documentation about single tools can be found this [sphinx documentation]()
+
+### Prerequisites
+
+#### Create a fine-grained Personal Access Token (PAT)
+
+1. Go to **GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens** (direct link: <https://github.com/settings/tokens?type=beta>)
+2. Generate new token
+3. Set **Resource owner** and **Repository access** as appropriate
+4. Grant these **Repository permissions** (minimum for full read + write):
+
+| Permission        | Access level   | Used by tools                                                                                                                              |
+| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Metadata**      | Read-only      | All tools                                                                                                                                  |
+| **Contents**      | Read and write | `github_get_file_contents`, `github_list_directory`, `github_list_commits`, `github_create_or_update_file`, `github_create_branch`         |
+| **Issues**        | Read and write | `github_list_issues`, `github_get_issue`, `github_create_issue`, `github_update_issue`, `github_add_issue_comment`                         |
+| **Pull requests** | Read and write | `github_list_pull_requests`, `github_get_pull_request`, `github_create_pull_request`, `github_merge_pull_request`, `github_add_pr_comment` |
+
+> **Read-only subset**: grant only **Read-only** access to Contents, Issues, Pull requests, and Metadata if you don't need write tools.
+
+
+```bash
+export GITHUB_TOKEN=github_pat_...
+```
+
+Or copy `.env.example` -> `.env` and fill in the token (load with `source .env`).
+
+
+### Integrating with Claude Desktop
+
+Add the server to your Claude Desktop configuration:
+
+| Platform | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+Add the `github` entry under `mcpServers`, replacing the path with the absolute path to your clone:
+
+```json
+{
+  "mcpServers" : {
+    "github" : {
+      "command" : "python",
+      "args" : ["-m", "github-mcp"],
+      "env" : {
+        "GITHUB_TOKEN" : "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the github tools available int he tool picker.
+
+### Integration with Other MCP Clients
+
+Any MCP client (e.g. Cline, GitHub Copilot, or custm tools) can use this server.
+Configuration depends on your assistant, in most cases there is a `config` to change.
+
+
+## Contribution
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes with clear messages
+4. Push to your fork
+5. Open a pull request
+
+
+### Live testing with MCP Inspector (requires a real token)
+
+```bash
+GITHUB_TOKEN=... 
+npx @modelcontextprotocol/inspector 
+uv run github-mcp
+```
+
+Then call `github_search_repositories` (q=`"mcp language:python"`) or `github_get_repo` (owner=`"modelcontextprotocol"`, repo=`"python-sdk"`) to verify auth,
+pagination, and formatting end-to-end.
+
+
+## Upcoming Features
+
+- **Projects v2**: Requires GitHub's GraphQL API (`/graphql`). Add a `graphql_client.py` alongside `client.py` and a new `tools/projects.py` module.
+- **Actions**: Also REST-based but with many endpoints. Add `tools/actions.py` importing from `client.py`.

github_mcp-1.1.0/README.md

@@ -0,0 +1,144 @@
+# github-mcp
+
+An MCP (Model COntext Protocol) server that gives AI assistants direct access to GitHub. Exposing ~22 GitHub REST tools
+covering repos, files, issues, pull requests, as well as searching.
+
+## Table of Contents
+
+1. [Features](#features)
+2. [Installation](#installation)
+3. [Usage]()
+4. [Contributing]()
+
+## Features
+
+A single stdio MCP server (built on [FastMCP](https://github.com/modelcontextprotocol/python-sdk)) exposing **23 GitHub REST tools** grouped into four areas:
+
+- **Repositories & files** — `github_list_repos`, `github_get_repo`, `github_list_branches`, `github_list_commits`, `github_get_file_contents`, `github_list_directory`, `github_create_or_update_file`, `github_create_branch`
+- **Issues** — `github_list_issues`, `github_get_issue`, `github_create_issue`, `github_update_issue`, `github_add_issue_comment`
+- **Pull requests** — `github_list_pull_requests`, `github_get_pull_request`, `github_create_pull_request`, `github_merge_pull_request`, `github_add_pr_comment`
+- **Search** — `github_search_repositories`, `github_search_code`, `github_search_issues`, `github_search_users`, `github_search_commits`
+
+Under the hood:
+
+- **Async HTTP** via a shared, lazily-initialised `httpx.AsyncClient` against the pinned GitHub API version (`2022-11-28`).
+- **Automatic pagination** — list endpoints follow the `Link: rel="next"` header up to a configurable item cap.
+- **Typed inputs** — every tool validates its arguments with Pydantic models.
+- **Actionable errors** — common GitHub failures (401, 403/rate-limit with reset time, 404, 409, 422, timeouts) are translated into clear, human-readable messages.
+- **Flexible auth** — reads a fine-grained PAT from `GITHUB_TOKEN`, falling back to `GITHUB_PAT`.
+
+## Installation
+
+### Prerequisites
+
+- `Python 3.12` or later
+- Dependencies `mcp[cli]>=1.0.0`, `httpx>=0.27.0`, `pydantic>=2.0.0` (see [pyproject.toml](pyproject.toml)) (project uses `poetry` for dependency management)
+
+
+### Install from PyPi
+
+```bash
+pip install github-mcp
+
+# or using poetry
+poetry add github-mcp
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/LWaetzig/github-mcp.git
+cd github-mcp
+pip install -e .
+```
+
+## Usage
+
+- Detailed documentation about single tools can be found this [sphinx documentation]()
+
+### Prerequisites
+
+#### Create a fine-grained Personal Access Token (PAT)
+
+1. Go to **GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens** (direct link: <https://github.com/settings/tokens?type=beta>)
+2. Generate new token
+3. Set **Resource owner** and **Repository access** as appropriate
+4. Grant these **Repository permissions** (minimum for full read + write):
+
+| Permission        | Access level   | Used by tools                                                                                                                              |
+| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Metadata**      | Read-only      | All tools                                                                                                                                  |
+| **Contents**      | Read and write | `github_get_file_contents`, `github_list_directory`, `github_list_commits`, `github_create_or_update_file`, `github_create_branch`         |
+| **Issues**        | Read and write | `github_list_issues`, `github_get_issue`, `github_create_issue`, `github_update_issue`, `github_add_issue_comment`                         |
+| **Pull requests** | Read and write | `github_list_pull_requests`, `github_get_pull_request`, `github_create_pull_request`, `github_merge_pull_request`, `github_add_pr_comment` |
+
+> **Read-only subset**: grant only **Read-only** access to Contents, Issues, Pull requests, and Metadata if you don't need write tools.
+
+
+```bash
+export GITHUB_TOKEN=github_pat_...
+```
+
+Or copy `.env.example` -> `.env` and fill in the token (load with `source .env`).
+
+
+### Integrating with Claude Desktop
+
+Add the server to your Claude Desktop configuration:
+
+| Platform | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+Add the `github` entry under `mcpServers`, replacing the path with the absolute path to your clone:
+
+```json
+{
+  "mcpServers" : {
+    "github" : {
+      "command" : "python",
+      "args" : ["-m", "github-mcp"],
+      "env" : {
+        "GITHUB_TOKEN" : "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the github tools available int he tool picker.
+
+### Integration with Other MCP Clients
+
+Any MCP client (e.g. Cline, GitHub Copilot, or custm tools) can use this server.
+Configuration depends on your assistant, in most cases there is a `config` to change.
+
+
+## Contribution
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes with clear messages
+4. Push to your fork
+5. Open a pull request
+
+
+### Live testing with MCP Inspector (requires a real token)
+
+```bash
+GITHUB_TOKEN=... 
+npx @modelcontextprotocol/inspector 
+uv run github-mcp
+```
+
+Then call `github_search_repositories` (q=`"mcp language:python"`) or `github_get_repo` (owner=`"modelcontextprotocol"`, repo=`"python-sdk"`) to verify auth,
+pagination, and formatting end-to-end.
+
+
+## Upcoming Features
+
+- **Projects v2**: Requires GitHub's GraphQL API (`/graphql`). Add a `graphql_client.py` alongside `client.py` and a new `tools/projects.py` module.
+- **Actions**: Also REST-based but with many endpoints. Add `tools/actions.py` importing from `client.py`.

github_mcp-1.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "github-mcp"
+version = "v1.1.0"
+description = "Local GitHub MCP server exposing GitHub REST API via FastMCP stdio transport"
+requires-python = ">=3.12"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [ { name = "Lucas Waetzig", email = "development@waetzig.net" } ]
+keywords = ["github", "mcp", "fastmcp", "stdio", "rest api", "search"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx (>=0.28.1,<0.29.0)",
+    "pydantic (>=2.13.4,<3.0.0)",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=4.0.0",
+    "ruff (>=0.15.12,<0.16.0)",
+    "mypy (>=2.0.0,<3.0.0)",
+]
+docs = [
+    "sphinx (>=9.1.0,<10.0.0)",
+    "sphinx-rtd-theme (>=3.1.0,<4.0.0)"
+]
+
+[project.urls]
+Homepage = "https://github.com/LWaetzig/github-mcp"
+Repository = "https://github.com/LWaetzig/github-mcp"
+Issues = "https://github.com/LWaetzig/github-mcp/issues"
+Documentation = "https://personal-public-packages.gitlab.io/github-mcp"
+
+[project.scripts]
+github-query-mcp = "github_mcp.server:main"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+addopts = "--cov=src --cov-report=term-missing --cov-fail-under=90"
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.mypy]
+python_version = "3.12"
+mypy_path = "src"
+files = ["src", "tests"]
+pretty = true
+show_error_codes = true
+warn_unused_configs = true
+check_untyped_defs = true
+ignore_missing_imports = true

github_mcp-1.1.0/src/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-1.1.0/src/github_mcp/app.py

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

github_mcp-1.1.0/src/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}"