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.24+ (~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 mark3labs/mcp-go for MCP protocol, google/go-github for GitHub API

-**Size:**~60MB repository, 70 Go files

**ALWAYS run these commands in this exact order before using report_progress or finishing work:**

1.**Format Code:**`script/lint` (this 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

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

go mod download

go build -v ./cmd/github-mcp-server

./github-mcp-server stdio

gotest ./pkg/github -v

gotest ./pkg/github -run TestGetMe

-**go.mod / go.sum:** Go module dependencies (Go 1.24.0+)

-**.golangci.yml:** Linter configuration (v2 format,~15 linters enabled)

-**Dockerfile:** Multi-stage build (golang:1.25.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

-**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

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 v2.5 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.

- 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

- 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

- 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=<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)

-**gofmt with simplify flag (-s)** - Automatically run by`script/lint`

-**golangci-lint v2.5.0** with these linters enabled:

- bodyclose, gocritic, gosec, makezero, misspell, nakedret, revive

- errcheck, staticcheck, govet, ineffassign, unused

- Exclusions for: third_party/, builtin/, examples/, generated code

-**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.

-**Keep changes minimal and focused** on the specific issue being addressed

- Prefer explicit over clever code

- 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

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

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)

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

**Fix:** Run`script/generate-docs` and commit README.md changes

**Fix:** Run`UPDATE_TOOLSNAPS=true go test ./...` and commit updated .snap files

**Fix:** Run`script/lint` locally - it will auto-format and show issues. Fix manually reported issues.

**Fix:** Run`script/licenses` to regenerate license files after dependency changes

**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

-**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

-**GITHUB_DYNAMIC_TOOLSETS** - Set to "1" for dynamic toolset discovery

-**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

`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, --dynamic-toolsets, --gh-host, --log-file

1.**PRIMARY FOCUS:** The local stdio MCP server (github-mcp-server) - this is what you should work on and test with

2.**ALWAYS** trust these instructions first - only search if information is incomplete or incorrect

3.**NEVER** use`script/tag-release` or push tags

4.**NEVER** skip`script/lint` before committing Go code changes

5.**ALWAYS** update toolsnaps when changing MCP tool schemas

6.**ALWAYS** run`script/generate-docs` after modifying tools

7. For specific test files, use`go test ./path -run TestName` not full suite

8. E2E tests require PAT token - you likely cannot run them

9. Toolsnaps are API documentation - treat changes seriously

10. Build/test/lint are very fast (~1s each) - run frequently

11. CI failures for docs-check or license-check have simple fixes (run the script)

12. mcpcurl is secondary - don't break it, but it's not the priority