mcp-github-crunchtools 1.0.1__tar.gz

mcp_github_crunchtools-1.0.1/.gatehouse-ignore

@@ -0,0 +1,3 @@
+# Paths Gatehouse never reviews (gitignore syntax). Read from the base branch in CI.
+uv.lock
+.specify/templates/

mcp_github_crunchtools-1.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,79 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of the bug
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this bug?
+      placeholder: |
+        1. Call tool '...' with args '...'
+        2. Observe error '...'
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages if available.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport
+      description: How are you running the MCP server?
+      options:
+        - stdio (uvx / pip)
+        - streamable-http (container / systemd)
+        - SSE
+    validations:
+      required: true
+
+  - type: dropdown
+    id: github_instance
+    attributes:
+      label: GitHub Instance Type
+      options:
+        - github.com
+        - Self-hosted (corporate/private)
+        - GitHub Community Edition
+        - GitHub Enterprise Edition
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Server Version
+      description: Output of `mcp-github-crunchtools --version` or pip show
+      placeholder: "0.3.2"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information (logs, config, environment)

mcp_github_crunchtools-1.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: GitHub API Documentation
+    url: https://docs.github.com/api/rest/
+    about: Check the GitHub REST API docs for endpoint behavior questions

mcp_github_crunchtools-1.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,73 @@
+name: Feature Request
+description: Suggest a new tool or enhancement
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve?
+      placeholder: I need to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the tool or change you'd like
+      placeholder: |
+        Tool name: `do_something`
+        GitHub API endpoint: `POST /projects/:id/...`
+        Parameters: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What alternatives have you considered?
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Tool Category
+      description: Which area does this feature belong to?
+      options:
+        - Projects / Groups
+        - Merge Requests
+        - Issues
+        - Pipelines / Jobs
+        - Files / Repository
+        - Branches
+        - Labels
+        - Users
+        - Releases
+        - Milestones
+        - Wiki
+        - Snippets
+        - Search
+        - Security / Config
+        - New Category
+    validations:
+      required: true
+
+  - type: dropdown
+    id: github_api
+    attributes:
+      label: GitHub API Reference
+      description: Does this correspond to an existing GitHub REST API endpoint?
+      options:
+        - "Yes - documented in GitHub API docs"
+        - "No - new behavior / aggregation"
+        - "Not sure"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information, API docs links, or examples

mcp_github_crunchtools-1.0.1/.github/dependabot.yml

@@ -0,0 +1,30 @@
+# Canonical Dependabot config for crunchtools Python projects using uv.
+# Drop in as .github/dependabot.yml. See constitution.md Section XV.
+#
+# Covers both ecosystems that go stale silently if left unpinned:
+#   - uv:            uv.lock (must be committed, never gitignored)
+#   - github-actions: `uses: some-action@vX.Y.Z` pins in .github/workflows/
+
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+    ignore:
+      - dependency-name: "crunchtools/constitution*"

mcp_github_crunchtools-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src tests
+
+      - name: Run type checker
+        run: uv run mypy src
+
+      - name: Run tests
+        run: uv run pytest -v
+        env:
+          GITHUB_TOKEN: "test_token_for_ci"
+
+  gourmand:
+    name: Code Quality (Gourmand)
+    uses: crunchtools/gatehouse/.github/workflows/gourmand.yml@v0.15.2
+
+  build-container:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build container image
+        run: |
+          docker build -f Containerfile -t mcp-github:test .
+
+      - name: Verify container
+        run: |
+          # Just verify it starts (will fail due to no token, but should start)
+          timeout 5 docker run --rm mcp-github:test || true

mcp_github_crunchtools-1.0.1/.github/workflows/constitution.yml

@@ -0,0 +1,21 @@
+# Drop in as .github/workflows/constitution.yml. See constitution.md VII.
+#
+# The tag below is the constitution version this repo is judged by. It moves
+# together with `Inherits:` in .specify/memory/constitution.md (scripts/fleet-bump.py
+# opens that PR); Dependabot is told to ignore it, see examples/dependabot.yml.
+# Required check: `Constitution / Validate constitution`.
+
+name: Constitution
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  constitution:
+    name: Constitution
+    uses: crunchtools/constitution/.github/workflows/validate.yml@v1.18.0

mcp_github_crunchtools-1.0.1/.github/workflows/container.yml

@@ -0,0 +1,112 @@
+name: Container Build & Push
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  QUAY_IMAGE: quay.io/crunchtools/mcp-github
+  GHCR_IMAGE: ghcr.io/crunchtools/mcp-github
+
+jobs:
+  build-and-push-quay:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to Quay.io
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: quay.io
+          username: ${{ secrets.QUAY_USERNAME }}
+          password: ${{ secrets.QUAY_PASSWORD }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.QUAY_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Containerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run Trivy vulnerability scanner
+        continue-on-error: true
+        if: github.event_name != 'pull_request'
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: ${{ env.QUAY_IMAGE }}:latest
+          format: "table"
+          exit-code: "0"
+          severity: "CRITICAL,HIGH"
+          version: "v0.68.2"
+
+  build-and-push-ghcr:
+    runs-on: ubuntu-latest
+    needs: build-and-push-quay
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ github.token }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.GHCR_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Containerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha

mcp_github_crunchtools-1.0.1/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,18 @@
+# Drop in as .github/workflows/dependabot-automerge.yml. See constitution.md XV.
+#
+# Queues green GitHub Actions minor/patch bumps for auto-merge. Needs the repo
+# setting `allow_auto_merge`; the required checks still decide the merge.
+
+name: Dependabot auto-merge
+
+on:
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  automerge:
+    name: Dependabot
+    uses: crunchtools/constitution/.github/workflows/dependabot-automerge.yml@v1.18.0

mcp_github_crunchtools-1.0.1/.github/workflows/gatehouse-retriage.yml

@@ -0,0 +1,23 @@
+# Gatehouse retriage — makes a reply to a finding clear the triage check.
+#
+# Drop this next to examples/gatehouse.yml. A reply re-runs the `Gatehouse`
+# workflow, but that run's checks do not count toward branch rules; only the
+# pull_request_target run's do. When the reply run finishes, this re-runs
+# triage inside the pull_request_target run. `workflow_run` always executes
+# the default-branch copy of this file, so a fork cannot alter it.
+
+name: Gatehouse retriage
+
+on:
+  workflow_run:
+    workflows: [Gatehouse]   # the `name:` of your gatehouse.yml
+    types: [completed]
+
+permissions: {}   # default-deny
+
+jobs:
+  retriage:
+    if: github.event.workflow_run.event == 'pull_request_review_comment'
+    permissions:
+      actions: write   # re-run the triage job; nothing else
+    uses: crunchtools/gatehouse/.github/workflows/retriage.yml@v0.15.2

mcp_github_crunchtools-1.0.1/.github/workflows/gatehouse.yml

@@ -0,0 +1,110 @@
+# Gatehouse — fork-safe code review + workflow protection, in ONE file.
+#
+# Drop this in your repo at .github/workflows/gatehouse.yml, add a OPENROUTER_API_KEY
+# secret, and you get:
+#   • AI review of every PR (including from forks) — posted as a PR review
+#   • rejection of untrusted PRs that try to modify your workflow files
+#
+# Nothing is ever checked out from the PR. The fork's change is only ever read as
+# a diff (data); the reviewer logic lives in the pinned gatehouse container; the
+# rules (your styleguide/constitution) are fetched from YOUR base branch, not the
+# PR. The one thing you don't trust — the proposed change — is only ever read.
+#
+# Three jobs with DIFFERENT authority:
+#   • guard   — a real blocking gate. Mark it a REQUIRED status check so a PR
+#               that tampers with your workflow files is rejected.
+#   • review  — ADVISORY. It posts findings as PR comments and always passes;
+#               do NOT mark it required. An LLM reviewer is non-deterministic,
+#               so it must never hold merge authority. (Opt into blocking with
+#               `blocking: true` below only if you accept that tradeoff — and
+#               even then, keep it out of branch protection.)
+#   • triage  — deterministic. Fails while any finding has no reply
+#               (`fixed in <sha>` or `not a bug: <reason>`). Safe to mark
+#               REQUIRED: it never judges code, only whether a human answered.
+
+name: Gatehouse
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+  # A reply rings the doorbell: this run's own checks do not count toward
+  # branch rules, so examples/gatehouse-retriage.yml answers it by re-running
+  # triage inside the pull_request_target run. Add that file too.
+  pull_request_review_comment:
+    types: [created, edited, deleted]
+
+permissions: {}   # default-deny; each job grants only what it needs
+
+jobs:
+  # ── 1) Protect the workflow files themselves ────────────────────────────────
+  # Rejects PRs from forks that touch .github/workflows/. Safe under
+  # pull_request_target because it only reads the changed-file LIST via the
+  # API — it never checks out or runs your code. And because pull_request_target
+  # runs the BASE version of this file, a PR can't edit this job to disable it.
+  guard:
+    name: Protect workflows
+    # Runs on replies too. A job skipped on the reply event reports
+    # "skipped", which a required check counts as passing: skipping the
+    # guard there would let any comment on a rejected fork PR clear it.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Reject workflow changes from untrusted PRs
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT: ${{ github.event_name }}
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+        run: |
+          set -euo pipefail
+          # Gate on where the branch lives, not on the author's role: a branch
+          # pushed into this repo already required write access, and a fork is
+          # what pull_request_target actually guards against.
+          if [ "$HEAD_REPO" = "$GITHUB_REPOSITORY" ]; then
+            echo "Head branch is in $GITHUB_REPOSITORY; allowing."; exit 0
+          fi
+          # Both sides of a rename: `gh pr diff --name-only` lists only the new
+          # path, so a fork could move a workflow out of .github/workflows/ unseen.
+          changed="$(gh api --paginate "repos/$GITHUB_REPOSITORY/pulls/$PR/files" \
+            --jq '.[] | .filename, (.previous_filename // empty)')"
+          if echo "$changed" | grep -qE '^\.github/workflows/'; then
+            echo "::error::PR modifies .github/workflows/ — not accepted from external contributors."
+            # Explain once, on the PR event; replies re-run the check, not the comment.
+            if [ "$EVENT" = "pull_request_target" ]; then
+              gh pr comment "$PR" --repo "$GITHUB_REPOSITORY" --body \
+                $'🚫 **Workflow changes are not accepted via pull request.** Please open an issue and a maintainer will make the change.'
+            fi
+            exit 1
+          fi
+          echo "No workflow files changed."
+
+  # ── 2) Review the PR diff (no checkout, BYO key) ────────────────────────────
+  # The reviewer is maintained centrally in gatehouse's reusable workflow and the
+  # pinned container — so security fixes reach you without copying logic around.
+  # Scope OPENROUTER_API_KEY to this reusable workflow so only it can read the key.
+  review:
+    name: Gatehouse review
+    if: github.event_name == 'pull_request_target'
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: crunchtools/gatehouse/.github/workflows/review.yml@v0.15.2
+    # Advisory by default — findings post as comments, the check always passes.
+    # Uncomment to let critical/high findings fail the check (still not required):
+    #   with:
+    #     blocking: true
+    secrets:
+      OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+
+  # ── 3) Every finding answered ──────────────────────────────────────────────
+  # Runs after the review on a push, and alone on a reply (review is skipped
+  # then, hence always()). Read-only, no secrets.
+  triage:
+    name: Gatehouse triage
+    needs: review
+    if: always()
+    permissions:
+      pull-requests: read
+    uses: crunchtools/gatehouse/.github/workflows/triage.yml@v0.15.2

mcp_github_crunchtools-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1