chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1 @@
|
||||
* @github/github-mcp-server
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: "\U0001F41B Bug report"
|
||||
about: Report a bug or unexpected behavior while using GitHub MCP Server
|
||||
title: ''
|
||||
labels: bug
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
### Describe the bug
|
||||
|
||||
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
|
||||
|
||||
### Steps to reproduce the behavior
|
||||
|
||||
1. Type this '...'
|
||||
2. View the output '....'
|
||||
3. See error
|
||||
|
||||
### Expected vs actual behavior
|
||||
|
||||
A clear and concise description of what you expected to happen and what actually happened.
|
||||
|
||||
### Logs
|
||||
|
||||
Paste any available logs. Redact if needed.
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
name: "⭐ Submit a feature request"
|
||||
about: Surface a feature or problem that you think should be solved
|
||||
title: ''
|
||||
labels: enhancement
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
### Describe the feature or problem you’d like to solve
|
||||
|
||||
A clear and concise description of what the feature or problem is.
|
||||
|
||||
### Proposed solution
|
||||
|
||||
How will it benefit GitHub MCP Server and its users?
|
||||
|
||||
### Example prompts or workflows (for tools/toolsets only)
|
||||
|
||||
If it's a new tool or improvement, share 3–5 example prompts or workflows it would enable. Just enough detail to show the value. Clear, valuable use cases are more likely to get approved.
|
||||
|
||||
### Additional context
|
||||
|
||||
Add any other context like screenshots or mockups are helpful, if applicable.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
name: Insiders Feedback
|
||||
about: Give feedback related to a GitHub MCP Server Insiders feature
|
||||
title: "Insiders Feedback: "
|
||||
labels: ''
|
||||
assignees: ''
|
||||
|
||||
---
|
||||
|
||||
Version: Insiders
|
||||
|
||||
Feature:
|
||||
|
||||
Feedback:
|
||||
@@ -0,0 +1,39 @@
|
||||
name: Build UI
|
||||
description: Restore cached UI HTML artifacts, or set up Node and run script/build-ui on cache miss.
|
||||
|
||||
runs:
|
||||
using: composite
|
||||
steps:
|
||||
- name: Cache UI artifacts
|
||||
id: cache-ui
|
||||
uses: actions/cache@v5
|
||||
with:
|
||||
path: |
|
||||
pkg/github/ui_dist/get-me.html
|
||||
pkg/github/ui_dist/issue-write.html
|
||||
pkg/github/ui_dist/pr-write.html
|
||||
pkg/github/ui_dist/pr-edit.html
|
||||
key: ui-dist-v2-${{ hashFiles('ui/package-lock.json', 'ui/package.json', 'ui/index.html', 'ui/tsconfig*.json', 'ui/vite.config.ts', 'ui/src/**', 'ui/scripts/**') }}
|
||||
enableCrossOsArchive: true
|
||||
|
||||
- name: Set up Node.js
|
||||
if: steps.cache-ui.outputs.cache-hit != 'true'
|
||||
uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: "20"
|
||||
cache: npm
|
||||
cache-dependency-path: ui/package-lock.json
|
||||
|
||||
- name: Build UI
|
||||
if: steps.cache-ui.outputs.cache-hit != 'true'
|
||||
shell: bash
|
||||
run: script/build-ui
|
||||
|
||||
- name: Report UI cache status
|
||||
shell: bash
|
||||
run: |
|
||||
if [ "${{ steps.cache-ui.outputs.cache-hit }}" = "true" ]; then
|
||||
echo "UI artifacts restored from cache (skipped build)."
|
||||
else
|
||||
echo "UI artifacts rebuilt from source."
|
||||
fi
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: go-sdk-tool-migrator
|
||||
description: Agent specializing in migrating MCP tools from mark3labs/mcp-go to modelcontextprotocol/go-sdk
|
||||
---
|
||||
|
||||
# Go SDK Tool Migrator Agent
|
||||
|
||||
You are a specialized agent designed to assist developers in migrating MCP tools from the mark3labs/mcp-go library to the modelcontextprotocol/go-sdk. Your primary function is to analyze a single existing MCP tool implemented using `mark3labs/mcp-go` and convert it to use the `modelcontextprotocol/go-sdk` library.
|
||||
|
||||
## Migration Process
|
||||
|
||||
You should focus on ONLY the toolset you are asked to migrate and its corresponding test file. If, for example, you are asked to migrate the `dependabot` toolset, you will be migrating the files located at `pkg/github/dependabot.go` and `pkg/github/dependabot_test.go`. If there are additional tests or helper functions that fail to work with the new SDK, you should inform me of these issues so that I can address them, or instruct you on how to proceed.
|
||||
|
||||
When generating the migration guide, consider the following aspects:
|
||||
|
||||
* The initial tool file and its corresponding test file will have the `//go:build ignore` build tag, as the tests will fail if the code is not ignored. The `ignore` build tag should be removed before work begins.
|
||||
* The import for `github.com/mark3labs/mcp-go/mcp` should be changed to `github.com/modelcontextprotocol/go-sdk/mcp`
|
||||
* The return type for the tool constructor function should be updated from `mcp.Tool, server.ToolHandlerFunc` to `(mcp.Tool, mcp.ToolHandlerFor[map[string]any, any])`.
|
||||
* The tool handler function signature should be updated to use generics, changing from `func(ctx context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error)` to `func(context.Context, *mcp.CallToolRequest, map[string]any) (*mcp.CallToolResult, any, error)`.
|
||||
* The `RequiredParam`, `RequiredInt`, `RequiredBigInt`, `OptionalParamOK`, `OptionalParam`, `OptionalIntParam`, `OptionalIntParamWithDefault`, `OptionalBoolParamWithDefault`, `OptionalStringArrayParam`, `OptionalBigIntArrayParam` and `OptionalCursorPaginationParams` functions should be changed to use the tool arguments that are now passed as a map in the tool handler function, rather than extracting them from the `mcp.CallToolRequest`.
|
||||
* `mcp.NewToolResultText`, `mcp.NewToolResultError`, `mcp.NewToolResultErrorFromErr` and `mcp.NewToolResultResource` no longer available in `modelcontextprotocol/go-sdk`. There are a few helper functions available in `pkg/utils/result.go` that can be used to replace these, in the `utils` package.
|
||||
|
||||
### Schema Changes
|
||||
|
||||
The biggest change when migrating MCP tools from mark3labs/mcp-go to modelcontextprotocol/go-sdk is the way input and output schemas are defined and handled. In `mark3labs/mcp-go`, input and output schemas were often defined using a DSL provided by the library. In `modelcontextprotocol/go-sdk`, schemas are defined using `jsonschema.Schema` structures using `github.com/google/jsonschema-go`, which are more verbose.
|
||||
|
||||
When migrating a tool, you will need to convert the existing schema definitions to JSON Schema format. This involves defining the properties, types, and any validation rules using the JSON Schema specification.
|
||||
|
||||
#### Example Schema Guide
|
||||
|
||||
If we take an example of a tool that has the following input schema in mark3labs/mcp-go:
|
||||
|
||||
```go
|
||||
...
|
||||
return mcp.NewTool(
|
||||
"list_dependabot_alerts",
|
||||
mcp.WithDescription(t("TOOL_LIST_DEPENDABOT_ALERTS_DESCRIPTION", "List dependabot alerts in a GitHub repository.")),
|
||||
mcp.WithToolAnnotation(mcp.ToolAnnotation{
|
||||
Title: t("TOOL_LIST_DEPENDABOT_ALERTS_USER_TITLE", "List dependabot alerts"),
|
||||
ReadOnlyHint: ToBoolPtr(true),
|
||||
}),
|
||||
mcp.WithString("owner",
|
||||
mcp.Required(),
|
||||
mcp.Description("The owner of the repository."),
|
||||
),
|
||||
mcp.WithString("repo",
|
||||
mcp.Required(),
|
||||
mcp.Description("The name of the repository."),
|
||||
),
|
||||
mcp.WithString("state",
|
||||
mcp.Description("Filter dependabot alerts by state. Defaults to open"),
|
||||
mcp.DefaultString("open"),
|
||||
mcp.Enum("open", "fixed", "dismissed", "auto_dismissed"),
|
||||
),
|
||||
mcp.WithString("severity",
|
||||
mcp.Description("Filter dependabot alerts by severity"),
|
||||
mcp.Enum("low", "medium", "high", "critical"),
|
||||
),
|
||||
),
|
||||
...
|
||||
```
|
||||
|
||||
The corresponding input schema in modelcontextprotocol/go-sdk would look like this:
|
||||
|
||||
```go
|
||||
...
|
||||
return mcp.Tool{
|
||||
Name: "list_dependabot_alerts",
|
||||
Description: t("TOOL_LIST_DEPENDABOT_ALERTS_DESCRIPTION", "List dependabot alerts in a GitHub repository."),
|
||||
Annotations: &mcp.ToolAnnotations{
|
||||
Title: t("TOOL_LIST_DEPENDABOT_ALERTS_USER_TITLE", "List dependabot alerts"),
|
||||
ReadOnlyHint: true,
|
||||
},
|
||||
InputSchema: &jsonschema.Schema{
|
||||
Type: "object",
|
||||
Properties: map[string]*jsonschema.Schema{
|
||||
"owner": {
|
||||
Type: "string",
|
||||
Description: "The owner of the repository.",
|
||||
},
|
||||
"repo": {
|
||||
Type: "string",
|
||||
Description: "The name of the repository.",
|
||||
},
|
||||
"state": {
|
||||
Type: "string",
|
||||
Description: "Filter dependabot alerts by state. Defaults to open",
|
||||
Enum: []any{"open", "fixed", "dismissed", "auto_dismissed"},
|
||||
Default: "open",
|
||||
},
|
||||
"severity": {
|
||||
Type: "string",
|
||||
Description: "Filter dependabot alerts by severity",
|
||||
Enum: []any{"low", "medium", "high", "critical"},
|
||||
},
|
||||
},
|
||||
Required: []string{"owner", "repo"},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Tests
|
||||
|
||||
After migrating the tool code and test file, ensure that all tests pass successfully. If any tests fail, review the error messages and adjust the migrated code as necessary to resolve any issues. If you encounter any challenges or need further assistance during the migration process, please let me know.
|
||||
|
||||
At the end of your changes, you will continue to have an issue with the `toolsnaps` tests, these validate that the schema has not changed unexpectedly. You can update the snapshots by setting `UPDATE_TOOLSNAPS=true` before running the tests, e.g.:
|
||||
|
||||
```bash
|
||||
UPDATE_TOOLSNAPS=true go test ./...
|
||||
```
|
||||
|
||||
You should however, only update the toolsnaps after confirming that the schema changes are intentional and correct. Some schema changes are unavoidable, such as argument ordering, however the schemas themselves should remain logically equivalent.
|
||||
@@ -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.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 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.24.0+)
|
||||
- **.golangci.yml:** Linter configuration (v2 format, ~15 linters enabled)
|
||||
- **Dockerfile:** Multi-stage build (golang:1.25.8-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=<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
|
||||
@@ -0,0 +1,19 @@
|
||||
# To get started with Dependabot version updates, you'll need to specify which
|
||||
# package ecosystems to update and where the package manifests are located.
|
||||
# Please see the documentation for all configuration options:
|
||||
# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
|
||||
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "gomod"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
- package-ecosystem: "docker"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
@@ -0,0 +1,13 @@
|
||||
# GitHub MCP Server dependencies
|
||||
|
||||
The following open source dependencies are used to build the [github/github-mcp-server][] GitHub Model Context Protocol Server.
|
||||
|
||||
## Go Packages
|
||||
|
||||
Some packages may only be included on certain architectures or operating systems.
|
||||
|
||||
{{ range . }}
|
||||
- [{{.Name}}](https://pkg.go.dev/{{.Name}}) ([{{.LicenseName}}]({{.LicenseURL}}))
|
||||
{{- end }}
|
||||
|
||||
[github/github-mcp-server]: https://github.com/github/github-mcp-server
|
||||
@@ -0,0 +1,44 @@
|
||||
messages:
|
||||
- role: system
|
||||
content: |
|
||||
You are a triage assistant for the GitHub MCP Server repository. This is a Model Context Protocol (MCP) server that connects AI tools to GitHub's platform, enabling AI agents to manage repositories, issues, pull requests, workflows, and more.
|
||||
|
||||
Your job is to analyze bug reports and assess their completeness.
|
||||
|
||||
**CRITICAL: Detect unfilled templates**
|
||||
- Flag issues containing unmodified template text like "A clear and concise description of what the bug is"
|
||||
- Flag placeholder values like "Type this '...'" or "View the output '....'" that haven't been replaced
|
||||
- Flag generic/meaningless titles (e.g., random words, test content)
|
||||
- These are ALWAYS "Missing Details" even if the template structure is present
|
||||
|
||||
Analyze the issue for these key elements:
|
||||
1. Clear description of the problem (not template text)
|
||||
2. Affected version (from running `docker run -i --rm ghcr.io/github/github-mcp-server ./github-mcp-server --version`)
|
||||
3. Steps to reproduce the behavior (actual steps, not placeholders)
|
||||
4. Expected vs actual behavior (real descriptions, not template text)
|
||||
5. Relevant logs (if applicable)
|
||||
|
||||
Provide ONE of these assessments:
|
||||
|
||||
### AI Assessment: Ready for Review
|
||||
Use when the bug report has actual information in required fields and can be triaged by a maintainer.
|
||||
|
||||
### AI Assessment: Missing Details
|
||||
Use when:
|
||||
- Template text has not been replaced with actual content
|
||||
- Critical information is missing (no reproduction steps, no version info, unclear problem description)
|
||||
- The title is meaningless or spam-like
|
||||
- Placeholder text remains in any section
|
||||
|
||||
When marking as Missing Details, recommend adding the "waiting-for-reply" label.
|
||||
|
||||
### AI Assessment: Unsure
|
||||
Use when you cannot determine the completeness of the report.
|
||||
|
||||
After your assessment header, provide a brief explanation of your rating.
|
||||
If details are missing, be specific about which sections contain template text or need actual information.
|
||||
- role: user
|
||||
content: "{{input}}"
|
||||
model: openai/gpt-4o-mini
|
||||
modelParameters:
|
||||
max_tokens: 500
|
||||
@@ -0,0 +1,54 @@
|
||||
messages:
|
||||
- role: system
|
||||
content: |
|
||||
You are a triage assistant for the GitHub MCP Server repository. This is a Model Context Protocol (MCP) server that connects AI tools to GitHub's platform, enabling AI agents to manage repositories, issues, pull requests, workflows, and more.
|
||||
|
||||
Your job is to analyze new issues and help categorize them.
|
||||
|
||||
**CRITICAL: Detect invalid or incomplete submissions**
|
||||
- Flag issues with unmodified template text (e.g., "A clear and concise description...")
|
||||
- Flag placeholder values that haven't been replaced (e.g., "Type this '...'", "....", "XXX")
|
||||
- Flag meaningless, spam-like, or test titles (e.g., random words, nonsensical content)
|
||||
- Flag empty or nearly empty issues
|
||||
- These are ALWAYS "Missing Details" or "Invalid" depending on severity
|
||||
|
||||
Analyze the issue to determine:
|
||||
1. Is this a bug report, feature request, question, documentation issue, or something else?
|
||||
2. Is the issue clear and well-described with actual content (not template text)?
|
||||
3. Does it contain enough information for maintainers to act on?
|
||||
4. Is this potentially spam, a test issue, or completely invalid?
|
||||
|
||||
Provide ONE of these assessments:
|
||||
|
||||
### AI Assessment: Ready for Review
|
||||
Use when the issue is clear, well-described with actual content, and contains enough context for maintainers to understand and act on it.
|
||||
|
||||
### AI Assessment: Missing Details
|
||||
Use when:
|
||||
- Template text has not been replaced with actual content
|
||||
- The issue is unclear or lacks context
|
||||
- Critical information is missing to make it actionable
|
||||
- The title is vague but the issue seems legitimate
|
||||
|
||||
When marking as Missing Details, recommend adding the "waiting-for-reply" label.
|
||||
|
||||
### AI Assessment: Invalid
|
||||
Use when:
|
||||
- The issue appears to be spam or test content
|
||||
- The title is completely meaningless and body has no useful information
|
||||
- This doesn't relate to the GitHub MCP Server project at all
|
||||
|
||||
When marking as Invalid, recommend adding the "invalid" label and consider closing.
|
||||
|
||||
### AI Assessment: Unsure
|
||||
Use when you cannot determine the nature or completeness of the issue.
|
||||
|
||||
After your assessment header, provide a brief explanation including:
|
||||
- What type of issue this appears to be (bug, feature request, question, invalid, etc.)
|
||||
- Which specific sections contain template text or need actual information
|
||||
- What additional information might be helpful if any
|
||||
- role: user
|
||||
content: "{{input}}"
|
||||
model: openai/gpt-4o-mini
|
||||
modelParameters:
|
||||
max_tokens: 500
|
||||
@@ -0,0 +1,51 @@
|
||||
<!--
|
||||
Copilot: Fill all sections. Prefer short, concrete answers.
|
||||
If a checkbox is selected, add a brief explanation.
|
||||
-->
|
||||
|
||||
## Summary
|
||||
<!-- In 1–2 sentences: what does this PR do? -->
|
||||
|
||||
## Why
|
||||
<!-- Why is this change needed? Link issues or discussions. -->
|
||||
Fixes #
|
||||
|
||||
## What changed
|
||||
<!-- Bullet list of concrete changes. -->
|
||||
-
|
||||
-
|
||||
|
||||
## MCP impact
|
||||
<!-- Select one or more. If selected, add 1–2 sentences. -->
|
||||
- [ ] No tool or API changes
|
||||
- [ ] Tool schema or behavior changed
|
||||
- [ ] New tool added
|
||||
|
||||
## Prompts tested (tool changes only)
|
||||
<!-- If you changed or added tools, list example prompts you tested. -->
|
||||
<!-- Include prompts that trigger the tool and describe the use case. -->
|
||||
<!-- Example: "List all open issues in the repo assigned to me" -->
|
||||
-
|
||||
|
||||
## Security / limits
|
||||
<!-- Select if relevant. Add a short note if checked. -->
|
||||
- [ ] No security or limits impact
|
||||
- [ ] Auth / permissions considered
|
||||
- [ ] Data exposure, filtering, or token/size limits considered
|
||||
|
||||
## Tool renaming
|
||||
- [ ] I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
|
||||
- [ ] I have added the new tool aliases in `deprecated_tool_aliases.go`
|
||||
- [ ] I am not renaming tools as part of this PR
|
||||
|
||||
Note: if you're renaming tools, you *must* add the tool aliases. For more information on how to do so, please refer to the [official docs](https://github.com/github/github-mcp-server/blob/main/docs/tool-renaming.md).
|
||||
|
||||
## Lint & tests
|
||||
<!-- Check what you ran. If not run, explain briefly. -->
|
||||
- [ ] Linted locally with `./script/lint`
|
||||
- [ ] Tested locally with `./script/test`
|
||||
|
||||
## Docs
|
||||
|
||||
- [ ] Not needed
|
||||
- [ ] Updated (README / docs / examples)
|
||||
@@ -0,0 +1,27 @@
|
||||
name: AI Issue Assessment
|
||||
|
||||
on:
|
||||
issues:
|
||||
types: [opened, labeled]
|
||||
|
||||
jobs:
|
||||
ai-issue-assessment:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
issues: write
|
||||
models: read
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Run AI assessment
|
||||
uses: github/ai-assessment-comment-labeler@e3bedc38cfffa9179fe4cee8f7ecc93bffb3fee7 # v1.0.1
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
ai_review_label: "request ai review"
|
||||
issue_number: ${{ github.event.issue.number }}
|
||||
issue_body: ${{ github.event.issue.body }}
|
||||
prompts_directory: ".github/prompts"
|
||||
labels_to_prompts_mapping: "bug,bug-report-review.prompt.yml|default,default-issue-review.prompt.yml"
|
||||
@@ -0,0 +1,28 @@
|
||||
name: Close inactive issues
|
||||
on:
|
||||
schedule:
|
||||
- cron: "30 8 * * *"
|
||||
|
||||
jobs:
|
||||
close-issues:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
PR_DAYS_BEFORE_STALE: 30
|
||||
PR_DAYS_BEFORE_CLOSE: 60
|
||||
PR_STALE_LABEL: stale
|
||||
permissions:
|
||||
issues: write
|
||||
pull-requests: write
|
||||
steps:
|
||||
- uses: actions/stale@v10
|
||||
with:
|
||||
days-before-issue-stale: ${{ env.PR_DAYS_BEFORE_STALE }}
|
||||
days-before-issue-close: ${{ env.PR_DAYS_BEFORE_CLOSE }}
|
||||
stale-issue-label: ${{ env.PR_STALE_LABEL }}
|
||||
stale-issue-message: "This issue is stale because it has been open for ${{ env.PR_DAYS_BEFORE_STALE }} days with no activity. Leave a comment to avoid closing this issue in ${{ env.PR_DAYS_BEFORE_CLOSE }} days."
|
||||
close-issue-message: "This issue was closed because it has been inactive for ${{ env.PR_DAYS_BEFORE_CLOSE }} days since being marked as stale."
|
||||
days-before-pr-stale: ${{ env.PR_DAYS_BEFORE_STALE }}
|
||||
days-before-pr-close: ${{ env.PR_DAYS_BEFORE_STALE }}
|
||||
# Start with the oldest items first
|
||||
ascending: true
|
||||
repo-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -0,0 +1,103 @@
|
||||
name: "CodeQL"
|
||||
run-name: ${{ github.event.inputs.code_scanning_run_name }}
|
||||
on: [push, pull_request, workflow_dispatch]
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
CODE_SCANNING_REF: ${{ github.event.inputs.code_scanning_ref }}
|
||||
CODE_SCANNING_BASE_BRANCH: ${{ github.event.inputs.code_scanning_base_branch }}
|
||||
CODE_SCANNING_IS_ANALYZING_DEFAULT_BRANCH: ${{ github.event.inputs.code_scanning_is_analyzing_default_branch }}
|
||||
|
||||
jobs:
|
||||
analyze:
|
||||
name: Analyze (${{ matrix.language }})
|
||||
# Only run on the main repository, not on forks
|
||||
if: github.repository == 'github/github-mcp-server'
|
||||
runs-on: ${{ fromJSON(matrix.runner) }}
|
||||
permissions:
|
||||
actions: read
|
||||
contents: read
|
||||
packages: read
|
||||
security-events: write
|
||||
continue-on-error: false
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- language: actions
|
||||
category: /language:actions
|
||||
build-mode: none
|
||||
runner: '["ubuntu-22.04"]'
|
||||
- language: go
|
||||
category: /language:go
|
||||
build-mode: autobuild
|
||||
runner: '["ubuntu-22.04"]'
|
||||
- language: javascript
|
||||
category: /language:javascript
|
||||
build-mode: none
|
||||
runner: '["ubuntu-22.04"]'
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Initialize CodeQL
|
||||
uses: github/codeql-action/init@v4
|
||||
with:
|
||||
languages: ${{ matrix.language }}
|
||||
build-mode: ${{ matrix.build-mode }}
|
||||
dependency-caching: ${{ runner.environment == 'github-hosted' }}
|
||||
queries: "" # Default query suite
|
||||
packs: github/ccr-${{ matrix.language }}-queries
|
||||
config: |
|
||||
paths-ignore:
|
||||
- third-party
|
||||
- third-party-licenses.*.md
|
||||
default-setup:
|
||||
org:
|
||||
model-packs: [ ${{ github.event.inputs.code_scanning_codeql_packs }} ]
|
||||
threat-models: [ ]
|
||||
- name: Setup proxy for registries
|
||||
id: proxy
|
||||
uses: github/codeql-action/start-proxy@v4
|
||||
with:
|
||||
registries_credentials: ${{ secrets.GITHUB_REGISTRIES_PROXY }}
|
||||
language: ${{ matrix.language }}
|
||||
|
||||
- name: Configure
|
||||
uses: github/codeql-action/resolve-environment@v4
|
||||
id: resolve-environment
|
||||
with:
|
||||
language: ${{ matrix.language }}
|
||||
- name: Setup Go
|
||||
uses: actions/setup-go@v6
|
||||
if: matrix.language == 'go' && fromJSON(steps.resolve-environment.outputs.environment).configuration.go.version
|
||||
with:
|
||||
go-version: ${{ fromJSON(steps.resolve-environment.outputs.environment).configuration.go.version }}
|
||||
cache: false
|
||||
|
||||
- name: Set up Node.js (for JavaScript CodeQL)
|
||||
if: matrix.language == 'javascript'
|
||||
uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version: "20"
|
||||
cache: "npm"
|
||||
cache-dependency-path: ui/package-lock.json
|
||||
|
||||
- name: Build UI
|
||||
if: matrix.language == 'go'
|
||||
uses: ./.github/actions/build-ui
|
||||
|
||||
- name: Autobuild
|
||||
uses: github/codeql-action/autobuild@v4
|
||||
|
||||
- name: Perform CodeQL Analysis
|
||||
uses: github/codeql-action/analyze@v4
|
||||
env:
|
||||
CODEQL_PROXY_HOST: ${{ steps.proxy.outputs.proxy_host }}
|
||||
CODEQL_PROXY_PORT: ${{ steps.proxy.outputs.proxy_port }}
|
||||
CODEQL_PROXY_CA_CERTIFICATE: ${{ steps.proxy.outputs.proxy_ca_certificate }}
|
||||
with:
|
||||
category: ${{ matrix.category }}
|
||||
@@ -0,0 +1,138 @@
|
||||
name: Docker
|
||||
|
||||
# This workflow uses actions that are not certified by GitHub.
|
||||
# They are provided by a third-party and are governed by
|
||||
# separate terms of service, privacy policy, and support
|
||||
# documentation.
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: "27 0 * * *"
|
||||
push:
|
||||
branches: ["main", "next"]
|
||||
# Publish semver tags as releases.
|
||||
tags: ["v*.*.*"]
|
||||
pull_request:
|
||||
branches: ["main", "next"]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
description:
|
||||
required: false
|
||||
description: "Description of the run."
|
||||
type: string
|
||||
default: "Manual run"
|
||||
|
||||
env:
|
||||
# Use docker.io for Docker Hub if empty
|
||||
REGISTRY: ghcr.io
|
||||
# github.repository as <account>/<repo>
|
||||
IMAGE_NAME: ${{ github.repository }}
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest-xl
|
||||
permissions:
|
||||
contents: read
|
||||
packages: write
|
||||
# This is used to complete the identity challenge
|
||||
# with sigstore/fulcio when running outside of PRs.
|
||||
id-token: write
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v7
|
||||
|
||||
# Install the cosign tool except on PR
|
||||
# https://github.com/sigstore/cosign-installer
|
||||
- name: Install cosign
|
||||
if: github.event_name != 'pull_request'
|
||||
uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 #v4.1.2
|
||||
with:
|
||||
cosign-release: "v2.2.4"
|
||||
|
||||
# Set up BuildKit Docker 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@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
|
||||
|
||||
# Login against a Docker registry except on PR
|
||||
# https://github.com/docker/login-action
|
||||
- name: Log into registry ${{ env.REGISTRY }}
|
||||
if: github.event_name != 'pull_request'
|
||||
uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.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
|
||||
id: meta
|
||||
uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
|
||||
with:
|
||||
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
|
||||
tags: |
|
||||
type=schedule
|
||||
type=ref,event=branch
|
||||
type=ref,event=tag
|
||||
type=ref,event=pr
|
||||
type=semver,pattern={{version}}
|
||||
type=semver,pattern={{major}}.{{minor}}
|
||||
type=semver,pattern={{major}}
|
||||
type=sha
|
||||
type=edge
|
||||
# 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
|
||||
uses: actions/cache@v5
|
||||
with:
|
||||
path: go-build-cache
|
||||
key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}
|
||||
|
||||
- name: Inject go-build-cache
|
||||
uses: reproducible-containers/buildkit-cache-dance@5422eac04292c961a382e0f584ea0f03ad9da723 # v3.4.0
|
||||
with:
|
||||
cache-map: |
|
||||
{
|
||||
"go-build-cache/apk": "/var/cache/apk",
|
||||
"go-build-cache/pkg": "/go/pkg/mod",
|
||||
"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
|
||||
id: build-and-push
|
||||
uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
|
||||
with:
|
||||
context: .
|
||||
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
|
||||
platforms: linux/amd64,linux/arm64
|
||||
build-args: |
|
||||
VERSION=${{ github.ref_name }}
|
||||
secrets: |
|
||||
oauth_client_id=${{ secrets.OAUTH_CLIENT_ID }}
|
||||
oauth_client_secret=${{ secrets.OAUTH_CLIENT_SECRET }}
|
||||
|
||||
# Sign the resulting Docker image digest except on PRs.
|
||||
# This will only write to the public Rekor transparency log when the Docker
|
||||
# repository is public to avoid leaking data. If you would like to publish
|
||||
# transparency data even for private images, pass --force to cosign below.
|
||||
# https://github.com/sigstore/cosign
|
||||
- name: Sign the published Docker image
|
||||
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
|
||||
TAGS: ${{ steps.meta.outputs.tags }}
|
||||
DIGEST: ${{ steps.build-and-push.outputs.digest }}
|
||||
# This step uses the identity token to provision an ephemeral certificate
|
||||
# against the sigstore community Fulcio instance.
|
||||
run: echo "${TAGS}" | xargs -I {} cosign sign --yes {}@${DIGEST}
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
name: Documentation Check
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
docs-check:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Build UI
|
||||
uses: ./.github/actions/build-ui
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version-file: 'go.mod'
|
||||
|
||||
- name: Build docs generator
|
||||
run: go build -o github-mcp-server ./cmd/github-mcp-server
|
||||
|
||||
- name: Generate documentation
|
||||
run: ./github-mcp-server generate-docs
|
||||
|
||||
- name: Check for documentation changes
|
||||
run: |
|
||||
if ! git diff --exit-code README.md; then
|
||||
echo "❌ Documentation is out of date!"
|
||||
echo ""
|
||||
echo "The generated documentation differs from what's committed."
|
||||
echo "Please run the following command to update the documentation:"
|
||||
echo ""
|
||||
echo " go run ./cmd/github-mcp-server generate-docs"
|
||||
echo ""
|
||||
echo "Then commit the changes."
|
||||
echo ""
|
||||
echo "Changes detected:"
|
||||
git diff README.md
|
||||
exit 1
|
||||
else
|
||||
echo "✅ Documentation is up to date!"
|
||||
fi
|
||||
@@ -0,0 +1,44 @@
|
||||
name: Build and Test Go Project
|
||||
on: [push, pull_request]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
build:
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
os: [ubuntu-latest, windows-latest, macos-latest]
|
||||
|
||||
runs-on: ${{ matrix.os }}
|
||||
|
||||
steps:
|
||||
- name: Force git to use LF
|
||||
# This step is required on Windows to work around go mod tidy -diff issues caused by CRLF line endings.
|
||||
# TODO: replace with a checkout option when https://github.com/actions/checkout/issues/226 is implemented
|
||||
if: runner.os == 'Windows'
|
||||
run: |
|
||||
git config --global core.autocrlf false
|
||||
git config --global core.eol lf
|
||||
|
||||
- name: Check out code
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Build UI
|
||||
uses: ./.github/actions/build-ui
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version-file: "go.mod"
|
||||
|
||||
- name: Tidy dependencies
|
||||
run: go mod tidy -diff
|
||||
|
||||
- name: Run unit tests
|
||||
shell: bash
|
||||
run: script/test
|
||||
|
||||
- name: Build
|
||||
run: go build -v ./cmd/github-mcp-server
|
||||
@@ -0,0 +1,50 @@
|
||||
name: GoReleaser Release
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v*"
|
||||
permissions:
|
||||
contents: write
|
||||
id-token: write
|
||||
attestations: write
|
||||
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Check out code
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Build UI
|
||||
uses: ./.github/actions/build-ui
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version-file: "go.mod"
|
||||
|
||||
- name: Download dependencies
|
||||
run: go mod download
|
||||
|
||||
- name: Run GoReleaser
|
||||
uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94
|
||||
with:
|
||||
distribution: goreleaser
|
||||
# GoReleaser version
|
||||
version: "~> v2"
|
||||
# Arguments to pass to GoReleaser
|
||||
args: release --clean
|
||||
workdir: .
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
OAUTH_CLIENT_ID: ${{ secrets.OAUTH_CLIENT_ID }}
|
||||
OAUTH_CLIENT_SECRET: ${{ secrets.OAUTH_CLIENT_SECRET }}
|
||||
|
||||
- name: Generate signed build provenance attestations for workflow artifacts
|
||||
uses: actions/attest-build-provenance@v4
|
||||
with:
|
||||
subject-path: |
|
||||
dist/*.tar.gz
|
||||
dist/*.zip
|
||||
dist/*.txt
|
||||
@@ -0,0 +1,19 @@
|
||||
name: Label issues for AI review
|
||||
on:
|
||||
issues:
|
||||
types:
|
||||
- reopened
|
||||
- opened
|
||||
jobs:
|
||||
label_issues:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
issues: write
|
||||
steps:
|
||||
- name: Add AI review label to issue
|
||||
run: gh issue edit "$NUMBER" --add-label "$LABELS"
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
NUMBER: ${{ github.event.issue.number }}
|
||||
LABELS: "request ai review"
|
||||
@@ -0,0 +1,116 @@
|
||||
# Automatically fix license files on PRs that need updates
|
||||
# Tries to auto-commit the fix, or comments with instructions if push fails
|
||||
|
||||
name: License Check
|
||||
on:
|
||||
pull_request:
|
||||
branches:
|
||||
- main # Only run when PR targets main
|
||||
paths:
|
||||
- "**.go"
|
||||
- go.mod
|
||||
- go.sum
|
||||
- ".github/licenses.tmpl"
|
||||
- "script/licenses*"
|
||||
- "third-party-licenses.*.md"
|
||||
- "third-party/**"
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
license-check:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Check out code
|
||||
uses: actions/checkout@v7
|
||||
|
||||
# Check out the actual PR branch so we can push changes back if needed
|
||||
- name: Check out PR branch
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: gh pr checkout ${{ github.event.pull_request.number }}
|
||||
|
||||
- name: Build UI
|
||||
uses: ./.github/actions/build-ui
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version-file: "go.mod"
|
||||
|
||||
# actions/setup-go does not setup the installed toolchain to be preferred over the system install,
|
||||
# which causes go-licenses to raise "Package ... does not have module info" errors.
|
||||
# For more information, https://github.com/google/go-licenses/issues/244#issuecomment-1885098633
|
||||
- name: Regenerate licenses
|
||||
env:
|
||||
CI: "true"
|
||||
run: |
|
||||
export GOROOT=$(go env GOROOT)
|
||||
export PATH=${GOROOT}/bin:$PATH
|
||||
./script/licenses
|
||||
|
||||
- name: Check for changes
|
||||
id: changes
|
||||
continue-on-error: true
|
||||
run: script/licenses-check
|
||||
|
||||
- name: Commit and push fixes
|
||||
if: steps.changes.outcome == 'failure'
|
||||
continue-on-error: true
|
||||
id: push
|
||||
run: |
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "github-actions[bot]@users.noreply.github.com"
|
||||
git add third-party-licenses.*.md third-party/
|
||||
git commit -m "chore: regenerate license files" -m "Auto-generated by license-check workflow"
|
||||
git push
|
||||
|
||||
- name: Check if already commented
|
||||
if: steps.changes.outcome == 'failure' && steps.push.outcome == 'failure'
|
||||
id: check_comment
|
||||
uses: actions/github-script@v9
|
||||
with:
|
||||
script: |
|
||||
const { data: comments } = await github.rest.issues.listComments({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: context.issue.number
|
||||
});
|
||||
|
||||
const alreadyCommented = comments.some(comment =>
|
||||
comment.user.login === 'github-actions[bot]' &&
|
||||
comment.body.includes('## ⚠️ License files need updating')
|
||||
);
|
||||
|
||||
core.setOutput('already_commented', alreadyCommented ? 'true' : 'false');
|
||||
|
||||
- name: Comment with instructions if cannot push
|
||||
if: steps.changes.outcome == 'failure' && steps.push.outcome == 'failure' && steps.check_comment.outputs.already_commented == 'false'
|
||||
uses: actions/github-script@v9
|
||||
with:
|
||||
script: |
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: context.issue.number,
|
||||
body: `## ⚠️ License files need updating
|
||||
|
||||
The license files are out of date. I tried to fix them automatically but don't have permission to push to this branch.
|
||||
|
||||
**Please run:**
|
||||
\`\`\`bash
|
||||
script/licenses
|
||||
git add third-party-licenses.*.md third-party/
|
||||
git commit -m "chore: regenerate license files"
|
||||
git push
|
||||
\`\`\`
|
||||
|
||||
Alternatively, enable "Allow edits by maintainers" in the PR settings so I can fix it automatically.`
|
||||
});
|
||||
|
||||
- name: Fail check if changes needed
|
||||
if: steps.changes.outcome == 'failure'
|
||||
run: exit 1
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
name: golangci-lint
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
golangci:
|
||||
name: lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- name: Build UI
|
||||
uses: ./.github/actions/build-ui
|
||||
- uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '1.25'
|
||||
- name: golangci-lint
|
||||
uses: golangci/golangci-lint-action@v9
|
||||
with:
|
||||
# sync with script/lint
|
||||
version: v2.9
|
||||
@@ -0,0 +1,140 @@
|
||||
name: MCP Server Diff
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [main]
|
||||
tags: ['v*']
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
mcp-diff:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Check out code
|
||||
uses: actions/checkout@v7
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version-file: go.mod
|
||||
|
||||
- name: Build UI
|
||||
uses: ./.github/actions/build-ui
|
||||
|
||||
- name: Stash UI artifacts for baseline checkout
|
||||
# mcp-server-diff checks the baseline ref out into a separate working
|
||||
# directory and runs install_command there. Without these prebuilt
|
||||
# artifacts, pkg/github/ui_dist/ would be empty on the baseline side
|
||||
# and UIAssetsAvailable() would return false, producing a false-positive
|
||||
# diff that "adds" _meta.ui to MCP Apps tools on every PR.
|
||||
run: |
|
||||
mkdir -p "${RUNNER_TEMP}/ui_dist"
|
||||
cp pkg/github/ui_dist/*.html "${RUNNER_TEMP}/ui_dist/"
|
||||
|
||||
- name: Generate diff configurations
|
||||
id: configs
|
||||
# The generator imports pkg/github so any new entry in
|
||||
# AllowedFeatureFlags is automatically diffed without touching this
|
||||
# workflow. See script/print-mcp-diff-configs/main.go.
|
||||
run: |
|
||||
{
|
||||
echo 'configurations<<MCP_DIFF_EOF'
|
||||
go run ./script/print-mcp-diff-configs
|
||||
echo 'MCP_DIFF_EOF'
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Run MCP Server Diff
|
||||
# Pinned to the cross-spec-aware mcp-server-diff v3.0.0 (full SHA required —
|
||||
# Actions rejects shortened SHAs): normalizes _meta plumbing, cache hints,
|
||||
# initialize envelope, tool-annotation default hints; probes each server at its
|
||||
# own newest spec via the stateless SEP-2575 server/discover path. Keeps the
|
||||
# go-sdk v1.6.1 -> v1.7.0-pre.1 bump an honest, signal-only diff. github/copilot-mcp-core#1709.
|
||||
uses: SamMorrowDrums/mcp-server-diff@40d992e0a220e5b63378758f9a40d6a8982898d2 # v3.0.0
|
||||
with:
|
||||
setup_go: "false"
|
||||
install_command: |
|
||||
go mod download
|
||||
mkdir -p pkg/github/ui_dist
|
||||
cp "${RUNNER_TEMP}"/ui_dist/*.html pkg/github/ui_dist/
|
||||
start_command: go run ./cmd/github-mcp-server stdio
|
||||
env_vars: |
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN=test-token
|
||||
configurations: ${{ steps.configs.outputs.configurations }}
|
||||
|
||||
- name: Add interpretation note
|
||||
if: always()
|
||||
run: |
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "---" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "ℹ️ **Note:** Differences may be intentional improvements." >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "Common expected differences:" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- New tools/toolsets added" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- Tool descriptions updated" >> $GITHUB_STEP_SUMMARY
|
||||
echo "- Capability changes (intentional improvements)" >> $GITHUB_STEP_SUMMARY
|
||||
|
||||
mcp-diff-http:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Check out code
|
||||
uses: actions/checkout@v7
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version-file: go.mod
|
||||
|
||||
- name: Build UI
|
||||
uses: ./.github/actions/build-ui
|
||||
|
||||
- name: Stash UI artifacts for baseline checkout
|
||||
# See the stdio job above for rationale: the action's baseline checkout
|
||||
# has no UI artifacts unless we hand them over via RUNNER_TEMP.
|
||||
run: |
|
||||
mkdir -p "${RUNNER_TEMP}/ui_dist"
|
||||
cp pkg/github/ui_dist/*.html "${RUNNER_TEMP}/ui_dist/"
|
||||
|
||||
- name: Generate diff configurations
|
||||
id: configs
|
||||
# See script/print-mcp-diff-configs/main.go. The http-headers variant
|
||||
# points every config at a shared HTTP server started by the action
|
||||
# and carries per-config settings via X-MCP-* headers, mirroring how
|
||||
# the remote server is invoked in production (server-side defaults +
|
||||
# per-user header overrides).
|
||||
run: |
|
||||
{
|
||||
echo 'configurations<<MCP_DIFF_EOF'
|
||||
go run ./script/print-mcp-diff-configs -transport http-headers
|
||||
echo 'MCP_DIFF_EOF'
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Run MCP Server Diff (streamable-http)
|
||||
# Pinned to mcp-server-diff v3.0.0 — see rationale on the stdio job above.
|
||||
uses: SamMorrowDrums/mcp-server-diff@40d992e0a220e5b63378758f9a40d6a8982898d2 # v3.0.0
|
||||
with:
|
||||
setup_go: "false"
|
||||
install_command: |
|
||||
go mod download
|
||||
mkdir -p pkg/github/ui_dist
|
||||
cp "${RUNNER_TEMP}"/ui_dist/*.html pkg/github/ui_dist/
|
||||
http_start_command: go run ./cmd/github-mcp-server http --port 8082
|
||||
http_startup_wait_ms: "5000"
|
||||
configurations: ${{ steps.configs.outputs.configurations }}
|
||||
|
||||
- name: Add interpretation note
|
||||
if: always()
|
||||
run: |
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "---" >> $GITHUB_STEP_SUMMARY
|
||||
echo "" >> $GITHUB_STEP_SUMMARY
|
||||
echo "ℹ️ **Note:** This job exercises the streamable-http transport against a shared server, with per-config settings supplied via X-MCP-* request headers." >> $GITHUB_STEP_SUMMARY
|
||||
@@ -0,0 +1,28 @@
|
||||
name: AI Moderator
|
||||
on:
|
||||
issues:
|
||||
types: [opened]
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review_comment:
|
||||
types: [created]
|
||||
|
||||
jobs:
|
||||
spam-detection:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
issues: write
|
||||
pull-requests: write
|
||||
models: read
|
||||
contents: read
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- uses: github/ai-moderator@v1
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
spam-label: 'spam'
|
||||
ai-label: 'ai-generated'
|
||||
minimize-detected-comments: true
|
||||
enable-spam-detection: true
|
||||
enable-link-spam-detection: true
|
||||
enable-ai-detection: true
|
||||
@@ -0,0 +1,83 @@
|
||||
name: Publish to MCP Registry
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ["v*"] # Triggers on version tags like v1.0.0
|
||||
workflow_dispatch: # Allow manual triggering
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write # Required for OIDC authentication
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Setup Go
|
||||
uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: "stable"
|
||||
|
||||
- name: Fetch tags
|
||||
run: |
|
||||
if [[ "${{ github.ref_type }}" != "tag" ]]; then
|
||||
git fetch --tags
|
||||
else
|
||||
echo "Skipping tag fetch - already on tag ${{ github.ref_name }}"
|
||||
fi
|
||||
|
||||
- name: Wait for Docker image
|
||||
run: |
|
||||
if [[ "${{ github.ref_type }}" == "tag" ]]; then
|
||||
TAG="${{ github.ref_name }}"
|
||||
else
|
||||
TAG=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n1)
|
||||
fi
|
||||
IMAGE="ghcr.io/github/github-mcp-server:$TAG"
|
||||
|
||||
for i in {1..10}; do
|
||||
if docker manifest inspect "$IMAGE" &>/dev/null; then
|
||||
echo "✅ Docker image ready: $TAG"
|
||||
break
|
||||
fi
|
||||
[ $i -eq 10 ] && { echo "❌ Timeout waiting for $TAG after 5 minutes"; exit 1; }
|
||||
echo "⏳ Waiting for Docker image ($i/10)..."
|
||||
sleep 30
|
||||
done
|
||||
|
||||
- name: Install MCP Publisher
|
||||
run: |
|
||||
git clone --quiet https://github.com/modelcontextprotocol/registry publisher-repo
|
||||
cd publisher-repo && make publisher > /dev/null && cd ..
|
||||
cp publisher-repo/bin/mcp-publisher . && chmod +x mcp-publisher
|
||||
|
||||
- name: Update server.json version
|
||||
run: |
|
||||
if [[ "${{ github.ref_type }}" == "tag" ]]; then
|
||||
TAG_VERSION=$(echo "${{ github.ref_name }}" | sed 's/^v//')
|
||||
else
|
||||
LATEST_TAG=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)
|
||||
[ -z "$LATEST_TAG" ] && { echo "No release tag found"; exit 1; }
|
||||
TAG_VERSION=$(echo "$LATEST_TAG" | sed 's/^v//')
|
||||
echo "Using latest tag: $LATEST_TAG"
|
||||
fi
|
||||
sed -i "s/\${VERSION}/$TAG_VERSION/g" server.json
|
||||
echo "Version: $TAG_VERSION"
|
||||
|
||||
- name: Validate configuration
|
||||
run: |
|
||||
python3 -m json.tool server.json > /dev/null && echo "Configuration valid" || exit 1
|
||||
|
||||
- name: Display final server.json
|
||||
run: |
|
||||
echo "Final server.json contents:"
|
||||
cat server.json
|
||||
|
||||
- name: Login to MCP Registry (OIDC)
|
||||
run: ./mcp-publisher login github-oidc
|
||||
|
||||
- name: Publish to MCP Registry
|
||||
run: ./mcp-publisher publish
|
||||
Reference in New Issue
Block a user