mcp-github-crunchtools 1.0.1__py3-none-any.whl

mcp_github_crunchtools/__init__.py

@@ -0,0 +1,58 @@
+"""MCP GitHub CrunchTools - Secure MCP server for GitHub.
+
+A security-focused MCP server for GitHub issues, pull requests (diffs and
+CI checks), repository files, and code/issue search. Works with github.com
+and GitHub Enterprise Server.
+
+Usage:
+    mcp-github-crunchtools
+
+    python -m mcp_github_crunchtools
+
+    uvx mcp-github-crunchtools
+
+Environment Variables:
+    GITHUB_TOKEN: Required. GitHub Personal Access Token.
+    GITHUB_API_URL: Optional. API base URL (default: https://api.github.com).
+    GITHUB_DEFAULT_ORG: Optional. Default owner when a tool omits owner.
+
+Example with Claude Code:
+    claude mcp add mcp-github-crunchtools \\
+        --env GITHUB_TOKEN=your_token_here \\
+        -- uvx mcp-github-crunchtools
+"""
+
+import argparse
+
+from .server import mcp
+
+__version__ = "1.0.1"
+__all__ = ["main", "mcp"]
+
+
+def main() -> None:
+    """Main entry point for the MCP server."""
+    parser = argparse.ArgumentParser(description="MCP server for GitHub")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="Transport protocol (default: stdio)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind to for HTTP transports (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8016,
+        help="Port to bind to for HTTP transports (default: 8016)",
+    )
+    args = parser.parse_args()
+
+    if args.transport == "stdio":
+        mcp.run()
+    else:
+        mcp.run(transport=args.transport, host=args.host, port=args.port)

mcp_github_crunchtools/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m mcp_github_crunchtools."""
+
+from . import main
+
+if __name__ == "__main__":
+    main()

mcp_github_crunchtools/client.py

@@ -0,0 +1,271 @@
+"""GitHub API client with security hardening.
+
+This module provides a secure async HTTP client for the GitHub REST API.
+All requests go through this client to ensure consistent security practices.
+"""
+
+import logging
+import re
+from typing import Any
+
+import httpx
+
+from .config import get_config
+from .errors import (
+    GitHubApiError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+MAX_RESPONSE_SIZE = 10 * 1024 * 1024
+REQUEST_TIMEOUT = 30.0
+GITHUB_API_VERSION = "2022-11-28"
+DEFAULT_ACCEPT = "application/vnd.github+json"
+
+_LINK_ENTRY = re.compile(r'<(?P<url>[^>]+)>;\s*rel="(?P<rel>[^"]+)"')
+_PAGE_PARAM = re.compile(r"[?&]page=(\d+)")
+
+
+class GitHubClient:
+    """Async HTTP client for the GitHub REST API.
+
+    Security features:
+    - Configurable base URL with HTTPS enforcement (supports GHES)
+    - Token passed via Authorization: Bearer header (not URL)
+    - TLS certificate validation (httpx default)
+    - Request timeout enforcement
+    - Response size limits
+    - Pagination support via the GitHub Link header
+    """
+
+    def __init__(self) -> None:
+        """Initialize the GitHub client."""
+        self._config = get_config()
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the async HTTP client."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self._config.api_base_url,
+                headers={
+                    "Authorization": f"Bearer {self._config.token}",
+                    "Accept": DEFAULT_ACCEPT,
+                    "X-GitHub-Api-Version": GITHUB_API_VERSION,
+                },
+                timeout=httpx.Timeout(REQUEST_TIMEOUT),
+                verify=self._config.ssl_verify,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        accept: str | None = None,
+    ) -> dict[str, Any]:
+        """Make an API request with error handling.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            path: API path (e.g., /repos/owner/repo/issues)
+            params: Query parameters
+            json_data: JSON body data
+            accept: Optional override for the Accept header (e.g., for diffs)
+
+        Returns:
+            API response data with pagination info if applicable. Non-JSON
+            responses (such as raw diffs) are returned as {"content": text}.
+
+        Raises:
+            GitHubApiError: On API errors, including non-rate-limit 403s
+                (e.g. re-running a workflow run older than 30 days), whose
+                original GitHub message is preserved so callers can tell a
+                real scope problem from other 403 conditions
+            RateLimitError: On rate limiting
+            PermissionDeniedError: On 401 authorization failures
+            NotFoundError: When the resource does not exist
+        """
+        client = await self._get_client()
+
+        logger.debug("API request: %s %s", method, path)
+
+        headers = {"Accept": accept} if accept else None
+
+        try:
+            response = await client.request(
+                method=method,
+                url=path,
+                params=params,
+                json=json_data,
+                headers=headers,
+            )
+        except httpx.TimeoutException as e:
+            raise GitHubApiError(0, f"Request timeout: {e}") from e
+        except httpx.RequestError as e:
+            raise GitHubApiError(0, f"Request failed: {e}") from e
+
+        content_length = response.headers.get("content-length")
+        if content_length and int(content_length) > MAX_RESPONSE_SIZE:
+            raise GitHubApiError(0, "Response too large")
+
+        if not response.is_success:
+            self._handle_error_response(response)
+
+        if response.status_code == 204:
+            return {"status": "deleted"}
+
+        content_type = response.headers.get("content-type", "")
+        if "application/json" not in content_type:
+            return {"content": response.text}
+
+        try:
+            parsed = response.json()
+        except ValueError as e:
+            raise GitHubApiError(
+                response.status_code, f"Invalid JSON response: {e}"
+            ) from e
+
+        if isinstance(parsed, list):
+            return self._wrap_list_response(parsed, response)
+
+        if isinstance(parsed, dict):
+            return parsed
+        return {"data": parsed}
+
+    def _wrap_list_response(
+        self, items: list[Any], response: httpx.Response
+    ) -> dict[str, Any]:
+        """Wrap a list response with pagination parsed from the Link header.
+
+        GitHub signals pagination through the RFC 5988 Link header rather than
+        x-total-* headers. Each rel (next, prev, first, last) maps to a URL; we
+        surface both the URLs and their page numbers.
+        """
+        wrapped: dict[str, Any] = {"items": items}
+
+        pagination: dict[str, Any] = {}
+        link_header = response.headers.get("link")
+        if link_header:
+            for match in _LINK_ENTRY.finditer(link_header):
+                rel = match.group("rel")
+                url = match.group("url")
+                pagination[f"{rel}_url"] = url
+                page_match = _PAGE_PARAM.search(url)
+                if page_match:
+                    pagination[f"{rel}_page"] = int(page_match.group(1))
+
+        if pagination:
+            wrapped["pagination"] = pagination
+
+        return wrapped
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        """Handle error responses from the API.
+
+        GitHub signals primary rate limiting with HTTP 403 (not 429) plus
+        ``x-ratelimit-remaining: 0``; both cases map to RateLimitError.
+
+        Args:
+            response: HTTP response
+
+        Raises:
+            Various UserError subclasses based on error type
+        """
+        status_code = response.status_code
+
+        error_msg: str = "Unknown error"
+        try:
+            error_body = response.json()
+            if isinstance(error_body, dict):
+                raw_msg = error_body.get("message", error_body.get("error"))
+                if isinstance(raw_msg, (dict, str, int, float)):
+                    error_msg = str(raw_msg)
+            else:
+                error_msg = str(error_body)
+        except ValueError:
+            error_msg = response.text[:200] if response.text else "Unknown error"
+
+        rate_remaining = response.headers.get("x-ratelimit-remaining")
+
+        if status_code == 429 or (status_code == 403 and rate_remaining == "0"):
+            retry_after = response.headers.get("retry-after")
+            if retry_after is None:
+                retry_after = response.headers.get("x-ratelimit-reset")
+            raise RateLimitError(int(retry_after) if retry_after else None)
+
+        if status_code == 401:
+            raise PermissionDeniedError("Valid token with required scopes")
+        if status_code == 403:
+            raise GitHubApiError(status_code, error_msg)
+        if status_code == 404:
+            raise NotFoundError(error_msg)
+
+        raise GitHubApiError(status_code, error_msg)
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        accept: str | None = None,
+    ) -> dict[str, Any]:
+        """Make a GET request.
+
+        Args:
+            path: API path
+            params: Query parameters
+            accept: Optional Accept header override (e.g.,
+                "application/vnd.github.diff" to retrieve a diff)
+        """
+        return await self._request("GET", path, params=params, accept=accept)
+
+    async def post(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make a POST request."""
+        return await self._request("POST", path, params=params, json_data=json_data)
+
+    async def put(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make a PUT request."""
+        return await self._request("PUT", path, json_data=json_data)
+
+    async def patch(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make a PATCH request."""
+        return await self._request("PATCH", path, json_data=json_data)
+
+    async def delete(self, path: str) -> dict[str, Any]:
+        """Make a DELETE request."""
+        return await self._request("DELETE", path)
+
+
+_client: GitHubClient | None = None
+
+
+def get_client() -> GitHubClient:
+    """Get the global GitHub client instance."""
+    global _client
+    if _client is None:
+        _client = GitHubClient()
+    return _client

mcp_github_crunchtools/config.py

@@ -0,0 +1,140 @@
+"""Secure configuration handling.
+
+This module handles all configuration including the sensitive API token.
+The token is stored as a SecretStr to prevent accidental logging.
+"""
+
+import logging
+import os
+from urllib.parse import urlparse
+
+from pydantic import SecretStr
+
+from .errors import ConfigurationError
+
+logger = logging.getLogger(__name__)
+
+
+class Config:
+    """Secure configuration handling.
+
+    The API token is stored as a SecretStr and should only be accessed
+    via the token property when actually needed for API calls.
+    """
+
+    def __init__(self) -> None:
+        """Initialize configuration from environment variables.
+
+        Raises:
+            ConfigurationError: If required environment variables are missing or invalid.
+        """
+        token = os.environ.get("GITHUB_TOKEN")
+        if not token:
+            raise ConfigurationError(
+                "GITHUB_TOKEN environment variable required. "
+                "Create a Personal Access Token at "
+                "https://github.com/settings/tokens"
+            )
+
+        self._token = SecretStr(token)
+
+        api_url = os.environ.get("GITHUB_API_URL", "https://api.github.com").rstrip("/")
+
+        parsed = urlparse(api_url)
+        if not parsed.scheme or not parsed.netloc:
+            raise ConfigurationError(
+                "Invalid GITHUB_API_URL: must be a valid URL (e.g. https://api.github.com)"
+            )
+
+        if parsed.scheme != "https" and parsed.hostname not in (
+            "localhost",
+            "127.0.0.1",
+            "::1",
+        ):
+            raise ConfigurationError(
+                "GITHUB_API_URL must use HTTPS for non-localhost URLs"
+            )
+
+        self._api_base_url = api_url
+
+        self._default_org = os.environ.get("GITHUB_DEFAULT_ORG") or None
+
+        ssl_disabled = os.environ.get("GITHUB_SSL_VERIFY", "true").lower() in (
+            "false",
+            "0",
+            "no",
+        )
+        ssl_cert_file = os.environ.get("SSL_CERT_FILE")
+
+        match (ssl_disabled, ssl_cert_file):
+            case (True, _):
+                self._ssl_verify: bool | str = False
+                logger.warning("SSL verification disabled via GITHUB_SSL_VERIFY")
+            case (False, str(cert_path)):
+                self._ssl_verify = cert_path
+                logger.info("Using custom CA bundle: %s", cert_path)
+            case _:
+                self._ssl_verify = True
+
+        logger.info(
+            "Configuration loaded successfully (GitHub API: %s)", self._api_base_url
+        )
+
+    @property
+    def token(self) -> str:
+        """Get token value for API calls.
+
+        Use sparingly - only when making actual API calls.
+        """
+        return self._token.get_secret_value()
+
+    @property
+    def api_base_url(self) -> str:
+        """GitHub REST API base URL.
+
+        Derived from GITHUB_API_URL environment variable
+        (default: https://api.github.com).
+        """
+        return self._api_base_url
+
+    @property
+    def default_org(self) -> str | None:
+        """Default owner/org used when a tool is called without an owner."""
+        return self._default_org
+
+    @property
+    def ssl_verify(self) -> bool | str:
+        """SSL verification setting.
+
+        Returns True, False, or a path to a CA bundle file.
+        """
+        return self._ssl_verify
+
+    def __repr__(self) -> str:
+        """Safe repr that never exposes the token."""
+        return f"Config(api_base_url={self._api_base_url}, token=***)"
+
+    def __str__(self) -> str:
+        """Safe str that never exposes the token."""
+        return f"Config(api_base_url={self._api_base_url}, token=***)"
+
+
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Get the global configuration instance.
+
+    This function lazily initializes the configuration on first call.
+    Subsequent calls return the same instance.
+
+    Returns:
+        The global Config instance.
+
+    Raises:
+        ConfigurationError: If configuration is invalid.
+    """
+    global _config
+    if _config is None:
+        _config = Config()
+    return _config

mcp_github_crunchtools/errors.py

@@ -0,0 +1,65 @@
+"""Safe error types that can be shown to users.
+
+This module defines exception classes that are safe to expose to MCP clients.
+Internal errors should be caught and converted to UserError before propagating.
+"""
+
+import os
+
+SAFE_ID_MAX_LENGTH = 40
+
+
+class UserError(Exception):
+    """Base class for safe errors that can be shown to users.
+
+    All error messages in UserError subclasses must be carefully crafted
+    to avoid leaking sensitive information like API tokens or internal paths.
+    """
+
+
+class ConfigurationError(UserError):
+    """Error in server configuration."""
+
+
+class GitHubApiError(UserError):
+    """Error from GitHub API.
+
+    The message is sanitized to remove any potential token references.
+    """
+
+    def __init__(self, code: int, message: str) -> None:
+        token = os.environ.get("GITHUB_TOKEN", "")
+        safe_message = message.replace(token, "***") if token else message
+        super().__init__(f"GitHub API error {code}: {safe_message}")
+
+
+class NotFoundError(UserError):
+    """Resource not found or not accessible."""
+
+    def __init__(self, identifier: str) -> None:
+        if len(identifier) > SAFE_ID_MAX_LENGTH:
+            safe_id = identifier[:SAFE_ID_MAX_LENGTH] + "..."
+        else:
+            safe_id = identifier
+        super().__init__(f"Not found or not accessible: {safe_id}")
+
+
+class PermissionDeniedError(UserError):
+    """Permission denied for the requested operation."""
+
+    def __init__(self, required_scope: str) -> None:
+        super().__init__(f"Permission denied. Required scope: {required_scope}")
+
+
+class RateLimitError(UserError):
+    """Rate limit exceeded."""
+
+    def __init__(self, retry_after: int | None = None) -> None:
+        msg = "Rate limit exceeded."
+        if retry_after:
+            msg += f" Retry after {retry_after} seconds."
+        super().__init__(msg)
+
+
+class ValidationError(UserError):
+    """Input validation error."""