jaimenbell-github-mcp 0.1.0__py3-none-any.whl

github_mcp/client.py

@@ -0,0 +1,155 @@
+"""Thin sync httpx wrapper around api.github.com.
+
+One function per HTTP verb used by the tool groups (get/post/patch). Auth
+header injection when a token is present; degrades to GitHub's unauthenticated
+60 req/hr tier otherwise. GitHub's 403 primary rate-limit response (hourly
+quota, X-RateLimit-Reset) and secondary rate-limit response (abuse-detection
+heuristics, Retry-After) both surface as a typed `rate_limited` error; any
+other 4xx/5xx surfaces as a typed `github_api_error` -- never a raw
+exception/crash. A dedicated httpx.Client is created per call so tests can
+respx-mock deterministically without managing a shared client lifecycle
+across the process.
+"""
+from __future__ import annotations
+
+import json as json_module
+from typing import Any
+
+import httpx
+
+from . import config
+
+DEFAULT_TIMEOUT_S = 10.0
+
+
+def _headers() -> dict:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "github-mcp",
+    }
+    token = config.get_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _rate_limit_error(tool: str, response: httpx.Response) -> dict:
+    reset_header = response.headers.get("X-RateLimit-Reset")
+    remaining = response.headers.get("X-RateLimit-Remaining")
+    retry_after = response.headers.get("Retry-After")
+    if reset_header:
+        message = f"GitHub API rate limit exceeded. Resets at unix time {reset_header}."
+    elif retry_after:
+        # GitHub's secondary rate limit: no X-RateLimit-* headers, just Retry-After.
+        message = f"GitHub API secondary rate limit exceeded. Retry after {retry_after}s."
+    else:
+        message = "GitHub API rate limit exceeded."
+    return {
+        "ok": False,
+        "error": {
+            "type": "rate_limited",
+            "message": message,
+            "tool": tool,
+            "status_code": response.status_code,
+            "reset_time": int(reset_header) if reset_header and reset_header.isdigit() else None,
+            "remaining": int(remaining) if remaining and remaining.isdigit() else None,
+            "retry_after_s": int(retry_after) if retry_after and retry_after.isdigit() else None,
+        },
+    }
+
+
+def _api_error(tool: str, response: httpx.Response) -> dict:
+    try:
+        body = response.json()
+        message = body.get("message", response.text)
+    except (json_module.JSONDecodeError, ValueError):
+        message = response.text or f"HTTP {response.status_code}"
+    return {
+        "ok": False,
+        "error": {
+            "type": "github_api_error",
+            "message": message,
+            "tool": tool,
+            "status_code": response.status_code,
+        },
+    }
+
+
+def _is_rate_limit_response(response: httpx.Response) -> bool:
+    """True for GitHub's primary rate limit (403 + X-RateLimit-Remaining: 0)
+    and its secondary rate limit (403 + Retry-After, no X-RateLimit-Remaining
+    -- triggered by abuse-detection/concurrency/rapid-write heuristics rather
+    than the hourly quota)."""
+    if response.status_code != 403:
+        return False
+    if response.headers.get("X-RateLimit-Remaining") == "0":
+        return True
+    return "Retry-After" in response.headers
+
+
+def _handle_response(tool: str, response: httpx.Response) -> dict:
+    if _is_rate_limit_response(response):
+        return _rate_limit_error(tool, response)
+    if response.status_code >= 400:
+        return _api_error(tool, response)
+    try:
+        data = response.json() if response.content else {}
+    except (json_module.JSONDecodeError, ValueError) as exc:
+        return {
+            "ok": False,
+            "error": {
+                "type": "decode_error",
+                "message": f"GitHub returned non-JSON content: {exc}",
+                "tool": tool,
+                "status_code": response.status_code,
+            },
+        }
+    return {"ok": True, "data": data, "status_code": response.status_code}
+
+
+def request(
+    tool: str,
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json: dict[str, Any] | None = None,
+) -> dict:
+    """Issue one request to api.github.com and return a structured result:
+    {"ok": True, "data": ..., "status_code": ...} on success, or
+    {"ok": False, "error": {...}} on any 4xx/5xx/decode failure. Network-level
+    exceptions (timeout, connection refused, DNS failure) AND malformed-URL
+    errors (e.g. a caller-supplied owner/repo/path containing characters that
+    make the assembled URL invalid) are also caught and surfaced as a typed
+    error rather than propagating -- the tool caller always gets a dict back,
+    never an exception. `httpx.InvalidURL` does not subclass `httpx.HTTPError`
+    (it's raised during URL construction, before any network I/O), so it is
+    listed explicitly -- omitting it would let a bad path/owner/repo value
+    crash the call instead of returning a clean error."""
+    url = f"{config.GITHUB_API_BASE}{path}"
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT_S) as client:
+            response = client.request(method, url, headers=_headers(), params=params, json=json)
+    except (httpx.HTTPError, httpx.InvalidURL) as exc:
+        return {
+            "ok": False,
+            "error": {
+                "type": "network_error",
+                "message": str(exc),
+                "tool": tool,
+            },
+        }
+    return _handle_response(tool, response)
+
+
+def get(tool: str, path: str, *, params: dict[str, Any] | None = None) -> dict:
+    return request(tool, "GET", path, params=params)
+
+
+def post(tool: str, path: str, *, json: dict[str, Any] | None = None) -> dict:
+    return request(tool, "POST", path, json=json)
+
+
+def patch(tool: str, path: str, *, json: dict[str, Any] | None = None) -> dict:
+    return request(tool, "PATCH", path, json=json)

github_mcp/config.py

@@ -0,0 +1,127 @@
+"""Config/safety layer for github-mcp.
+
+Tool-group gating + token loading + structured refusal/error payloads. This
+is the server's own defense-in-depth layer: even if a caller gets past
+harness permission prompts, the server itself refuses write actions unless
+GITHUB_MCP_ENABLE_WRITE=1 is set, and never proceeds with a write call that
+lacks a token -- mirroring desktop-mcp's config.gated pattern.
+
+Groups:
+  read  -- repo/issue/PR/file/user/commit lookups (always on, works
+           unauthenticated at GitHub's 60 req/hr tier)
+  write -- issue/PR-comment mutations (env-gated, OFF by default, requires
+           GITHUB_TOKEN)
+
+Env vars:
+  GITHUB_MCP_ENABLE_WRITE=1 -- enable the write group
+  GITHUB_TOKEN              -- fine-grained PAT; read works without it
+                               (degraded unauth rate), write requires it
+"""
+from __future__ import annotations
+
+import os
+
+GROUP_READ = "read"
+GROUP_WRITE = "write"
+
+_ENV_GATES = {
+    GROUP_WRITE: "GITHUB_MCP_ENABLE_WRITE",
+}
+
+GITHUB_API_BASE = "https://api.github.com"
+
+
+def _env_truthy(name: str) -> bool:
+    val = os.environ.get(name, "")
+    return val.strip().lower() in ("1", "true", "yes", "on")
+
+
+def group_enabled(group: str) -> bool:
+    """read is always on; write requires its env gate."""
+    if group == GROUP_READ:
+        return True
+    env_name = _ENV_GATES.get(group)
+    if env_name is None:
+        return False
+    return _env_truthy(env_name)
+
+
+def get_token() -> str | None:
+    """Fine-grained PAT from GITHUB_TOKEN, or None. Never logged; callers
+    must not include this value in any error payload or diagnostic."""
+    token = os.environ.get("GITHUB_TOKEN")
+    return token if token else None
+
+
+def policy_refusal(group: str, tool: str) -> dict:
+    """Structured refusal payload for a disabled tool group."""
+    env_name = _ENV_GATES.get(group, f"GITHUB_MCP_ENABLE_{group.upper()}")
+    return {
+        "ok": False,
+        "error": {
+            "type": "policy_refusal",
+            "message": (
+                f"Tool group '{group}' is disabled. Set {env_name}=1 in the "
+                f"server's environment to enable it."
+            ),
+            "group": group,
+            "tool": tool,
+            "required_env": env_name,
+        },
+    }
+
+
+def auth_required(tool: str) -> dict:
+    """Structured refusal payload for a write call with no GITHUB_TOKEN.
+    Write actions always require a token even when the group is enabled --
+    GitHub's write endpoints reject unauthenticated requests, so this is a
+    fast, clean local refusal instead of a round-trip 401/403."""
+    return {
+        "ok": False,
+        "error": {
+            "type": "auth_required",
+            "message": (
+                f"Tool '{tool}' requires a GitHub token. Set GITHUB_TOKEN in "
+                f"the server's environment (fine-grained PAT with the needed "
+                f"repo write scopes)."
+            ),
+            "tool": tool,
+        },
+    }
+
+
+def check_group(group: str, tool: str) -> dict | None:
+    """Gate check for a tool call. Returns a structured refusal dict if the
+    group is disabled, else None (caller proceeds)."""
+    if not group_enabled(group):
+        return policy_refusal(group, tool)
+    return None
+
+
+def check_write_preconditions(tool: str) -> dict | None:
+    """Combined gate for write tools: group must be enabled AND a token must
+    be present. Returns a structured refusal dict, else None."""
+    refusal = check_group(GROUP_WRITE, tool)
+    if refusal is not None:
+        return refusal
+    if get_token() is None:
+        return auth_required(tool)
+    return None
+
+
+def gated_write(fn):
+    """Decorator applied directly to write-group module functions so the
+    policy gate + token precondition is enforced at the source -- not just in
+    the MCP tool wrapper -- and is unit-testable without spinning up the
+    fastmcp server or hitting the network."""
+
+    def wrapper(*args, **kwargs):
+        refusal = check_write_preconditions(fn.__name__)
+        if refusal is not None:
+            return refusal
+        return fn(*args, **kwargs)
+
+    wrapper.__name__ = fn.__name__
+    wrapper.__doc__ = fn.__doc__
+    wrapper.__wrapped__ = fn
+    return wrapper

github_mcp/groups/read.py

@@ -0,0 +1,259 @@
+"""Read group: repo/issue/PR/file/user/commit lookups. Always enabled (no
+env gate) -- these work unauthenticated (GitHub's 60 req/hr tier) and are
+considered safe by default.
+
+Every function returns a plain dict ({"ok": True, ...} or a structured
+error) built from `client.get`, never raises. Base64 file-content decoding
+happens here (get_file_content) since it's read-tool-specific, not a
+generic client concern.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+
+from .. import client
+
+MAX_FILE_BYTES = 100_000
+
+
+def get_repo(owner: str, repo: str) -> dict:
+    """Metadata for a repository: description, language, stars, forks, open
+    issues, default branch, archived flag, license, last-push time."""
+    result = client.get("get_repo", f"/repos/{owner}/{repo}")
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {
+        "ok": True,
+        "full_name": d.get("full_name"),
+        "description": d.get("description"),
+        "language": d.get("language"),
+        "stargazers_count": d.get("stargazers_count"),
+        "forks_count": d.get("forks_count"),
+        "open_issues_count": d.get("open_issues_count"),
+        "default_branch": d.get("default_branch"),
+        "archived": d.get("archived"),
+        "disabled": d.get("disabled"),
+        "license": (d.get("license") or {}).get("spdx_id"),
+        "pushed_at": d.get("pushed_at"),
+        "html_url": d.get("html_url"),
+    }
+
+
+def list_issues(owner: str, repo: str, state: str = "open", limit: int = 20) -> dict:
+    """List issues (pull requests filtered out), most-recently-updated first."""
+    capped = max(1, min(limit, 50))
+    result = client.get(
+        "list_issues",
+        f"/repos/{owner}/{repo}/issues",
+        params={"state": state, "per_page": capped, "sort": "updated"},
+    )
+    if not result["ok"]:
+        return result
+    issues = [item for item in result["data"] if "pull_request" not in item]
+    return {
+        "ok": True,
+        "issues": [
+            {
+                "number": i.get("number"),
+                "title": i.get("title"),
+                "state": i.get("state"),
+                "user": (i.get("user") or {}).get("login"),
+                "labels": [lbl.get("name") for lbl in i.get("labels", [])],
+                "comments": i.get("comments"),
+                "updated_at": i.get("updated_at"),
+            }
+            for i in issues
+        ],
+    }
+
+
+def get_issue(owner: str, repo: str, issue_number: int) -> dict:
+    """Fetch a single issue's full detail (title, body, state, labels, comments)."""
+    result = client.get("get_issue", f"/repos/{owner}/{repo}/issues/{issue_number}")
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {
+        "ok": True,
+        "number": d.get("number"),
+        "title": d.get("title"),
+        "body": d.get("body"),
+        "state": d.get("state"),
+        "user": (d.get("user") or {}).get("login"),
+        "labels": [lbl.get("name") for lbl in d.get("labels", [])],
+        "comments": d.get("comments"),
+        "created_at": d.get("created_at"),
+        "updated_at": d.get("updated_at"),
+    }
+
+
+def list_pull_requests(owner: str, repo: str, state: str = "open", limit: int = 20) -> dict:
+    """List pull requests, most-recently-updated first."""
+    capped = max(1, min(limit, 50))
+    result = client.get(
+        "list_pull_requests",
+        f"/repos/{owner}/{repo}/pulls",
+        params={"state": state, "per_page": capped, "sort": "updated"},
+    )
+    if not result["ok"]:
+        return result
+    return {
+        "ok": True,
+        "pull_requests": [
+            {
+                "number": p.get("number"),
+                "title": p.get("title"),
+                "state": p.get("state"),
+                "user": (p.get("user") or {}).get("login"),
+                "draft": p.get("draft"),
+                "base": (p.get("base") or {}).get("ref"),
+                "head": (p.get("head") or {}).get("ref"),
+                "updated_at": p.get("updated_at"),
+            }
+            for p in result["data"]
+        ],
+    }
+
+
+def get_pull_request(owner: str, repo: str, pr_number: int) -> dict:
+    """Fetch a single pull request's full detail, including merge state."""
+    result = client.get("get_pull_request", f"/repos/{owner}/{repo}/pulls/{pr_number}")
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {
+        "ok": True,
+        "number": d.get("number"),
+        "title": d.get("title"),
+        "body": d.get("body"),
+        "state": d.get("state"),
+        "user": (d.get("user") or {}).get("login"),
+        "draft": d.get("draft"),
+        "mergeable": d.get("mergeable"),
+        "merged": d.get("merged"),
+        "base": (d.get("base") or {}).get("ref"),
+        "head": (d.get("head") or {}).get("ref"),
+        "updated_at": d.get("updated_at"),
+    }
+
+
+def get_file_content(owner: str, repo: str, path: str, ref: str | None = None) -> dict:
+    """Read a UTF-8 text file from a repo at a given path (base64-decoded
+    server-side). Returns a structured 'binary' marker instead of decoding
+    non-UTF-8 content. Truncates past MAX_FILE_BYTES."""
+    params = {"ref": ref} if ref else None
+    result = client.get("get_file_content", f"/repos/{owner}/{repo}/contents/{path}", params=params)
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    if isinstance(d, list):
+        return {
+            "ok": False,
+            "error": {
+                "type": "not_a_file",
+                "message": f"'{path}' is a directory, not a file.",
+                "tool": "get_file_content",
+            },
+        }
+    if d.get("encoding") != "base64":
+        return {
+            "ok": False,
+            "error": {
+                "type": "unsupported_encoding",
+                "message": f"Unsupported content encoding: {d.get('encoding')}",
+                "tool": "get_file_content",
+            },
+        }
+    raw = base64.b64decode(d.get("content", ""))
+    try:
+        text = raw.decode("utf-8")
+        truncated = False
+        if len(raw) > MAX_FILE_BYTES:
+            text = raw[:MAX_FILE_BYTES].decode("utf-8", errors="ignore")
+            truncated = True
+        return {
+            "ok": True,
+            "path": d.get("path"),
+            "size": d.get("size"),
+            "content": text,
+            "truncated": truncated,
+            "binary": False,
+        }
+    except (UnicodeDecodeError, binascii.Error):
+        return {
+            "ok": True,
+            "path": d.get("path"),
+            "size": d.get("size"),
+            "content": None,
+            "truncated": False,
+            "binary": True,
+        }
+
+
+def search_repos(query: str, limit: int = 10) -> dict:
+    """Search public repositories by keyword/qualifiers, sorted by best match.
+    Subject to GitHub's stricter search rate limit (10 req/min unauthenticated)."""
+    capped = max(1, min(limit, 25))
+    result = client.get("search_repos", "/search/repositories", params={"q": query, "per_page": capped})
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {
+        "ok": True,
+        "total_count": d.get("total_count"),
+        "items": [
+            {
+                "full_name": item.get("full_name"),
+                "description": item.get("description"),
+                "language": item.get("language"),
+                "stargazers_count": item.get("stargazers_count"),
+                "html_url": item.get("html_url"),
+            }
+            for item in d.get("items", [])
+        ],
+    }
+
+
+def get_user(username: str) -> dict:
+    """Public profile for a GitHub user or organization."""
+    result = client.get("get_user", f"/users/{username}")
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {
+        "ok": True,
+        "login": d.get("login"),
+        "name": d.get("name"),
+        "bio": d.get("bio"),
+        "company": d.get("company"),
+        "location": d.get("location"),
+        "public_repos": d.get("public_repos"),
+        "followers": d.get("followers"),
+        "type": d.get("type"),
+    }
+
+
+def list_commits(owner: str, repo: str, limit: int = 20, sha: str | None = None) -> dict:
+    """List commits on a repo's default branch (or `sha` ref), newest first."""
+    capped = max(1, min(limit, 50))
+    params = {"per_page": capped}
+    if sha:
+        params["sha"] = sha
+    result = client.get("list_commits", f"/repos/{owner}/{repo}/commits", params=params)
+    if not result["ok"]:
+        return result
+    return {
+        "ok": True,
+        "commits": [
+            {
+                "sha": c.get("sha"),
+                "message": (c.get("commit") or {}).get("message"),
+                "author": ((c.get("commit") or {}).get("author") or {}).get("name"),
+                "date": ((c.get("commit") or {}).get("author") or {}).get("date"),
+                "html_url": c.get("html_url"),
+            }
+            for c in result["data"]
+        ],
+    }

github_mcp/groups/write.py

@@ -0,0 +1,89 @@
+"""Write group: issue/PR mutations. Env-gated behind GITHUB_MCP_ENABLE_WRITE
+(OFF by default) AND requires GITHUB_TOKEN -- both preconditions enforced by
+`config.gated_write` at the source, so a disabled group or missing token
+returns a structured refusal before any network call is attempted.
+"""
+from __future__ import annotations
+
+from .. import client, config
+
+
+@config.gated_write
+def create_issue(owner: str, repo: str, title: str, body: str | None = None, labels: list[str] | None = None) -> dict:
+    """Open a new issue on a repository."""
+    payload: dict = {"title": title}
+    if body is not None:
+        payload["body"] = body
+    if labels:
+        payload["labels"] = labels
+    result = client.post("create_issue", f"/repos/{owner}/{repo}/issues", json=payload)
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {"ok": True, "number": d.get("number"), "html_url": d.get("html_url"), "state": d.get("state")}
+
+
+@config.gated_write
+def comment_on_issue(owner: str, repo: str, issue_number: int, body: str) -> dict:
+    """Post a comment on an issue or pull request (PRs are issues in GitHub's
+    comments API)."""
+    result = client.post(
+        "comment_on_issue",
+        f"/repos/{owner}/{repo}/issues/{issue_number}/comments",
+        json={"body": body},
+    )
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {"ok": True, "id": d.get("id"), "html_url": d.get("html_url")}
+
+
+@config.gated_write
+def update_issue_state(owner: str, repo: str, issue_number: int, state: str) -> dict:
+    """Set an issue's state to 'open' or 'closed'."""
+    if state not in ("open", "closed"):
+        return {
+            "ok": False,
+            "error": {
+                "type": "invalid_input",
+                "message": f"state must be 'open' or 'closed', got '{state}'",
+                "tool": "update_issue_state",
+            },
+        }
+    result = client.patch(
+        "update_issue_state",
+        f"/repos/{owner}/{repo}/issues/{issue_number}",
+        json={"state": state},
+    )
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {"ok": True, "number": d.get("number"), "state": d.get("state")}
+
+
+@config.gated_write
+def add_labels(owner: str, repo: str, issue_number: int, labels: list[str]) -> dict:
+    """Add one or more labels to an issue or pull request."""
+    result = client.post(
+        "add_labels",
+        f"/repos/{owner}/{repo}/issues/{issue_number}/labels",
+        json={"labels": labels},
+    )
+    if not result["ok"]:
+        return result
+    return {"ok": True, "labels": [lbl.get("name") for lbl in result["data"]]}
+
+
+@config.gated_write
+def create_pr_review_comment(owner: str, repo: str, pr_number: int, body: str, commit_id: str, path: str, line: int) -> dict:
+    """Create a review comment on a specific line of a pull request's diff."""
+    payload = {"body": body, "commit_id": commit_id, "path": path, "line": line}
+    result = client.post(
+        "create_pr_review_comment",
+        f"/repos/{owner}/{repo}/pulls/{pr_number}/comments",
+        json=payload,
+    )
+    if not result["ok"]:
+        return result
+    d = result["data"]
+    return {"ok": True, "id": d.get("id"), "html_url": d.get("html_url")}

github_mcp/server.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""github-mcp -- public read+write reference MCP server over the GitHub
+REST API (FastMCP).
+
+Reference portfolio implementation, NOT the official GitHub MCP server --
+see README's "what this is / is not" section.
+
+Tool groups (see github_mcp.config): read (always on, works unauthenticated
+at GitHub's 60 req/hr tier), write (env-gated GITHUB_MCP_ENABLE_WRITE, OFF
+by default, also requires GITHUB_TOKEN). Every write-group tool enforces its
+own gate + token precondition at the function level
+(github_mcp.config.gated_write), so this file is thin wiring -- the safety
+logic lives in config.py and is unit-tested independently of the MCP
+transport.
+
+Run: python run_server.py
+"""
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+from .groups import read, write
+
+SERVER_NAME = "github-mcp"
+
+mcp = FastMCP(SERVER_NAME)
+
+
+# ---- read (always on) --------------------------------------------------
+
+@mcp.tool(name="get_repo", description="Get metadata for a repository: description, language, stars, forks, open issues, default branch, archived flag, license, last-push time.")
+async def get_repo_tool(owner: str, repo: str) -> dict:
+    return read.get_repo(owner, repo)
+
+
+@mcp.tool(name="list_issues", description="List issues for a repository (pull requests filtered out), most-recently-updated first.")
+async def list_issues_tool(owner: str, repo: str, state: str = "open", limit: int = 20) -> dict:
+    return read.list_issues(owner, repo, state=state, limit=limit)
+
+
+@mcp.tool(name="get_issue", description="Fetch a single issue's full detail: title, body, state, labels, comment count.")
+async def get_issue_tool(owner: str, repo: str, issue_number: int) -> dict:
+    return read.get_issue(owner, repo, issue_number)
+
+
+@mcp.tool(name="list_pull_requests", description="List pull requests for a repository, most-recently-updated first.")
+async def list_pull_requests_tool(owner: str, repo: str, state: str = "open", limit: int = 20) -> dict:
+    return read.list_pull_requests(owner, repo, state=state, limit=limit)
+
+
+@mcp.tool(name="get_pull_request", description="Fetch a single pull request's full detail, including merge state.")
+async def get_pull_request_tool(owner: str, repo: str, pr_number: int) -> dict:
+    return read.get_pull_request(owner, repo, pr_number)
+
+
+@mcp.tool(name="get_file_content", description="Read a UTF-8 text file from a repo at a given path (base64-decoded). Reports binary files rather than decoding them.")
+async def get_file_content_tool(owner: str, repo: str, path: str, ref: str | None = None) -> dict:
+    return read.get_file_content(owner, repo, path, ref=ref)
+
+
+@mcp.tool(name="search_repos", description="Search public repositories by keyword/qualifiers, sorted by best match.")
+async def search_repos_tool(query: str, limit: int = 10) -> dict:
+    return read.search_repos(query, limit=limit)
+
+
+@mcp.tool(name="get_user", description="Get a public profile for a GitHub user or organization.")
+async def get_user_tool(username: str) -> dict:
+    return read.get_user(username)
+
+
+@mcp.tool(name="list_commits", description="List commits on a repo's default branch (or a given ref), newest first.")
+async def list_commits_tool(owner: str, repo: str, limit: int = 20, sha: str | None = None) -> dict:
+    return read.list_commits(owner, repo, limit=limit, sha=sha)
+
+
+# ---- write (env-gated: GITHUB_MCP_ENABLE_WRITE, OFF by default; requires GITHUB_TOKEN) --
+
+@mcp.tool(name="create_issue", description="Open a new issue on a repository. Requires GITHUB_MCP_ENABLE_WRITE=1 and GITHUB_TOKEN.")
+async def create_issue_tool(owner: str, repo: str, title: str, body: str | None = None, labels: list[str] | None = None) -> dict:
+    return write.create_issue(owner, repo, title, body=body, labels=labels)
+
+
+@mcp.tool(name="comment_on_issue", description="Post a comment on an issue or pull request. Requires GITHUB_MCP_ENABLE_WRITE=1 and GITHUB_TOKEN.")
+async def comment_on_issue_tool(owner: str, repo: str, issue_number: int, body: str) -> dict:
+    return write.comment_on_issue(owner, repo, issue_number, body)
+
+
+@mcp.tool(name="update_issue_state", description="Set an issue's state to 'open' or 'closed'. Requires GITHUB_MCP_ENABLE_WRITE=1 and GITHUB_TOKEN.")
+async def update_issue_state_tool(owner: str, repo: str, issue_number: int, state: str) -> dict:
+    return write.update_issue_state(owner, repo, issue_number, state)
+
+
+@mcp.tool(name="add_labels", description="Add one or more labels to an issue or pull request. Requires GITHUB_MCP_ENABLE_WRITE=1 and GITHUB_TOKEN.")
+async def add_labels_tool(owner: str, repo: str, issue_number: int, labels: list[str]) -> dict:
+    return write.add_labels(owner, repo, issue_number, labels)
+
+
+@mcp.tool(name="create_pr_review_comment", description="Create a review comment on a specific line of a pull request's diff. Requires GITHUB_MCP_ENABLE_WRITE=1 and GITHUB_TOKEN.")
+async def create_pr_review_comment_tool(owner: str, repo: str, pr_number: int, body: str, commit_id: str, path: str, line: int) -> dict:
+    return write.create_pr_review_comment(owner, repo, pr_number, body, commit_id, path, line)
+
+
+if __name__ == "__main__":
+    mcp.run()

jaimenbell_github_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: jaimenbell-github-mcp
+Version: 0.1.0
+Summary: Public read+write reference MCP server over the GitHub REST API. Env-gated tool groups (read always on, write off by default), fine-grained PAT auth that degrades to the unauthenticated tier, typed rate-limit/error payloads. Reference portfolio implementation, NOT the official GitHub MCP server.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: httpx==0.28.1
+Provides-Extra: test
+Requires-Dist: pytest==9.0.3; extra == "test"
+Requires-Dist: respx==0.23.1; extra == "test"
+Dynamic: license-file
+
+# github-mcp
+
+A public read+write MCP server over the GitHub REST API -- built to the
+[desktop-mcp](https://github.com)/rag-mcp/mcp-factory standard (own
+pyproject, fastmcp server, honest README, real test suite). Env-gated tool
+groups, **write disabled by default**.
+
+## What this is / is not
+
+This is a **reference portfolio implementation** demonstrating a hardened
+read+write MCP server pattern over a real external SaaS API (GitHub) --
+env-gated tool groups, typed error/rate-limit handling, auth that degrades
+gracefully, a real test suite. It exists to show, concretely, "I build
+read/write MCP servers over external APIs" with a link a client can click.
+
+**It is NOT the official GitHub MCP server.** It does not aim for parity
+with GitHub's own MCP offering (GraphQL, Actions, webhooks, GitHub Apps are
+all out of scope -- see below). It started life as a factory-scaffolded
+read-only demo ([mcp-factory](https://github.com)'s
+`generated/github_read_server.py`) and was hand-hardened into this
+standalone read+write server -- the scaffold-then-harden path is itself part
+of the story this repo tells.
+
+## Tool groups
+
+| Group | Tools | Default state |
+|---|---|---|
+| `read` | `get_repo`, `list_issues`, `get_issue`, `list_pull_requests`, `get_pull_request`, `get_file_content`, `search_repos`, `get_user`, `list_commits` | always on, works unauthenticated (GitHub's 60 req/hr tier) |
+| `write` | `create_issue`, `comment_on_issue`, `update_issue_state`, `add_labels`, `create_pr_review_comment` | env-gated, **OFF by default** -- requires `GITHUB_MCP_ENABLE_WRITE=1` **and** `GITHUB_TOKEN` |
+
+A disabled write call returns a structured `policy_refusal` error (never a
+silent no-op, never a crash). A write call with the group enabled but no
+token returns a structured `auth_required` error -- the group gate and the
+token precondition are checked independently, both before any network call.
+
+## Write-safety-off-by-default
+
+This is defense-in-depth, mirroring desktop-mcp's `input` group: harness-level
+permission prompts are the first gate, but the server itself refuses every
+write tool unless its own environment explicitly opts in with
+`GITHUB_MCP_ENABLE_WRITE=1`, and even then refuses without a `GITHUB_TOKEN`.
+A misconfigured or overly-permissive MCP host cannot turn on GitHub mutations
+this process wasn't deliberately configured to allow. The registration this
+repo ships with (see `~/.claude.json`'s `github-mcp` entry) has the write
+group **absent from env** -- enabling it is a deliberate per-registration
+operator choice, not a code change.
+
+## Honest-capabilities table
+
+Every claim below maps to the file that implements it and the test(s) that
+verify it -- no capability is asserted without a corresponding implementation
+and test.
+
+| Claim | Implementation | Verified by |
+|---|---|---|
+| Repo metadata (stars, language, license, default branch, archived flag...) | `github_mcp/groups/read.py::get_repo` | `tests/test_read.py::TestGetRepo`, live: `tests/test_live_smoke.py::test_live_get_repo_real_json` |
+| List / fetch issues (PRs filtered from list) | `github_mcp/groups/read.py::list_issues`, `get_issue` | `tests/test_read.py::TestListIssues`, `TestGetIssue` |
+| List / fetch pull requests | `github_mcp/groups/read.py::list_pull_requests`, `get_pull_request` | `tests/test_read.py::TestListPullRequests`, `TestGetPullRequest` |
+| Read a repo file's content (base64-decoded, binary detected not decoded) | `github_mcp/groups/read.py::get_file_content` | `tests/test_read.py::TestGetFileContent` |
+| Search public repositories | `github_mcp/groups/read.py::search_repos` | `tests/test_read.py::TestSearchRepos` |
+| Public user/org profile | `github_mcp/groups/read.py::get_user` | `tests/test_read.py::TestGetUser` |
+| List commits on a branch/ref | `github_mcp/groups/read.py::list_commits` | `tests/test_read.py::TestListCommits` |
+| Open an issue | `github_mcp/groups/write.py::create_issue` | `tests/test_write.py::TestCreateIssue` |
+| Comment on an issue/PR | `github_mcp/groups/write.py::comment_on_issue` | `tests/test_write.py::TestCommentOnIssue` |
+| Open/close an issue | `github_mcp/groups/write.py::update_issue_state` | `tests/test_write.py::TestUpdateIssueState` |
+| Add labels to an issue/PR | `github_mcp/groups/write.py::add_labels` | `tests/test_write.py::TestAddLabels` |
+| Create a PR review comment on a diff line | `github_mcp/groups/write.py::create_pr_review_comment` | `tests/test_write.py::TestCreatePrReviewComment` |
+| Write group OFF by default, structured refusal when disabled | `github_mcp/config.py::group_enabled`, `gated_write` | `tests/test_config.py::TestGroupEnabled`, `tests/test_write.py::TestGateDisabledByDefault` |
+| Write tools require a token even when the group is enabled | `github_mcp/config.py::check_write_preconditions` | `tests/test_config.py::TestCheckWritePreconditions`, `tests/test_write.py::TestAuthRequiredWhenGroupEnabled` |
+| Fine-grained PAT auth, degrades to unauthenticated tier when absent | `github_mcp/client.py::_headers` | `tests/test_client.py::TestAuthHeaderInjection`, `tests/test_read.py::TestUnauthDegrade` |
+| GitHub primary rate-limit (403 + `X-RateLimit-Reset`) and secondary rate-limit (403 + `Retry-After`, no `X-RateLimit-Remaining`) both surface as a typed error with reset/retry time, never a crash | `github_mcp/client.py::_rate_limit_error`, `_is_rate_limit_response` | `tests/test_client.py::TestRateLimitError`, `tests/test_client.py::TestRateLimitError::test_secondary_rate_limit_no_ratelimit_headers_retry_after_only`, `tests/test_read.py::TestUnauthDegrade::test_get_repo_rate_limited_without_token_is_typed` |
+| Malformed owner/repo/path (control chars etc.) that would raise `httpx.InvalidURL` surfaces as a typed error, never an uncaught exception | `github_mcp/client.py::request` | `tests/test_client.py::TestNetworkError::test_malformed_path_raises_invalid_url_caught_as_network_error` |
+| Generic 4xx/5xx surfaces as a typed error, never a crash | `github_mcp/client.py::_api_error` | `tests/test_client.py::TestApiError` |
+| Non-JSON / malformed responses and network failures surface as typed errors | `github_mcp/client.py::_handle_response`, `request` | `tests/test_client.py::TestDecodeError`, `TestNetworkError` |
+
+## Limitations (read before relying on this)
+
+- **REST v1 only.** No GraphQL API coverage.
+- **No webhooks / GitHub App auth.** Fine-grained PAT only.
+- **No Actions/workflow-dispatch tools.** Issue/PR CRUD is the v1 write surface.
+- **Unauthenticated read is rate-limited to 60 req/hr** by GitHub itself (10
+  req/min for search) -- expect `rate_limited` errors under sustained
+  unauthenticated use; set `GITHUB_TOKEN` (even a read-only fine-grained PAT)
+  to raise this considerably.
+- **`get_file_content` truncates past 100KB** and reports (rather than
+  decodes) non-UTF-8 files.
+- **No pagination beyond a single page** for list endpoints (`limit`, capped
+  per-endpoint, is the only page-size control in v1).
+- **Not registered with the mcp-factory hub.** Ships as a standalone repo
+  (own pyproject, system Python312 install), matching the rag-mcp/desktop-mcp
+  model.
+
+## Env vars
+
+| Var | Effect | Default |
+|---|---|---|
+| `GITHUB_MCP_ENABLE_WRITE` | enable the `write` tool group | unset (off) |
+| `GITHUB_TOKEN` | fine-grained PAT; read works without it (degraded unauth rate), write requires it | unset |
+| `GITHUB_MCP_LIVE` | `1` to run the real-network smoke test (see Testing) | unset (skip) |
+
+## Usage examples
+
+```jsonc
+// A tool call from the MCP host, illustrative -- not a shell command.
+{"tool": "get_repo", "arguments": {"owner": "anthropics", "repo": "anthropic-sdk-python"}}
+// -> {"ok": true, "full_name": "anthropics/anthropic-sdk-python", "stargazers_count": 1234, ...}
+
+// write group disabled (default):
+{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
+// -> {"ok": false, "error": {"type": "policy_refusal", "group": "write", "required_env": "GITHUB_MCP_ENABLE_WRITE", ...}}
+
+// write group enabled, no token set:
+{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
+// -> {"ok": false, "error": {"type": "auth_required", "tool": "create_issue", ...}}
+```
+
+## Testing
+
+```
+# unit suite (respx-mocked api.github.com, no real network touched)
+python -m pytest -q
+
+# handshake check -- prints every registered tool name
+python scripts/list_tools.py
+
+# real-network read smoke (get_repo against a stable public repo;
+# no write smoke exists anywhere in this suite -- see safety rails above)
+GITHUB_MCP_LIVE=1 python -m pytest -q -k live_get_repo
+```
+
+## Install
+
+```
+pip install -r requirements.txt   # or: pip install .
+# deps: fastmcp==3.4.2, httpx==0.28.1
+# test-only: pytest==9.0.3, respx==0.23.1
+```
+
+## Setup / connect
+
+1. `pip install -r requirements.txt` on Python 3.12+.
+2. (Optional) generate a [fine-grained PAT](https://github.com/settings/tokens?type=beta)
+   scoped to the repos you want read+write access to (Issues: read/write,
+   Pull requests: read/write, Contents: read is enough for v1). Read tools
+   work with **no token at all** -- they just run at GitHub's unauthenticated
+   60 req/hr tier.
+3. Add to your MCP host config (e.g. `~/.claude.json`):
+
+```jsonc
+{
+  "mcpServers": {
+    "github-mcp": {
+      "command": "C:\\Users\\jaime\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
+      "args": ["C:\\Users\\jaime\\projects\\github-mcp\\run_server.py"],
+      "env": {
+        "GITHUB_TOKEN": "your-fine-grained-pat-here"
+        // GITHUB_MCP_ENABLE_WRITE intentionally absent -- write stays off
+        // until you deliberately opt in per-deployment.
+      }
+    }
+  }
+}
+```
+
+4. To enable write tools for a given deployment, add
+   `"GITHUB_MCP_ENABLE_WRITE": "1"` to that entry's `env` block. This is a
+   registration-time operator decision, not a code change.
+
+Registered in `~/.claude.json` as `github-mcp` (stdio, system Python312,
+`read` group always on, `write` group absent from env -- off).
+
+<!-- MCP registry ownership marker -->
+mcp-name: io.github.jaimenbell/github-mcp

jaimenbell_github_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+github_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+github_mcp/client.py,sha256=Uk4kFyStJUq_vDa1j_KP394Zt24G1mOeEZxGb7JpLiY,5846
+github_mcp/config.py,sha256=fY1zoKnrK_cq-BSYP1cQHN3dAJRHiRXDSU0hzZeRbx8,4210
+github_mcp/server.py,sha256=dwC0ZUN7j6THfQ_4FZS9GCWqF-KTAh_WJ0e294N3WoY,5173
+github_mcp/groups/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+github_mcp/groups/read.py,sha256=pmZ_-gFlykAp4paOAY01hrRavqaC7XdKz7XMiegmLoQ,9007
+github_mcp/groups/write.py,sha256=sDAlx4eFXQR9HhamnMXU20I4_Bxmmv3BUezQnUudDGk,3262
+jaimenbell_github_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=X9AtXBdJheXRglho9cH4FH2eK7RwIz0ZJYcyX0iMQ1E,1068
+jaimenbell_github_mcp-0.1.0.dist-info/METADATA,sha256=RPKCId-1b22demfZHe658TtJ-U0Zmhv-qJDpTUjn86M,10902
+jaimenbell_github_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+jaimenbell_github_mcp-0.1.0.dist-info/top_level.txt,sha256=Oz7KcY8SwRmG0rRos2vB8LycqcG5vapSkveK8aqQi0Q,11
+jaimenbell_github_mcp-0.1.0.dist-info/RECORD,,

jaimenbell_github_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jaimenbell_github_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaimen Bell
+
+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.

jaimenbell_github_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+github_mcp