From aecc009db4270fb9d506db7cd6d0c1d1ec16296d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 5 Nov 2026 16:23:14 +0000 Subject: [PATCH 1/5] build(deps): bump golang.org/x/net from 0.61.0 to 0.62.0 Bumps [golang.org/x/net](https://github.com/golang/net) from 0.61.0 to 0.62.0. - [Commits](https://github.com/golang/net/compare/v0.61.0...v0.62.0) --- updated-dependencies: - dependency-name: golang.org/x/net dependency-version: 0.62.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index f848a191bb..d9b861fda9 100644 --- a/go.mod +++ b/go.mod @@ -20,7 +20,7 @@ require ( github.com/spf13/viper v1.21.0 github.com/stretchr/testify v1.12.1 github.com/yosida95/uritemplate/v3 v3.0.2 - golang.org/x/net v0.61.0 + golang.org/x/net v0.62.0 golang.org/x/oauth2 v0.37.0 ) diff --git a/go.sum b/go.sum index eec6755985..e804c329b6 100644 --- a/go.sum +++ b/go.sum @@ -86,8 +86,8 @@ golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLL golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= -golang.org/x/net v0.61.0 h1:RR+6j/BTBCrggOLugxa+66R8FvoN6MHlzDlZIbN9YFw= -golang.org/x/net v0.61.0/go.mod h1:WgDCOTH8iwtB66T4/GfI94AHo/hhdb7Hah9NDseQfiI= +golang.org/x/net v0.62.0 h1:18ELalfM5+XNRwzM2nYqXsZQ9ByS1uhj2O/U7+5jqRY= +golang.org/x/net v0.62.0/go.mod h1:WgDCOTH8iwtB66T4/GfI94AHo/hhdb7Hah9NDseQfiI= golang.org/x/oauth2 v0.37.0 h1:JUlcxA8oAtauLfiH8FX2/FkAWHAdi0QtGCGc+hofE98= golang.org/x/oauth2 v0.37.0/go.mod h1:IxwZNxUULJmpBFf9K/9NTMSIfZZuvuTy1gGxhigP/58= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= From 47af05c2de1c0aa5c45ed352de407f7e4877f401 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 5 Nov 2026 16:24:28 +0000 Subject: [PATCH 2/5] chore: regenerate license files Auto-generated by license-check workflow --- third-party-licenses.darwin.md | 2 +- third-party-licenses.linux.md | 2 +- third-party-licenses.windows.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/third-party-licenses.darwin.md b/third-party-licenses.darwin.md index 4eec968221..e56119de40 100644 --- a/third-party-licenses.darwin.md +++ b/third-party-licenses.darwin.md @@ -42,7 +42,7 @@ The following packages are included for the amd64, arm64 architectures. - [github.com/subosito/gotenv](https://pkg.go.dev/github.com/subosito/gotenv) ([MIT](https://github.com/subosito/gotenv/blob/v1.6.0/LICENSE)) - [github.com/yosida95/uritemplate/v3](https://pkg.go.dev/github.com/yosida95/uritemplate/v3) ([BSD-3-Clause](https://github.com/yosida95/uritemplate/blob/v3.0.2/LICENSE)) - [go.yaml.in/yaml/v3](https://pkg.go.dev/go.yaml.in/yaml/v3) ([MIT](https://github.com/yaml/go-yaml/blob/v3.0.5/LICENSE)) - - [golang.org/x/net](https://pkg.go.dev/golang.org/x/net) ([BSD-3-Clause](https://cs.opensource.google/go/x/net/+/v0.61.0:LICENSE)) + - [golang.org/x/net](https://pkg.go.dev/golang.org/x/net) ([BSD-3-Clause](https://cs.opensource.google/go/x/net/+/v0.62.0:LICENSE)) - [golang.org/x/oauth2](https://pkg.go.dev/golang.org/x/oauth2) ([BSD-3-Clause](https://cs.opensource.google/go/x/oauth2/+/v0.37.0:LICENSE)) - [golang.org/x/sync/errgroup](https://pkg.go.dev/golang.org/x/sync/errgroup) ([BSD-3-Clause](https://cs.opensource.google/go/x/sync/+/v0.24.0:LICENSE)) - [golang.org/x/sys](https://pkg.go.dev/golang.org/x/sys) ([BSD-3-Clause](https://cs.opensource.google/go/x/sys/+/v0.49.0:LICENSE)) diff --git a/third-party-licenses.linux.md b/third-party-licenses.linux.md index a714a789a1..4e80b87ea4 100644 --- a/third-party-licenses.linux.md +++ b/third-party-licenses.linux.md @@ -42,7 +42,7 @@ The following packages are included for the 386, amd64, arm64 architectures. - [github.com/subosito/gotenv](https://pkg.go.dev/github.com/subosito/gotenv) ([MIT](https://github.com/subosito/gotenv/blob/v1.6.0/LICENSE)) - [github.com/yosida95/uritemplate/v3](https://pkg.go.dev/github.com/yosida95/uritemplate/v3) ([BSD-3-Clause](https://github.com/yosida95/uritemplate/blob/v3.0.2/LICENSE)) - [go.yaml.in/yaml/v3](https://pkg.go.dev/go.yaml.in/yaml/v3) ([MIT](https://github.com/yaml/go-yaml/blob/v3.0.5/LICENSE)) - - [golang.org/x/net](https://pkg.go.dev/golang.org/x/net) ([BSD-3-Clause](https://cs.opensource.google/go/x/net/+/v0.61.0:LICENSE)) + - [golang.org/x/net](https://pkg.go.dev/golang.org/x/net) ([BSD-3-Clause](https://cs.opensource.google/go/x/net/+/v0.62.0:LICENSE)) - [golang.org/x/oauth2](https://pkg.go.dev/golang.org/x/oauth2) ([BSD-3-Clause](https://cs.opensource.google/go/x/oauth2/+/v0.37.0:LICENSE)) - [golang.org/x/sync/errgroup](https://pkg.go.dev/golang.org/x/sync/errgroup) ([BSD-3-Clause](https://cs.opensource.google/go/x/sync/+/v0.24.0:LICENSE)) - [golang.org/x/sys](https://pkg.go.dev/golang.org/x/sys) ([BSD-3-Clause](https://cs.opensource.google/go/x/sys/+/v0.49.0:LICENSE)) diff --git a/third-party-licenses.windows.md b/third-party-licenses.windows.md index e5fc90b46e..a08ec62093 100644 --- a/third-party-licenses.windows.md +++ b/third-party-licenses.windows.md @@ -43,7 +43,7 @@ The following packages are included for the 386, amd64, arm64 architectures. - [github.com/subosito/gotenv](https://pkg.go.dev/github.com/subosito/gotenv) ([MIT](https://github.com/subosito/gotenv/blob/v1.6.0/LICENSE)) - [github.com/yosida95/uritemplate/v3](https://pkg.go.dev/github.com/yosida95/uritemplate/v3) ([BSD-3-Clause](https://github.com/yosida95/uritemplate/blob/v3.0.2/LICENSE)) - [go.yaml.in/yaml/v3](https://pkg.go.dev/go.yaml.in/yaml/v3) ([MIT](https://github.com/yaml/go-yaml/blob/v3.0.5/LICENSE)) - - [golang.org/x/net](https://pkg.go.dev/golang.org/x/net) ([BSD-3-Clause](https://cs.opensource.google/go/x/net/+/v0.61.0:LICENSE)) + - [golang.org/x/net](https://pkg.go.dev/golang.org/x/net) ([BSD-3-Clause](https://cs.opensource.google/go/x/net/+/v0.62.0:LICENSE)) - [golang.org/x/oauth2](https://pkg.go.dev/golang.org/x/oauth2) ([BSD-3-Clause](https://cs.opensource.google/go/x/oauth2/+/v0.37.0:LICENSE)) - [golang.org/x/sync/errgroup](https://pkg.go.dev/golang.org/x/sync/errgroup) ([BSD-3-Clause](https://cs.opensource.google/go/x/sync/+/v0.24.0:LICENSE)) - [golang.org/x/sys](https://pkg.go.dev/golang.org/x/sys) ([BSD-3-Clause](https://cs.opensource.google/go/x/sys/+/v0.49.0:LICENSE)) From a179e1560189fe56ca5087320ed2b0d9329bcc0c Mon Sep 17 00:00:00 2001 From: TKM4991 <339926613+kraigmills-stack@users.noreply.github.com> Date: Fri, 6 Nov 2026 09:09:50 -0500 Subject: [PATCH 3/5] Remove Docker references from publish workflow Strip Docker names and action namespaces from the publish workflow, leaving invalid action references. Remove a leading space from the bug report's version command. --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/workflows/docker-publish.yml | 42 ++++++++++++++-------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 79d806777b..c2290d6b37 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -13,7 +13,7 @@ A clear and concise description of what the bug is. ### Affected version -Please run ` docker run -i --rm ghcr.io/github/github-mcp-server ./github-mcp-server --version` and paste the output below +Please run `docker run -i --rm ghcr.io/github/github-mcp-server ./github-mcp-server --version` and paste the output below ### Steps to reproduce the behavior diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index d443bc36f8..af4f11499b 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -1,4 +1,4 @@ -name: Docker +name: # This workflow uses actions that are not certified by GitHub. # They are provided by a third-party and are governed by @@ -23,7 +23,7 @@ on: default: "Manual run" env: - # Use docker.io for Docker Hub if empty + # Use .io for Hub if empty REGISTRY: ghcr.io # github.repository as / IMAGE_NAME: ${{ github.repository }} @@ -50,27 +50,27 @@ jobs: with: cosign-release: "v3.1.3" - # Set up BuildKit Docker container builder to be able to build + # Set up BuildKit container builder to be able to build # multi-platform images and export cache - # https://github.com/docker/setup-buildx-action - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + # https://github.com//setup-buildx-action + - name: Set up Buildx + uses: /setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 - # Login against a Docker registry except on PR - # https://github.com/docker/login-action + # Login against a registry except on PR + # https://github.com//login-action - name: Log into registry ${{ env.REGISTRY }} if: github.event_name != 'pull_request' - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 + uses: /login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - # Extract metadata (tags, labels) for Docker - # https://github.com/docker/metadata-action - - name: Extract Docker metadata + # Extract metadata (tags, labels) for + # https://github.com//metadata-action + - name: Extract metadata id: meta - uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 + uses: /metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | @@ -86,7 +86,7 @@ jobs: # Custom rule to prevent pre-releases from getting latest tag type=raw,value=latest,enable=${{ github.ref_type == 'tag' && startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-') }} - - name: Go Build Cache for Docker + - name: Go Build Cache for uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6 with: path: go-build-cache @@ -102,11 +102,11 @@ jobs: "go-build-cache/build": "/root/.cache/go-build" } - # Build and push Docker image with Buildx (don't push on PR) - # https://github.com/docker/build-push-action - - name: Build and push Docker image + # Build and push image with Buildx (don't push on PR) + # https://github.com//build-push-action + - name: Build and push image id: build-and-push - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 + uses: /build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 with: context: . push: ${{ github.event_name != 'pull_request' }} @@ -121,11 +121,11 @@ jobs: oauth_client_id=${{ secrets.OAUTH_CLIENT_ID }} oauth_client_secret=${{ secrets.OAUTH_CLIENT_SECRET }} - # Sign the resulting Docker image digest except on PRs. + # Sign the resulting image digest except on PRs. # Publish both v2-compatible .sig tags and native Sigstore bundles. # --yes also consents to publishing signing metadata to the public log. # https://github.com/sigstore/cosign - - name: Sign the published Docker image (legacy) + - name: Sign the published image (legacy) if: ${{ github.event_name != 'pull_request' }} env: # https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable @@ -134,7 +134,7 @@ jobs: # against the sigstore community Fulcio instance. run: cosign sign --yes --new-bundle-format=false --use-signing-config=false --registry-referrers-mode=legacy "${REGISTRY}/${IMAGE_NAME}@${DIGEST}" - - name: Sign the published Docker image (native bundle) + - name: Sign the published image (native bundle) if: ${{ github.event_name != 'pull_request' }} env: DIGEST: ${{ steps.build-and-push.outputs.digest }} From cf41e8b5538d0204fc4446b18f27fa0dbcad04d8 Mon Sep 17 00:00:00 2001 From: TKM4991 <339926613+kraigmills-stack@users.noreply.github.com> Date: Fri, 6 Nov 2026 09:09:50 -0500 Subject: [PATCH 4/5] Remove Docker references from publish workflow Strip Docker names and action namespaces from the publish workflow, leaving invalid action references. Remove a leading space from the bug report's version command. --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/workflows/docker-publish.yml | 42 ++++++++++++++-------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 79d806777b..c2290d6b37 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -13,7 +13,7 @@ A clear and concise description of what the bug is. ### Affected version -Please run ` docker run -i --rm ghcr.io/github/github-mcp-server ./github-mcp-server --version` and paste the output below +Please run `docker run -i --rm ghcr.io/github/github-mcp-server ./github-mcp-server --version` and paste the output below ### Steps to reproduce the behavior diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index d443bc36f8..af4f11499b 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -1,4 +1,4 @@ -name: Docker +name: # This workflow uses actions that are not certified by GitHub. # They are provided by a third-party and are governed by @@ -23,7 +23,7 @@ on: default: "Manual run" env: - # Use docker.io for Docker Hub if empty + # Use .io for Hub if empty REGISTRY: ghcr.io # github.repository as / IMAGE_NAME: ${{ github.repository }} @@ -50,27 +50,27 @@ jobs: with: cosign-release: "v3.1.3" - # Set up BuildKit Docker container builder to be able to build + # Set up BuildKit container builder to be able to build # multi-platform images and export cache - # https://github.com/docker/setup-buildx-action - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + # https://github.com//setup-buildx-action + - name: Set up Buildx + uses: /setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 - # Login against a Docker registry except on PR - # https://github.com/docker/login-action + # Login against a registry except on PR + # https://github.com//login-action - name: Log into registry ${{ env.REGISTRY }} if: github.event_name != 'pull_request' - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 + uses: /login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - # Extract metadata (tags, labels) for Docker - # https://github.com/docker/metadata-action - - name: Extract Docker metadata + # Extract metadata (tags, labels) for + # https://github.com//metadata-action + - name: Extract metadata id: meta - uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 + uses: /metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | @@ -86,7 +86,7 @@ jobs: # Custom rule to prevent pre-releases from getting latest tag type=raw,value=latest,enable=${{ github.ref_type == 'tag' && startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-') }} - - name: Go Build Cache for Docker + - name: Go Build Cache for uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6 with: path: go-build-cache @@ -102,11 +102,11 @@ jobs: "go-build-cache/build": "/root/.cache/go-build" } - # Build and push Docker image with Buildx (don't push on PR) - # https://github.com/docker/build-push-action - - name: Build and push Docker image + # Build and push image with Buildx (don't push on PR) + # https://github.com//build-push-action + - name: Build and push image id: build-and-push - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 + uses: /build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 with: context: . push: ${{ github.event_name != 'pull_request' }} @@ -121,11 +121,11 @@ jobs: oauth_client_id=${{ secrets.OAUTH_CLIENT_ID }} oauth_client_secret=${{ secrets.OAUTH_CLIENT_SECRET }} - # Sign the resulting Docker image digest except on PRs. + # Sign the resulting image digest except on PRs. # Publish both v2-compatible .sig tags and native Sigstore bundles. # --yes also consents to publishing signing metadata to the public log. # https://github.com/sigstore/cosign - - name: Sign the published Docker image (legacy) + - name: Sign the published image (legacy) if: ${{ github.event_name != 'pull_request' }} env: # https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable @@ -134,7 +134,7 @@ jobs: # against the sigstore community Fulcio instance. run: cosign sign --yes --new-bundle-format=false --use-signing-config=false --registry-referrers-mode=legacy "${REGISTRY}/${IMAGE_NAME}@${DIGEST}" - - name: Sign the published Docker image (native bundle) + - name: Sign the published image (native bundle) if: ${{ github.event_name != 'pull_request' }} env: DIGEST: ${{ steps.build-and-push.outputs.digest }} From afec709d3a8c9b82a0c51db928f547733e20e451 Mon Sep 17 00:00:00 2001 From: TKM4991 <339926613+kraigmills-stack@users.noreply.github.com> Date: Fri, 6 Nov 2026 14:38:03 -0500 Subject: [PATCH 5/5] Quit idk what im dong with any of this idk it github is for me --- .dockerignore | 36 ++- .../ISSUE_TEMPLATE/copilot-instructions.md | 291 ++++++++++++++++++ Dockerfile | 71 ++--- compose.debug.yaml | 6 + compose.yaml | 6 + .../delete_pending_pull_request_review.snap | 3 +- 6 files changed, 349 insertions(+), 64 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/copilot-instructions.md create mode 100644 compose.debug.yaml create mode 100644 compose.yaml diff --git a/.dockerignore b/.dockerignore index 8f302e7c05..7347a7fbb9 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,11 +1,25 @@ -.github -.vscode -script -third-party -.dockerignore -.gitignore -**/*.yml -**/*.yaml -**/*.md -**/*_test.go -LICENSE +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/bin +**/charts +**/docker-compose* +**/compose* +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md diff --git a/.github/ISSUE_TEMPLATE/copilot-instructions.md b/.github/ISSUE_TEMPLATE/copilot-instructions.md new file mode 100644 index 0000000000..0db7990bc4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/copilot-instructions.md @@ -0,0 +1,291 @@ +# GitHub MCP Server - Copilot Instructions + +## Project Overview + +This is the **GitHub MCP Server**, a Model Context Protocol (MCP) server that connects AI tools to GitHub's platform. It enables AI agents to manage repositories, issues, pull requests, workflows, and more through natural language. + +**Key Details:** +- **Language:** Go 1.27.3+ (~38k lines of code) +- **Type:** MCP server application with CLI interface +- **Primary Package:** github-mcp-server (stdio MCP server - **this is the main focus**) +- **Secondary Package:** mcpcurl (testing utility - don't break it, but not the priority) +- **Framework:** Uses modelcontextprotocol/go-sdk for MCP protocol, google/go-github for GitHub API +- **Size:** ~60MB repository, 70 Go files +- **Library Usage:** This repository is also used as a library by the remote server. Functions that could be called by other repositories should be exported (capitalized), even if not required internally. Preserve existing export patterns. + +**Code Quality Standards:** +- **Popular Open Source Repository** - High bar for code quality and clarity +- **Comprehension First** - Code must be clear to a wide audience +- **Clean Commits** - Atomic, focused changes with clear messages +- **Structure** - Always maintain or improve, never degrade +- **Code over Comments** - Prefer self-documenting code; comment only when necessary + +## Critical Build & Validation Steps + +### Required Commands (Run Before Committing) + +**ALWAYS run these commands in this exact order before using report_progress or finishing work:** + +1. **Format Code:** `script/lint` (runs `gofmt -s -w .` then `golangci-lint`) +2. **Run Tests:** `script/test` (runs `go test -race ./...`) +3. **Update Documentation:** `script/generate-docs` (if you modified MCP tools/toolsets) + +**These commands are FAST:** Lint ~1s, Tests ~1s (cached), Build ~1s + +### When Modifying MCP Tools/Endpoints + +If you change any MCP tool definitions or schemas: +1. Run tests with `UPDATE_TOOLSNAPS=true go test ./...` to update toolsnaps +2. Commit the updated `.snap` files in `pkg/github/__toolsnaps__/` +3. Run `script/generate-docs` to update README.md +4. Toolsnaps document API surface and ensure changes are intentional + +### Common Build Commands + +```bash +# Download dependencies (rarely needed - usually cached) +go mod download + +# Build the server binary +go build -v ./cmd/github-mcp-server + +# Run the server +./github-mcp-server stdio + +# Run specific package tests +go test ./pkg/github -v + +# Run specific test +go test ./pkg/github -run TestGetMe +``` + +## Project Structure + +### Directory Layout + +``` +. +├── cmd/ +│ ├── github-mcp-server/ # Main MCP server entry point (PRIMARY FOCUS) +│ └── mcpcurl/ # MCP testing utility (secondary - don't break it) +├── pkg/ # Public API packages +│ ├── github/ # GitHub API MCP tools implementation +│ │ └── __toolsnaps__/ # Tool schema snapshots (*.snap files) +│ ├── toolsets/ # Toolset configuration & management +│ ├── errors/ # Error handling utilities +│ ├── sanitize/ # HTML/content sanitization +│ ├── log/ # Logging utilities +│ ├── raw/ # Raw data handling +│ ├── buffer/ # Buffer utilities +│ └── translations/ # i18n translation support +├── internal/ # Internal implementation packages +│ ├── ghmcp/ # GitHub MCP server core logic +│ ├── githubv4mock/ # GraphQL API mocking for tests +│ ├── toolsnaps/ # Toolsnap validation system +│ └── profiler/ # Performance profiling +├── e2e/ # End-to-end tests (require GitHub PAT) +├── script/ # Build and maintenance scripts +├── docs/ # Documentation +├── .github/workflows/ # CI/CD workflows +└── [config files] # See below +``` + +### Key Configuration Files + +- **go.mod / go.sum:** Go module dependencies (Go 1.27.3+) +- **.golangci.yml:** Linter configuration (v2 format, ~15 linters enabled) +- **Dockerfile:** Multi-stage build (golang:1.27.3-alpine → distroless) +- **server.json:** MCP server metadata for registry +- **.goreleaser.yaml:** Release automation config +- **.gitignore:** Excludes bin/, dist/, vendor/, *.DS_Store, github-mcp-server binary + +### Important Scripts (script/ directory) + +- **script/lint** - Runs `gofmt` + `golangci-lint`. **MUST RUN** before committing +- **script/test** - Runs `go test -race ./...` (full test suite) +- **script/generate-docs** - Updates README.md tool documentation. Run after tool changes +- **script/licenses** - Updates third-party license files when dependencies change +- **script/licenses-check** - Validates license compliance (runs in CI) +- **script/get-me** - Quick test script for get_me tool +- **script/get-discussions** - Quick test for discussions +- **script/tag-release** - **NEVER USE THIS** - releases are managed separately + +## GitHub Workflows (CI/CD) + +All workflows run on push/PR unless noted. Located in `.github/workflows/`: + +1. **go.yml** - Build and test on ubuntu/windows/macos. Runs `script/test` and builds binary +2. **lint.yml** - Runs golangci-lint-action v2.5 (GitHub Action) with actions/setup-go stable +3. **docs-check.yml** - Verifies README.md is up-to-date by running generate-docs and checking git diff +4. **code-scanning.yml** - CodeQL security analysis for Go and GitHub Actions +5. **license-check.yml** - Runs `script/licenses-check` to validate compliance +6. **docker-publish.yml** - Publishes container image to ghcr.io +7. **goreleaser.yml** - Creates releases (main branch only) +8. **registry-releaser.yml** - Updates MCP registry + +**All of these must pass for PR merge.** If docs-check fails, run `script/generate-docs` and commit changes. + +## Testing Guidelines + +### Unit Tests + +- Use `testify` for assertions (`require` for critical checks, `assert` for non-blocking) +- Tests are in `*_test.go` files alongside implementation (internal tests, not `_test` package) +- Mock GitHub API with `go-github-mock` (REST) or `githubv4mock` (GraphQL) +- Test structure for tools: + 1. Test tool snapshot + 2. Verify critical schema properties (e.g., ReadOnly annotation) + 3. Table-driven behavioral tests + +### Toolsnaps (Tool Schema Snapshots) + +- Every MCP tool has a JSON schema snapshot in `pkg/github/__toolsnaps__/*.snap` +- Tests fail if current schema differs from snapshot (shows diff) +- To update after intentional changes: `UPDATE_TOOLSNAPS=true go test ./...` +- **MUST commit updated .snap files** - they document API changes +- Missing snapshots cause CI failure + +### End-to-End Tests + +- Located in `e2e/` directory with `e2e_test.go` +- **Require GitHub PAT token** - you usually cannot run these yourself +- Run with: `GITHUB_MCP_SERVER_E2E_TOKEN= go test -v --tags e2e ./e2e` +- Tests interact with live GitHub API via Docker container +- **Keep e2e tests updated when changing MCP tools** +- **Use only the e2e test style** when modifying tests in this directory +- For debugging: `GITHUB_MCP_SERVER_E2E_DEBUG=true` runs in-process (no Docker) + +## Code Style & Linting + +### Go Code Requirements + +- **gofmt with simplify flag (-s)** - Automatically run by `script/lint` +- **golangci-lint** with these linters enabled: + - bodyclose, gocritic, gosec, makezero, misspell, nakedret, revive + - errcheck, staticcheck, govet, ineffassign, unused +- Exclusions for: third_party/, builtin/, examples/, generated code + +### Go Naming Conventions + +- **Acronyms in identifiers:** Use `ID` not `Id`, `API` not `Api`, `URL` not `Url`, `HTTP` not `Http` +- Examples: `userID`, `getAPI`, `parseURL`, `HTTPClient` +- This applies to variable names, function names, struct fields, etc. + +### Code Patterns + +- **Keep changes minimal and focused** on the specific issue being addressed +- **Prefer clarity over cleverness** - code must be understandable by a wide audience +- **Atomic commits** - each commit should be a complete, logical change +- **Maintain or improve structure** - never degrade code organization +- Use table-driven tests for behavioral testing +- Comment sparingly - code should be self-documenting +- Follow standard Go conventions (Effective Go, Go proverbs) +- **Test changes thoroughly** before committing +- Export functions (capitalize) if they could be used by other repos as a library + +## Common Development Workflows + +### Adding a New MCP Tool + +1. Add tool implementation in `pkg/github/` (e.g., `foo_tools.go`) +2. Register tool in appropriate toolset in `pkg/github/` or `pkg/toolsets/` +3. Write unit tests following the tool test pattern +4. Run `UPDATE_TOOLSNAPS=true go test ./...` to create snapshot +5. Run `script/generate-docs` to update README +6. Run `script/lint` and `script/test` before committing +7. If e2e tests are relevant, update `e2e/e2e_test.go` using existing test style +8. Commit code + snapshots + README changes together + +### Fixing a Bug + +1. Write a failing test that reproduces the bug +2. Fix the bug with minimal changes +3. Verify test passes and existing tests still pass +4. Run `script/lint` and `script/test` +5. If tool schema changed, update toolsnaps (see above) + +### Updating Dependencies + +1. Update `go.mod` (e.g., `go get -u ./...` or manually) +2. Run `go mod tidy` +3. Run `script/licenses` to update license files +4. Run `script/test` to verify nothing broke +5. Commit go.mod, go.sum, and third-party-licenses* files + +## Common Errors & Solutions + +### "Documentation is out of date" in CI + +**Fix:** Run `script/generate-docs` and commit README.md changes + +### Toolsnap mismatch failures + +**Fix:** Run `UPDATE_TOOLSNAPS=true go test ./...` and commit updated .snap files + +### Lint failures + +**Fix:** Run `script/lint` locally - it will auto-format and show issues. Fix manually reported issues. + +### License check failures + +**Fix:** Run `script/licenses` to regenerate license files after dependency changes + +### Test failures after changing a tool + +**Likely causes:** +1. Forgot to update toolsnaps - run with `UPDATE_TOOLSNAPS=true` +2. Changed behavior broke existing tests - verify intent and fix tests +3. Schema change not reflected in test - update test expectations + +## Environment Variables + +- **GITHUB_PERSONAL_ACCESS_TOKEN** - Required for server operation and e2e tests +- **GITHUB_HOST** - For GitHub Enterprise Server (prefix with `https://`) +- **GITHUB_TOOLSETS** - Comma-separated toolset list (overrides --toolsets flag) +- **GITHUB_READ_ONLY** - Set to "1" for read-only mode +- **UPDATE_TOOLSNAPS** - Set to "true" when running tests to update snapshots +- **GITHUB_MCP_SERVER_E2E_TOKEN** - Token for e2e tests +- **GITHUB_MCP_SERVER_E2E_DEBUG** - Set to "true" for in-process e2e debugging + +## Key Files Reference + +### Root Directory Files +``` +.dockerignore - Docker build exclusions +.gitignore - Git exclusions (includes bin/, dist/, vendor/, binaries) +.golangci.yml - Linter configuration +.goreleaser.yaml - Release automation +CODE_OF_CONDUCT.md - Community guidelines +CONTRIBUTING.md - Contribution guide (fork, clone, test, lint workflow) +Dockerfile - Multi-stage Go build +LICENSE - MIT license +README.md - Main documentation (auto-generated sections) +SECURITY.md - Security policy +SUPPORT.md - Support resources +gemini-extension.json - Gemini CLI configuration +go.mod / go.sum - Go dependencies +server.json - MCP server registry metadata +``` + +### Main Entry Point + +`cmd/github-mcp-server/main.go` - Uses cobra for CLI, viper for config, supports: +- `stdio` command (default) - MCP stdio transport +- `generate-docs` command - Documentation generation +- Flags: --toolsets, --read-only, --gh-host, --log-file + +## Important Reminders + +1. **PRIMARY FOCUS:** The local stdio MCP server (github-mcp-server) - this is what you should work on and test with +2. **REMOTE SERVER:** Ignore remote server instructions when making code changes (unless specifically asked). This repo is used as a library by the remote server, so keep functions exported (capitalized) if they could be called by other repos, even if not needed internally. +3. **ALWAYS** trust these instructions first - only search if information is incomplete or incorrect +4. **NEVER** use `script/tag-release` or push tags +5. **NEVER** skip `script/lint` before committing Go code changes +6. **ALWAYS** update toolsnaps when changing MCP tool schemas +7. **ALWAYS** run `script/generate-docs` after modifying tools +8. For specific test files, use `go test ./path -run TestName` not full suite +9. E2E tests require PAT token - you likely cannot run them +10. Toolsnaps are API documentation - treat changes seriously +11. Build/test/lint are very fast (~1s each) - run frequently +12. CI failures for docs-check or license-check have simple fixes (run the script) +13. mcpcurl is secondary - don't break it, but it's not the priority \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 849e924be7..68c3a0ef2c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,52 +1,19 @@ -FROM node:26-alpine@sha256:e88a35be04478413b7c71c455cd9865de9b9360e1f43456be5951032d7ac1a66 AS ui-build -WORKDIR /app -COPY ui/package*.json ./ui/ -RUN cd ui && npm ci -COPY ui/ ./ui/ -# Create output directory and build - vite outputs directly to pkg/github/ui_dist/ -RUN mkdir -p ./pkg/github/ui_dist && \ - cd ui && npm run build - -FROM golang:1.27.3-alpine@sha256:f2c872bcee949b7be9c490efd02b48a8a2fbf947cdf533f1c58525ec9d8170fd AS build -ARG VERSION="dev" - -# Set the working directory -WORKDIR /build - -# Install git -RUN --mount=type=cache,target=/var/cache/apk \ - apk add git - -# Copy source code (including ui_dist placeholder) -COPY . . - -# Copy built UI assets over the placeholder -COPY --from=ui-build /app/pkg/github/ui_dist/* ./pkg/github/ui_dist/ - -# Build the server -# OAuth credentials are injected via build secrets so they are not baked into image history; the values are public in practice but kept out of layers. -RUN --mount=type=cache,target=/go/pkg/mod \ - --mount=type=cache,target=/root/.cache/go-build \ - --mount=type=secret,id=oauth_client_id \ - --mount=type=secret,id=oauth_client_secret \ - export OAUTH_CLIENT_ID="$(cat /run/secrets/oauth_client_id 2>/dev/null || echo '')" && \ - export OAUTH_CLIENT_SECRET="$(cat /run/secrets/oauth_client_secret 2>/dev/null || echo '')" && \ - CGO_ENABLED=0 go build -ldflags="-s -w -X main.version=${VERSION} -X main.commit=$(git rev-parse HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X github.com/github/github-mcp-server/v2/internal/buildinfo.OAuthClientID=${OAUTH_CLIENT_ID} -X github.com/github/github-mcp-server/v2/internal/buildinfo.OAuthClientSecret=${OAUTH_CLIENT_SECRET}" \ - -o /bin/github-mcp-server ./cmd/github-mcp-server - -# Make a stage to run the app -FROM gcr.io/distroless/base-debian12@sha256:fabbf1c0c357a3d42550111351daed089b20a2c954df13ee2fcff60602515e84 - -# Add required MCP server annotation -LABEL io.modelcontextprotocol.server.name="io.github.github/github-mcp-server" - -# Set the working directory -WORKDIR /server -# Copy the binary from the build stage -COPY --from=build /bin/github-mcp-server . -# Expose the default port -EXPOSE 8082 -# Set the entrypoint to the server binary -ENTRYPOINT ["/server/github-mcp-server"] -# Default arguments for ENTRYPOINT -CMD ["stdio"] +# GCC support can be specified at major, minor, or micro version +# (e.g. 8, 8.2 or 8.2.0). +# See https://hub.docker.com/r/library/gcc/ for all supported GCC +# tags from Docker Hub. +# See https://docs.docker.com/samples/library/gcc/ for more on how to use this image +FROM gcc:14-alpine + +# These commands copy your files into the specified directory in the image +# and set that as the working location +COPY . /usr/src/myapp +WORKDIR /usr/src/myapp + +# This command compiles your app using GCC, adjust for your source code +RUN g++ -o myapp main.cpp + +# This command runs your application, comment out this line to compile only +CMD ["./myapp"] + +LABEL Name=githubmcpserver Version=0.0.1 diff --git a/compose.debug.yaml b/compose.debug.yaml new file mode 100644 index 0000000000..233e76f193 --- /dev/null +++ b/compose.debug.yaml @@ -0,0 +1,6 @@ +services: + githubmcpserver: + image: githubmcpserver + build: + context: . + dockerfile: ./Dockerfil diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000000..d57cd12e73 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,6 @@ +services: + githubmcpserver: + image: githubmcpserver + build: + context: . + dockerfile: ./Dockerfile diff --git a/pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap b/pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap index 157857d3d7..765efbe508 100644 --- a/pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap +++ b/pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap @@ -60,4 +60,5 @@ "object" ] } -} \ No newline at end of file +delete_pending_pull_request_review +Delete any unfinsed WORKFLOW