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

mcp_github_crunchtools/tools/pull_requests.py

@@ -0,0 +1,287 @@
+"""Pull request tools.
+
+Tools for listing, fetching, diffing, and checking GitHub pull requests.
+"""
+
+from typing import Any
+
+from ..client import get_client
+from ..errors import ValidationError
+from ..models import (
+    PR_STATES,
+    clamp_per_page,
+    resolve_owner,
+    validate_name,
+    validate_positive_int,
+)
+
+DIFF_ACCEPT = "application/vnd.github.diff"
+
+
+async def list_pull_requests(
+    owner: str | None,
+    repo: str,
+    state: str = "open",
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """List pull requests for a repository.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        state: Filter by state (open, closed, all)
+        per_page: Results per page (max 100)
+        page: Page number
+
+    Returns:
+        List of pull requests with pagination info
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    if state not in PR_STATES:
+        allowed = ", ".join(sorted(PR_STATES))
+        raise ValidationError(f"Invalid state. Allowed: {allowed}")
+
+    client = get_client()
+
+    params: dict[str, Any] = {
+        "state": state,
+        "per_page": clamp_per_page(per_page),
+        "page": validate_positive_int(page, "page"),
+    }
+
+    return await client.get(f"/repos/{owner}/{repo}/pulls", params=params)
+
+
+async def get_pull_request(
+    owner: str | None,
+    repo: str,
+    pull_number: int,
+) -> dict[str, Any]:
+    """Get a single pull request by number.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        pull_number: Pull request number
+
+    Returns:
+        Pull request details including head/base refs and merge status
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    pull_number = validate_positive_int(pull_number, "pull_number")
+
+    client = get_client()
+    return await client.get(f"/repos/{owner}/{repo}/pulls/{pull_number}")
+
+
+async def get_pull_request_diff(
+    owner: str | None,
+    repo: str,
+    pull_number: int,
+) -> dict[str, Any]:
+    """Get the unified diff for a pull request.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        pull_number: Pull request number
+
+    Returns:
+        Dictionary with the diff text under the "content" key
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    pull_number = validate_positive_int(pull_number, "pull_number")
+
+    client = get_client()
+    return await client.get(
+        f"/repos/{owner}/{repo}/pulls/{pull_number}",
+        accept=DIFF_ACCEPT,
+    )
+
+
+def _classify_checks(
+    check_runs: dict[str, Any], combined_status: dict[str, Any]
+) -> dict[str, list[dict[str, Any]]]:
+    """Sort check-runs and commit-status contexts into verdict buckets.
+
+    Check-run conclusions failure/cancelled/timed_out/action_required are
+    failures; skipped/neutral are skips (NOT failures); success passes. An
+    incomplete run, or any other completed conclusion, is pending. Commit
+    statuses map failure/error -> failing, pending -> pending, success ->
+    passed.
+    """
+    buckets: dict[str, list[dict[str, Any]]] = {
+        "failing": [],
+        "pending": [],
+        "skipped": [],
+        "passed": [],
+    }
+
+    for run in check_runs.get("check_runs", []):
+        name = run.get("name")
+        status = run.get("status")
+        if status != "completed":
+            buckets["pending"].append({"name": name, "status": status})
+            continue
+        match run.get("conclusion"):
+            case (
+                "failure" | "cancelled" | "timed_out" | "action_required"
+            ) as conclusion:
+                url = run.get("html_url") or run.get("details_url") or ""
+                buckets["failing"].append(
+                    {"name": name, "conclusion": conclusion, "url": url}
+                )
+            case ("skipped" | "neutral") as conclusion:
+                buckets["skipped"].append({"name": name, "conclusion": conclusion})
+            case "success":
+                buckets["passed"].append({"name": name})
+            case _:
+                buckets["pending"].append({"name": name, "status": status})
+
+    for ctx in combined_status.get("statuses", []):
+        name = ctx.get("context")
+        match ctx.get("state"):
+            case ("failure" | "error") as state:
+                url = ctx.get("target_url") or ""
+                buckets["failing"].append(
+                    {"name": name, "conclusion": state, "url": url}
+                )
+            case "pending":
+                buckets["pending"].append({"name": name, "status": "pending"})
+            case "success":
+                buckets["passed"].append({"name": name})
+
+    return buckets
+
+
+async def get_pull_request_checks(
+    owner: str | None,
+    repo: str,
+    pull_number: int,
+) -> dict[str, Any]:
+    """Get a CI verdict for a pull request that distinguishes skip from fail.
+
+    Resolves the PR head SHA, then classifies every check-run (GitHub Checks
+    API) and legacy commit-status context into exactly one bucket: passed,
+    failing, pending, or skipped.
+
+    IMPORTANT: SKIPPED checks (conclusion "skipped" or "neutral") are NOT
+    failures and do not block merging. The legacy combined commit status can
+    report an overall state of "failure" when checks are merely skipped, which
+    is why this tool classifies each check explicitly instead of trusting that
+    aggregate. Use the ``ready_to_merge`` boolean as the signal for whether the
+    PR is clear to merge: it is True only when there are no failing and no
+    pending checks and the PR is not known-unmergeable.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        pull_number: Pull request number
+
+    Returns:
+        A verdict with the head SHA, mergeability, per-bucket check lists, a
+        summary count, and the ``ready_to_merge`` signal
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    pull_number = validate_positive_int(pull_number, "pull_number")
+
+    client = get_client()
+
+    pr = await client.get(f"/repos/{owner}/{repo}/pulls/{pull_number}")
+    head = pr.get("head") or {}
+    sha = head.get("sha")
+    if not sha:
+        raise ValidationError("Could not resolve pull request head SHA")
+
+    check_runs = await client.get(
+        f"/repos/{owner}/{repo}/commits/{sha}/check-runs"
+    )
+    combined_status = await client.get(
+        f"/repos/{owner}/{repo}/commits/{sha}/status"
+    )
+
+    buckets = _classify_checks(check_runs, combined_status)
+    failing = buckets["failing"]
+    pending = buckets["pending"]
+    skipped = buckets["skipped"]
+    passed = buckets["passed"]
+
+    mergeable = pr.get("mergeable")
+    ready_to_merge = (
+        not failing and not pending and mergeable is not False
+    )
+
+    return {
+        "pull_number": pull_number,
+        "head_sha": sha,
+        "mergeable": mergeable,
+        "mergeable_state": pr.get("mergeable_state", ""),
+        "ready_to_merge": ready_to_merge,
+        "summary": {
+            "passed": len(passed),
+            "failing": len(failing),
+            "pending": len(pending),
+            "skipped": len(skipped),
+        },
+        "failing": failing,
+        "pending": pending,
+        "skipped": skipped,
+        "passed": passed,
+    }
+
+
+async def update_pull_request(
+    owner: str | None,
+    repo: str,
+    pull_number: int,
+    state: str | None = None,
+    title: str | None = None,
+    body: str | None = None,
+) -> dict[str, Any]:
+    """Update a pull request — including closing or reopening it.
+
+    Note: this does NOT merge. Set state="closed" to close a PR without merging.
+
+    Args:
+        owner: Repository owner (defaults to GITHUB_DEFAULT_ORG if unset)
+        repo: Repository name
+        pull_number: Pull request number
+        state: "open" or "closed" (set "closed" to close the PR)
+        title: New title (optional)
+        body: New body (optional)
+
+    Returns:
+        Updated PR details (number, state, html_url, title)
+    """
+    owner = resolve_owner(owner)
+    repo = validate_name(repo, "repo")
+    pull_number = validate_positive_int(pull_number, "pull_number")
+
+    json_data: dict[str, Any] = {}
+    if state is not None:
+        if state not in ("open", "closed"):
+            raise ValidationError("state must be 'open' or 'closed'")
+        json_data["state"] = state
+    if title is not None:
+        json_data["title"] = title
+    if body is not None:
+        json_data["body"] = body
+    if not json_data:
+        raise ValidationError("no fields to update")
+
+    client = get_client()
+    result = await client.patch(
+        f"/repos/{owner}/{repo}/pulls/{pull_number}",
+        json_data=json_data,
+    )
+    return {
+        "number": result.get("number"),
+        "state": result.get("state"),
+        "html_url": result.get("html_url"),
+        "title": result.get("title"),
+    }

mcp_github_crunchtools/tools/search.py

@@ -0,0 +1,81 @@
+"""Search tools.
+
+Tools for searching code and issues/PRs across GitHub.
+"""
+
+from typing import Any
+
+from ..client import get_client
+from ..errors import ValidationError
+from ..models import (
+    MAX_QUERY_LENGTH,
+    clamp_per_page,
+    validate_positive_int,
+)
+
+
+def _validate_query(query: str) -> str:
+    if not query or not query.strip():
+        raise ValidationError("query must not be empty")
+    query = query.strip()
+    if len(query) > MAX_QUERY_LENGTH:
+        raise ValidationError("query is too long")
+    return query
+
+
+async def search_code(
+    query: str,
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """Search for code across GitHub.
+
+    Uses GitHub's code search syntax (e.g., "addClass repo:jquery/jquery").
+
+    Args:
+        query: Search query string
+        per_page: Results per page (max 100)
+        page: Page number
+
+    Returns:
+        Search results with total count and matched code items
+    """
+    query = _validate_query(query)
+
+    client = get_client()
+    params: dict[str, Any] = {
+        "q": query,
+        "per_page": clamp_per_page(per_page),
+        "page": validate_positive_int(page, "page"),
+    }
+
+    return await client.get("/search/code", params=params)
+
+
+async def search_issues(
+    query: str,
+    per_page: int = 30,
+    page: int = 1,
+) -> dict[str, Any]:
+    """Search for issues and pull requests across GitHub.
+
+    Uses GitHub's issue search syntax (e.g., "is:open is:pr author:octocat").
+
+    Args:
+        query: Search query string
+        per_page: Results per page (max 100)
+        page: Page number
+
+    Returns:
+        Search results with total count and matched issues/PRs
+    """
+    query = _validate_query(query)
+
+    client = get_client()
+    params: dict[str, Any] = {
+        "q": query,
+        "per_page": clamp_per_page(per_page),
+        "page": validate_positive_int(page, "page"),
+    }
+
+    return await client.get("/search/issues", params=params)

mcp_github_crunchtools-1.0.1.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.5
+Name: mcp-github-crunchtools
+Version: 1.0.1
+Summary: Secure MCP server for GitHub issues, pull requests, files, and search
+Author: crunchtools.com
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Keywords: devops,fastmcp,github,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MCP GitHub CrunchTools
+
+A secure MCP (Model Context Protocol) server for GitHub issues, pull requests, repository files, and search. Works with github.com and GitHub Enterprise Server.
+
+## Overview
+
+This MCP server is designed to be:
+
+- **Secure by default** - STRIDE threat model (see [SECURITY.md](SECURITY.md)), Pydantic input validation, and the API token held as a `SecretStr` to prevent accidental logging
+- **No third-party services** - Runs locally via stdio, your API token never leaves your machine
+- **Multi-instance** - Works with github.com or GitHub Enterprise Server via configurable API URL
+- **Cross-platform** - Works on Linux, macOS, and Windows
+- **Automatically updated** - GitHub Actions monitor for CVEs and update dependencies
+- **Containerized** - Available at `quay.io/crunchtools/mcp-github` built on [Hummingbird Python](https://quay.io/repository/hummingbird/python) base image
+
+## Naming Convention
+
+| Component | Name |
+|-----------|------|
+| GitHub repo | [crunchtools/mcp-github](https://github.com/crunchtools/mcp-github) |
+| Container | `quay.io/crunchtools/mcp-github` |
+| Python package (PyPI) | `mcp-github-crunchtools` |
+| CLI command | `mcp-github-crunchtools` |
+| Module import | `mcp_github_crunchtools` |
+
+## Why Hummingbird?
+
+The container image is built on the [Hummingbird Python base image](https://quay.io/repository/hummingbird/python) from [Project Hummingbird](https://github.com/hummingbird-project), which provides:
+
+- **Minimal CVE exposure** - Built with a minimal package set, dramatically reducing the attack surface
+- **Regular updates** - Security patches are applied promptly
+- **Optimized for Python** - Pre-configured Python environment
+- **Production-ready** - Proper signal handling and non-root user defaults
+
+## Features
+
+### Issues (3 tools)
+- `list_issues_tool` - List issues for a repository (pull requests excluded)
+- `get_issue_tool` - Get a single issue by number
+- `create_issue_comment_tool` - Comment on an issue or pull request (write)
+
+### Pull Requests (4 tools)
+- `list_pull_requests_tool` - List pull requests for a repository
+- `get_pull_request_tool` - Get a single pull request by number
+- `get_pull_request_diff_tool` - Get the unified diff for a pull request
+- `get_pull_request_checks_tool` - Combined CI status (check-runs + commit status)
+
+### Files (2 tools)
+- `get_file_content_tool` - Read decoded file content from a repository
+- `list_repo_tree_tool` - List the git tree (files and directories)
+
+### Search (2 tools)
+- `search_code_tool` - Search code across GitHub
+- `search_issues_tool` - Search issues and pull requests across GitHub
+
+## Installation
+
+### With uvx (Recommended)
+
+```bash
+uvx mcp-github-crunchtools
+```
+
+### With pip
+
+```bash
+pip install mcp-github-crunchtools
+```
+
+### With Container
+
+```bash
+podman run -e GITHUB_TOKEN=your_token \
+    quay.io/crunchtools/mcp-github
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GITHUB_TOKEN` | Yes | — | GitHub Personal Access Token |
+| `GITHUB_API_URL` | No | `https://api.github.com` | API base URL (set for GHES) |
+| `GITHUB_DEFAULT_ORG` | No | — | Default owner when a tool omits `owner` |
+| `SSL_CERT_FILE` | No | — | Custom CA bundle path, for self-hosted GHES with an internal CA |
+| `GITHUB_SSL_VERIFY` | No | `true` | Set `false` to disable TLS verification (not recommended) |
+
+### Creating a GitHub Personal Access Token
+
+1. **Navigate to token settings**
+   - Go to https://github.com/settings/tokens
+
+2. **Create a token**
+   - **Name**: `mcp-github-crunchtools`
+   - **Expiration**: Set an appropriate date (90 days recommended)
+   - **Scopes**: Grant read access to contents, issues, and pull requests.
+     Add write to issues/PRs only if you need `create_issue_comment_tool`.
+
+3. **Copy and Store Token**
+   - Copy the token immediately (shown only once)
+   - Store securely in a password manager
+
+### Add to Claude Code
+
+```bash
+claude mcp add mcp-github-crunchtools \
+    --env GITHUB_TOKEN=your_token_here \
+    -- uvx mcp-github-crunchtools
+```
+
+For GitHub Enterprise Server:
+
+```bash
+claude mcp add mcp-github-crunchtools \
+    --env GITHUB_TOKEN=your_token_here \
+    --env GITHUB_API_URL=https://ghe.example.com/api/v3 \
+    -- uvx mcp-github-crunchtools
+```
+
+For the container version:
+
+```bash
+claude mcp add mcp-github-crunchtools \
+    --env GITHUB_TOKEN=your_token_here \
+    -- podman run -i --rm -e GITHUB_TOKEN quay.io/crunchtools/mcp-github
+```
+
+## Usage Examples
+
+### List Issues
+
+```
+User: List open issues for crunchtools/mcp-github
+Assistant: [calls list_issues_tool with owner="crunchtools", repo="mcp-github"]
+```
+
+### Review a Pull Request
+
+```
+User: Show me the diff for PR #5 in crunchtools/mcp-github
+Assistant: [calls get_pull_request_diff_tool with pull_number=5]
+```
+
+### Check CI Status
+
+```
+User: Did the checks pass on pull request 5?
+Assistant: [calls get_pull_request_checks_tool with pull_number=5]
+```
+
+### Read a File
+
+```
+User: Show me src/server.py from crunchtools/mcp-github
+Assistant: [calls get_file_content_tool with path="src/server.py"]
+```
+
+### Search
+
+```
+User: Find code using FastMCP in crunchtools repos
+Assistant: [calls search_code_tool with query="FastMCP org:crunchtools"]
+```
+
+## Security
+
+This server was designed with security as a primary concern. See [SECURITY.md](SECURITY.md) for details.
+
+### Key Security Features
+
+1. **Token Protection**
+   - Stored as SecretStr (never accidentally logged)
+   - Environment variable only (never in files or args)
+   - Sanitized from all error messages
+
+2. **Input Validation**
+   - Pydantic models for write inputs
+   - Allowlist character validation for owner/repo names
+   - Path traversal prevention for file reads
+
+3. **API Hardening**
+   - Bearer-token auth and pinned GitHub API version
+   - HTTPS enforcement (except localhost)
+   - TLS certificate validation
+   - Request timeouts (30s)
+   - Response size limits (10MB)
+
+4. **Automated CVE Scanning**
+   - GitHub Actions scan dependencies
+   - Container security scanning with Trivy
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/crunchtools/mcp-github.git
+cd mcp-github
+uv sync --all-extras
+```
+
+### Run Tests
+
+```bash
+uv run pytest
+```
+
+### Lint and Type Check
+
+```bash
+uv run ruff check src tests
+uv run mypy src
+```
+
+### Build Container
+
+```bash
+podman build -t mcp-github .
+```
+
+## License
+
+AGPL-3.0-or-later
+
+## Contributing
+
+Contributions welcome! Please read SECURITY.md before submitting security-related changes.
+
+## Links
+
+- [GitHub REST API Documentation](https://docs.github.com/en/rest)
+- [FastMCP Documentation](https://gofastmcp.com/)
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [crunchtools.com](https://crunchtools.com)
+
+<!-- mcp-name: io.github.crunchtools/github -->

mcp_github_crunchtools-1.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+mcp_github_crunchtools/__init__.py,sha256=TA95qz8FfAAQot2W1bJEylmCEBzv6yEN8np_T188lGU,1630
+mcp_github_crunchtools/__main__.py,sha256=BYo13fF7OXaJiVbx-g9OxLXxXFX_FtH8SjvIiBDw3WM,115
+mcp_github_crunchtools/client.py,sha256=Tg2_4s86Fj6iXhU7FRQgO0nTBJm35kMYCvIVG-IpscY,9112
+mcp_github_crunchtools/config.py,sha256=n9NpxhxJdigCj_5T7C5qbBqJJMkyikxHooxPXJteOVw,4093
+mcp_github_crunchtools/errors.py,sha256=z99ivMY95PrVu0a1VV9S88_d51F8NWOmoAk23K5p20g,1919
+mcp_github_crunchtools/models.py,sha256=KgxcbSk0Zxngr0oOF_d9xDzt7L3_n5Wo4lOSyVqwoFE,5871
+mcp_github_crunchtools/server.py,sha256=GYOBOSFTDKCdUpdlvQGdxOFItSBMU18MXXp0TddehZc,13726
+mcp_github_crunchtools/tools/__init__.py,sha256=poTwR5xIH15MmUPSYlrGQI2HcAD107yz6UlsUzkkRyQ,1041
+mcp_github_crunchtools/tools/actions.py,sha256=rli_XZ_wwO_gx1sTcY9v1ZrgadQRbtvWIFH14DZIRnA,5884
+mcp_github_crunchtools/tools/files.py,sha256=3F2nCeGVoP8GKTFuhTPhyOxQBEBxp4lWWTmgv907axQ,3635
+mcp_github_crunchtools/tools/issues.py,sha256=XQ8CWLh4YRsHWEN3mQRnG7XwuO9Q0_6HB82HYOXSfhE,6429
+mcp_github_crunchtools/tools/pull_requests.py,sha256=INN75H71d1XNVvWieMLlx7JAfm89v02i_mCcvDQwklk,9068
+mcp_github_crunchtools/tools/search.py,sha256=FVLA0J7J_GNCh39qZQlFZlMRn4XyVN54ODkxVJbHbQg,1961
+mcp_github_crunchtools-1.0.1.dist-info/METADATA,sha256=s221ntasJ3PZw1jX_lJb0ylHn_0qF9ePLKl9b93zcko,7848
+mcp_github_crunchtools-1.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mcp_github_crunchtools-1.0.1.dist-info/entry_points.txt,sha256=RwJaHs3zcHeGjhsSDbZgxpGpDEWBKOFIZojcXXCpIMs,71
+mcp_github_crunchtools-1.0.1.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+mcp_github_crunchtools-1.0.1.dist-info/RECORD,,

mcp_github_crunchtools-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_github_crunchtools-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-github-crunchtools = mcp_github_crunchtools:main