workos-github-mcp-server 1.0.0__py3-none-any.whl

github_mcp_server/__init__.py

@@ -0,0 +1,26 @@
+"""
+GitHub MCP Server — Model Context Protocol server for GitHub operations.
+
+An independent, generalized MCP server that can connect to any AI agent
+supporting the Model Context Protocol. Not tied to any specific project.
+
+Quick start:
+    pip install workos-github-mcp-server
+    GITHUB_TOKEN=ghp_... github-mcp-server
+
+Or run as a module:
+    python -m github_mcp_server
+"""
+
+__version__ = "1.0.0"
+
+from github_mcp_server.server import create_server
+
+
+def main():
+    """Entry point for the github-mcp-server CLI command."""
+    server = create_server()
+    server.run()
+
+
+__all__ = ["main", "create_server", "__version__"]

github_mcp_server/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m github_mcp_server"""
+from github_mcp_server import main
+
+main()

github_mcp_server/client.py

@@ -0,0 +1,576 @@
+"""
+Async GitHub REST API Client.
+
+Production-quality client with:
+- Persistent connection pooling (httpx.AsyncClient)
+- Automatic retry with exponential backoff (429, 5xx)
+- Rate limit handling (X-RateLimit-* / Retry-After headers)
+- Structured error types
+- Proper resource cleanup
+"""
+
+import asyncio
+import logging
+import sys
+from typing import Any, Optional
+
+import httpx
+
+logger = logging.getLogger("github_mcp_server.client")
+
+# Configure logging to stderr (required for stdio MCP transport)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+    stream=sys.stderr,
+)
+
+
+# --- Error Types ---
+
+class GitHubAPIError(Exception):
+    """Base error for GitHub API failures."""
+
+    def __init__(self, status: int, message: str = ""):
+        self.status = status
+        self.message = message
+        super().__init__(self.message)
+
+
+class GitHubAuthError(GitHubAPIError):
+    """Authentication/authorization failure (401/403)."""
+    pass
+
+
+class GitHubNotFoundError(GitHubAPIError):
+    """Resource not found (404)."""
+    pass
+
+
+class GitHubRateLimitError(GitHubAPIError):
+    """Rate limit exceeded (403 with rate-limit headers or 429)."""
+
+    def __init__(self, retry_after: int = 60):
+        self.retry_after = retry_after
+        super().__init__(429, f"Rate limited. Retry after {retry_after}s")
+
+
+class GitHubValidationError(GitHubAPIError):
+    """Validation error (422) — invalid request body."""
+    pass
+
+
+# --- Client ---
+
+class GitHubClient:
+    """Async GitHub REST API client with connection pooling and retry."""
+
+    BASE_URL = "https://api.github.com"
+    MAX_RETRIES = 3
+    BACKOFF_BASE = 1.0  # seconds
+
+    def __init__(self, token: str):
+        if not token:
+            raise GitHubAuthError(401, "GITHUB_TOKEN is required")
+        self.token = token
+
+        self._client = httpx.AsyncClient(
+            base_url=self.BASE_URL,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+            timeout=30.0,
+        )
+
+    async def close(self):
+        """Close underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs,
+    ) -> Any:
+        """Make an authenticated request with retry logic."""
+        for attempt in range(self.MAX_RETRIES):
+            try:
+                resp = await self._client.request(
+                    method, path,
+                    params=kwargs.get("params"),
+                    json=kwargs.get("json"),
+                )
+
+                # Rate limit (429 or 403 with rate-limit header)
+                if resp.status_code == 429 or (
+                    resp.status_code == 403
+                    and resp.headers.get("x-ratelimit-remaining") == "0"
+                ):
+                    retry_after = int(
+                        resp.headers.get("retry-after",
+                        resp.headers.get("x-ratelimit-reset", "60"))
+                    )
+                    # Clamp to reasonable wait
+                    retry_after = min(retry_after, 120)
+                    if attempt < self.MAX_RETRIES - 1:
+                        logger.warning(
+                            "Rate limited, retrying after %ds (attempt %d/%d)",
+                            retry_after, attempt + 1, self.MAX_RETRIES,
+                        )
+                        await asyncio.sleep(retry_after)
+                        continue
+                    raise GitHubRateLimitError(retry_after)
+
+                # Server errors — retry
+                if resp.status_code >= 500:
+                    if attempt < self.MAX_RETRIES - 1:
+                        delay = self.BACKOFF_BASE * (2 ** attempt)
+                        logger.warning(
+                            "Server error %d, retrying in %.1fs (attempt %d/%d)",
+                            resp.status_code, delay, attempt + 1, self.MAX_RETRIES,
+                        )
+                        await asyncio.sleep(delay)
+                        continue
+
+                # Auth errors
+                if resp.status_code in (401, 403):
+                    data = resp.json()
+                    raise GitHubAuthError(
+                        resp.status_code,
+                        data.get("message", "Authentication failed"),
+                    )
+
+                # Not found
+                if resp.status_code == 404:
+                    data = resp.json()
+                    raise GitHubNotFoundError(
+                        404, data.get("message", "Resource not found")
+                    )
+
+                # Validation error
+                if resp.status_code == 422:
+                    data = resp.json()
+                    raise GitHubValidationError(
+                        422, data.get("message", "Validation failed")
+                    )
+
+                # Any other error
+                if resp.status_code >= 400:
+                    data = resp.json()
+                    raise GitHubAPIError(
+                        resp.status_code,
+                        data.get("message", f"HTTP {resp.status_code}"),
+                    )
+
+                # 204 No Content
+                if resp.status_code == 204:
+                    return {}
+
+                return resp.json()
+
+            except httpx.RequestError as e:
+                if attempt < self.MAX_RETRIES - 1:
+                    delay = self.BACKOFF_BASE * (2 ** attempt)
+                    logger.warning(
+                        "Request error: %s, retrying in %.1fs", str(e), delay
+                    )
+                    await asyncio.sleep(delay)
+                    continue
+                raise GitHubAPIError(0, str(e))
+
+        raise GitHubAPIError(0, "Failed after maximum retries")
+
+    # --- Repositories ---
+
+    async def list_repos(
+        self,
+        owner: Optional[str] = None,
+        repo_type: str = "owner",
+        sort: str = "updated",
+        per_page: int = 30,
+    ) -> list[dict]:
+        """List repositories for the authenticated user or a specific owner."""
+        if owner:
+            data = await self._request(
+                "GET", f"/users/{owner}/repos",
+                params={"type": repo_type, "sort": sort, "per_page": per_page},
+            )
+        else:
+            data = await self._request(
+                "GET", "/user/repos",
+                params={"type": repo_type, "sort": sort, "per_page": per_page},
+            )
+        return [
+            {
+                "full_name": r["full_name"],
+                "description": r.get("description", ""),
+                "language": r.get("language", ""),
+                "stars": r.get("stargazers_count", 0),
+                "forks": r.get("forks_count", 0),
+                "private": r.get("private", False),
+                "url": r.get("html_url", ""),
+                "updated_at": r.get("updated_at", ""),
+            }
+            for r in data
+        ]
+
+    async def get_repo(self, owner: str, repo: str) -> dict:
+        """Get detailed information about a repository."""
+        data = await self._request("GET", f"/repos/{owner}/{repo}")
+        return {
+            "full_name": data["full_name"],
+            "description": data.get("description", ""),
+            "language": data.get("language", ""),
+            "stars": data.get("stargazers_count", 0),
+            "forks": data.get("forks_count", 0),
+            "open_issues": data.get("open_issues_count", 0),
+            "private": data.get("private", False),
+            "default_branch": data.get("default_branch", "main"),
+            "url": data.get("html_url", ""),
+            "created_at": data.get("created_at", ""),
+            "updated_at": data.get("updated_at", ""),
+            "topics": data.get("topics", []),
+        }
+
+    async def search_repos(
+        self, query: str, sort: str = "stars", per_page: int = 10
+    ) -> list[dict]:
+        """Search repositories on GitHub."""
+        data = await self._request(
+            "GET", "/search/repositories",
+            params={"q": query, "sort": sort, "per_page": per_page},
+        )
+        return [
+            {
+                "full_name": r["full_name"],
+                "description": r.get("description", ""),
+                "language": r.get("language", ""),
+                "stars": r.get("stargazers_count", 0),
+                "url": r.get("html_url", ""),
+            }
+            for r in data.get("items", [])
+        ]
+
+    # --- Issues ---
+
+    async def list_issues(
+        self,
+        owner: str,
+        repo: str,
+        state: str = "open",
+        per_page: int = 30,
+    ) -> list[dict]:
+        """List issues in a repository."""
+        data = await self._request(
+            "GET", f"/repos/{owner}/{repo}/issues",
+            params={"state": state, "per_page": per_page},
+        )
+        return [
+            {
+                "number": i["number"],
+                "title": i["title"],
+                "state": i["state"],
+                "user": i.get("user", {}).get("login", ""),
+                "labels": [l["name"] for l in i.get("labels", [])],
+                "created_at": i.get("created_at", ""),
+                "url": i.get("html_url", ""),
+            }
+            for i in data
+            if "pull_request" not in i  # Exclude PRs from issues list
+        ]
+
+    async def create_issue(
+        self,
+        owner: str,
+        repo: str,
+        title: str,
+        body: str = "",
+        labels: Optional[list[str]] = None,
+        assignees: Optional[list[str]] = None,
+    ) -> dict:
+        """Create a new issue in a repository."""
+        payload: dict[str, Any] = {"title": title}
+        if body:
+            payload["body"] = body
+        if labels:
+            payload["labels"] = labels
+        if assignees:
+            payload["assignees"] = assignees
+        data = await self._request(
+            "POST", f"/repos/{owner}/{repo}/issues", json=payload,
+        )
+        return {
+            "number": data["number"],
+            "title": data["title"],
+            "url": data.get("html_url", ""),
+        }
+
+    async def get_issue(self, owner: str, repo: str, issue_number: int) -> dict:
+        """Get details of a specific issue."""
+        data = await self._request(
+            "GET", f"/repos/{owner}/{repo}/issues/{issue_number}",
+        )
+        return {
+            "number": data["number"],
+            "title": data["title"],
+            "state": data["state"],
+            "body": data.get("body", ""),
+            "user": data.get("user", {}).get("login", ""),
+            "labels": [l["name"] for l in data.get("labels", [])],
+            "assignees": [a["login"] for a in data.get("assignees", [])],
+            "created_at": data.get("created_at", ""),
+            "updated_at": data.get("updated_at", ""),
+            "url": data.get("html_url", ""),
+        }
+
+    async def update_issue(
+        self,
+        owner: str,
+        repo: str,
+        issue_number: int,
+        title: Optional[str] = None,
+        body: Optional[str] = None,
+        state: Optional[str] = None,
+        labels: Optional[list[str]] = None,
+        assignees: Optional[list[str]] = None,
+    ) -> dict:
+        """Update an existing issue."""
+        payload: dict[str, Any] = {}
+        if title is not None:
+            payload["title"] = title
+        if body is not None:
+            payload["body"] = body
+        if state is not None:
+            payload["state"] = state
+        if labels is not None:
+            payload["labels"] = labels
+        if assignees is not None:
+            payload["assignees"] = assignees
+        data = await self._request(
+            "PATCH", f"/repos/{owner}/{repo}/issues/{issue_number}", json=payload,
+        )
+        return {
+            "number": data["number"],
+            "title": data["title"],
+            "state": data["state"],
+            "url": data.get("html_url", ""),
+        }
+
+    async def search_issues(
+        self, query: str, sort: str = "created", per_page: int = 10
+    ) -> list[dict]:
+        """Search issues and pull requests across GitHub."""
+        data = await self._request(
+            "GET", "/search/issues",
+            params={"q": query, "sort": sort, "per_page": per_page},
+        )
+        return [
+            {
+                "number": i["number"],
+                "title": i["title"],
+                "state": i["state"],
+                "repository": i.get("repository_url", "").split("/repos/")[-1],
+                "user": i.get("user", {}).get("login", ""),
+                "url": i.get("html_url", ""),
+            }
+            for i in data.get("items", [])
+        ]
+
+    # --- Pull Requests ---
+
+    async def list_prs(
+        self,
+        owner: str,
+        repo: str,
+        state: str = "open",
+        per_page: int = 30,
+    ) -> list[dict]:
+        """List pull requests in a repository."""
+        data = await self._request(
+            "GET", f"/repos/{owner}/{repo}/pulls",
+            params={"state": state, "per_page": per_page},
+        )
+        return [
+            {
+                "number": pr["number"],
+                "title": pr["title"],
+                "state": pr["state"],
+                "user": pr.get("user", {}).get("login", ""),
+                "head": pr.get("head", {}).get("ref", ""),
+                "base": pr.get("base", {}).get("ref", ""),
+                "created_at": pr.get("created_at", ""),
+                "url": pr.get("html_url", ""),
+            }
+            for pr in data
+        ]
+
+    async def get_pr(self, owner: str, repo: str, pr_number: int) -> dict:
+        """Get details of a specific pull request."""
+        data = await self._request(
+            "GET", f"/repos/{owner}/{repo}/pulls/{pr_number}",
+        )
+        return {
+            "number": data["number"],
+            "title": data["title"],
+            "state": data["state"],
+            "body": data.get("body", ""),
+            "user": data.get("user", {}).get("login", ""),
+            "head": data.get("head", {}).get("ref", ""),
+            "base": data.get("base", {}).get("ref", ""),
+            "mergeable": data.get("mergeable"),
+            "merged": data.get("merged", False),
+            "additions": data.get("additions", 0),
+            "deletions": data.get("deletions", 0),
+            "changed_files": data.get("changed_files", 0),
+            "created_at": data.get("created_at", ""),
+            "url": data.get("html_url", ""),
+        }
+
+    async def create_pr(
+        self,
+        owner: str,
+        repo: str,
+        title: str,
+        head: str,
+        base: str,
+        body: str = "",
+        draft: bool = False,
+    ) -> dict:
+        """Create a new pull request."""
+        payload: dict[str, Any] = {
+            "title": title,
+            "head": head,
+            "base": base,
+        }
+        if body:
+            payload["body"] = body
+        if draft:
+            payload["draft"] = draft
+        data = await self._request(
+            "POST", f"/repos/{owner}/{repo}/pulls", json=payload,
+        )
+        return {
+            "number": data["number"],
+            "title": data["title"],
+            "url": data.get("html_url", ""),
+        }
+
+    # --- Commits ---
+
+    async def list_commits(
+        self,
+        owner: str,
+        repo: str,
+        sha: Optional[str] = None,
+        per_page: int = 30,
+    ) -> list[dict]:
+        """List commits in a repository."""
+        params: dict[str, Any] = {"per_page": per_page}
+        if sha:
+            params["sha"] = sha
+        data = await self._request(
+            "GET", f"/repos/{owner}/{repo}/commits", params=params,
+        )
+        return [
+            {
+                "sha": c["sha"][:7],
+                "message": c.get("commit", {}).get("message", "").split("\n")[0],
+                "author": c.get("commit", {}).get("author", {}).get("name", ""),
+                "date": c.get("commit", {}).get("author", {}).get("date", ""),
+                "url": c.get("html_url", ""),
+            }
+            for c in data
+        ]
+
+    # --- Search ---
+
+    async def search_code(
+        self, query: str, per_page: int = 10
+    ) -> list[dict]:
+        """Search code across GitHub repositories."""
+        data = await self._request(
+            "GET", "/search/code",
+            params={"q": query, "per_page": per_page},
+        )
+        return [
+            {
+                "name": item.get("name", ""),
+                "path": item.get("path", ""),
+                "repository": item.get("repository", {}).get("full_name", ""),
+                "url": item.get("html_url", ""),
+            }
+            for item in data.get("items", [])
+        ]
+
+    # --- Users ---
+
+    async def get_user(self, username: Optional[str] = None) -> dict:
+        """Get user profile. If no username, returns authenticated user."""
+        path = f"/users/{username}" if username else "/user"
+        data = await self._request("GET", path)
+        return {
+            "login": data.get("login", ""),
+            "name": data.get("name", ""),
+            "bio": data.get("bio", ""),
+            "company": data.get("company", ""),
+            "location": data.get("location", ""),
+            "email": data.get("email", ""),
+            "public_repos": data.get("public_repos", 0),
+            "followers": data.get("followers", 0),
+            "following": data.get("following", 0),
+            "url": data.get("html_url", ""),
+        }
+
+    # --- Gists ---
+
+    async def list_gists(self, per_page: int = 10) -> list[dict]:
+        """List gists for the authenticated user."""
+        data = await self._request(
+            "GET", "/gists", params={"per_page": per_page},
+        )
+        return [
+            {
+                "id": g["id"],
+                "description": g.get("description", ""),
+                "public": g.get("public", True),
+                "files": list(g.get("files", {}).keys()),
+                "url": g.get("html_url", ""),
+                "created_at": g.get("created_at", ""),
+            }
+            for g in data
+        ]
+
+    async def create_gist(
+        self,
+        files: dict[str, str],
+        description: str = "",
+        public: bool = False,
+    ) -> dict:
+        """Create a new gist.
+
+        Args:
+            files: Mapping of filename to file content.
+            description: Gist description.
+            public: Whether the gist is public.
+        """
+        payload: dict[str, Any] = {
+            "files": {
+                name: {"content": content} for name, content in files.items()
+            },
+            "description": description,
+            "public": public,
+        }
+        data = await self._request("POST", "/gists", json=payload)
+        return {
+            "id": data["id"],
+            "url": data.get("html_url", ""),
+            "files": list(data.get("files", {}).keys()),
+        }

github_mcp_server/config.py

@@ -0,0 +1,54 @@
+"""
+Environment variable validation for GitHub MCP Server.
+
+Required environment variables:
+    GITHUB_TOKEN: GitHub Personal Access Token (ghp_... or github_pat_...)
+
+Optional:
+    GITHUB_LOG_LEVEL: Logging level (default: INFO)
+"""
+
+import os
+import sys
+import logging
+
+logger = logging.getLogger("github_mcp_server.config")
+
+
+class GitHubConfig:
+    """Validated GitHub configuration from environment variables."""
+
+    def __init__(self):
+        self.token: str = ""
+        self.log_level: str = "INFO"
+        self._load()
+
+    def _load(self):
+        self.token = os.environ.get("GITHUB_TOKEN", "")
+        self.log_level = os.environ.get("GITHUB_LOG_LEVEL", "INFO")
+
+    def validate(self) -> list[str]:
+        """Validate configuration. Returns list of error messages (empty = valid)."""
+        errors = []
+
+        if not self.token:
+            errors.append(
+                "GITHUB_TOKEN is required. "
+                "Create one at https://github.com/settings/tokens"
+            )
+
+        return errors
+
+    def validate_or_exit(self):
+        """Validate configuration, exit with clear error if invalid."""
+        errors = self.validate()
+        if errors:
+            print("GitHub MCP Server configuration errors:", file=sys.stderr)
+            for err in errors:
+                print(f"  ✗ {err}", file=sys.stderr)
+            print(
+                "\nSet the required environment variables and try again.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        logger.info("GitHub configuration validated successfully")