From 4d6d64e715690d3f0be05052ef0d2d02a97fee93 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 28 Nov 2025 10:46:30 +0100 Subject: [PATCH 1/3] Add AI issue assessment workflow with github/ai-assessment-comment-labeler (#1498) * Initial plan * Add AI issue assessment workflow with github/ai-assessment-comment-labeler Co-authored-by: JoannaaKL <67866556+JoannaaKL@users.noreply.github.com> * Remove AI issue assessment workflow and prompt file per review feedback Co-authored-by: JoannaaKL <67866556+JoannaaKL@users.noreply.github.com> * Restore workflow and prompt, run on bug label or unlabeled issues Co-authored-by: JoannaaKL <67866556+JoannaaKL@users.noreply.github.com> * Update .github/workflows/ai-issue-assessment.yml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Add default-issue-review.prompt.yml for unlabeled issues Co-authored-by: JoannaaKL <67866556+JoannaaKL@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: JoannaaKL <67866556+JoannaaKL@users.noreply.github.com> Co-authored-by: JoannaaKL Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/prompts/bug-report-review.prompt.yml | 32 +++++++++++++++++++ .../prompts/default-issue-review.prompt.yml | 31 ++++++++++++++++++ .github/workflows/ai-issue-assessment.yml | 29 +++++++++++++++++ 3 files changed, 92 insertions(+) create mode 100644 .github/prompts/bug-report-review.prompt.yml create mode 100644 .github/prompts/default-issue-review.prompt.yml create mode 100644 .github/workflows/ai-issue-assessment.yml diff --git a/.github/prompts/bug-report-review.prompt.yml b/.github/prompts/bug-report-review.prompt.yml new file mode 100644 index 000000000..23c4bf70d --- /dev/null +++ b/.github/prompts/bug-report-review.prompt.yml @@ -0,0 +1,32 @@ +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. + + Analyze the issue for these key elements: + 1. Clear description of the problem + 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 + 4. Expected vs actual behavior + 5. Relevant logs (if applicable) + + Provide ONE of these assessments: + + ### AI Assessment: Ready for Review + Use when the bug report has most required information and can be triaged by a maintainer. + + ### AI Assessment: Missing Details + Use when critical information is missing (no reproduction steps, no version info, unclear problem description). + + ### 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, note which specific sections need more information. + - role: user + content: "{{input}}" +model: openai/gpt-4o-mini +modelParameters: + max_tokens: 500 diff --git a/.github/prompts/default-issue-review.prompt.yml b/.github/prompts/default-issue-review.prompt.yml new file mode 100644 index 000000000..6b4cd4a2b --- /dev/null +++ b/.github/prompts/default-issue-review.prompt.yml @@ -0,0 +1,31 @@ +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. + + Analyze the issue to determine: + 1. Is this a bug report, feature request, question, or something else? + 2. Is the issue clear and well-described? + 3. Does it contain enough information for maintainers to act on? + + Provide ONE of these assessments: + + ### AI Assessment: Ready for Review + Use when the issue is clear, well-described, and contains enough context for maintainers to understand and act on it. + + ### AI Assessment: Missing Details + Use when the issue is unclear, lacks context, or needs more information to be actionable. + + ### 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, etc.) + - What additional information might be helpful if any + - role: user + content: "{{input}}" +model: openai/gpt-4o-mini +modelParameters: + max_tokens: 500 diff --git a/.github/workflows/ai-issue-assessment.yml b/.github/workflows/ai-issue-assessment.yml new file mode 100644 index 000000000..8e813e81d --- /dev/null +++ b/.github/workflows/ai-issue-assessment.yml @@ -0,0 +1,29 @@ +name: AI Issue Assessment + +on: + issues: + types: [opened, labeled] + +jobs: + ai-issue-assessment: + if: > + (github.event.action == 'opened' && github.event.issue.labels[0] == null) || + (github.event.action == 'labeled' && github.event.label.name == 'bug') + runs-on: ubuntu-latest + permissions: + issues: write + models: read + contents: read + + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Run AI assessment + uses: github/ai-assessment-comment-labeler@e3bedc38cfffa9179fe4cee8f7ecc93bffb3fee7 # v1.0.1 + with: + token: ${{ secrets.GITHUB_TOKEN }} + 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' From 9c73e88deb8bd574992958f7de7e99d19f253a17 Mon Sep 17 00:00:00 2001 From: Tommaso Moro <37270480+tommaso-moro@users.noreply.github.com> Date: Fri, 28 Nov 2025 10:17:47 +0000 Subject: [PATCH 2/3] Tommy/server-config-docs (#1495) * small doc update to add x-mcp-tools header * update * add server configuration guide * update * Update docs/server-configuration.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/remote-server.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/server-configuration.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/server-configuration.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/server-configuration.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/server-configuration.md Co-authored-by: Tony Truong * use relative paths * use relative path --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Tony Truong --- README.md | 2 + docs/remote-server.md | 9 +- docs/server-configuration.md | 350 +++++++++++++++++++++++++++++++++++ 3 files changed, 359 insertions(+), 2 deletions(-) create mode 100644 docs/server-configuration.md diff --git a/README.md b/README.md index d6925d8ab..c9e724227 100644 --- a/README.md +++ b/README.md @@ -328,6 +328,8 @@ _Toolsets are not limited to Tools. Relevant MCP Resources and Prompts are also When no toolsets are specified, [default toolsets](#default-toolset) are used. +> **Looking for examples?** See the [Server Configuration Guide](./docs/server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets. + #### Specifying Toolsets To specify toolsets you want available to the LLM, you can pass an allow-list in two ways: diff --git a/docs/remote-server.md b/docs/remote-server.md index ec6d2302d..1030911ef 100644 --- a/docs/remote-server.md +++ b/docs/remote-server.md @@ -53,11 +53,14 @@ These toolsets are only available in the remote GitHub MCP Server and are not in ### Optional Headers -The Remote GitHub MCP server has optional headers equivalent to the Local server env vars: +The Remote GitHub MCP server has optional headers equivalent to the Local server env vars or flags: - `X-MCP-Toolsets`: Comma-separated list of toolsets to enable. E.g. "repos,issues". - - Equivalent to `GITHUB_TOOLSETS` env var for Local server. + - Equivalent to `GITHUB_TOOLSETS` env var or `--toolsets` flag for Local server. - If the list is empty, default toolsets will be used. Invalid or unknown toolsets are silently ignored without error and will not prevent the server from starting. Whitespace is ignored. +- `X-MCP-Tools`: Comma-separated list of tools to enable. E.g. "get_file_contents,issue_read,pull_request_read". + - Equivalent to `GITHUB_TOOLS` env var or `--tools` flag for Local server. + - Invalid tools will throw an error and prevent the server from starting. Whitespace is ignored. - `X-MCP-Readonly`: Enables only "read" tools. - Equivalent to `GITHUB_READ_ONLY` env var for Local server. - If this header is empty, "false", "f", "no", "n", "0", or "off" (ignoring whitespace and case), it will be interpreted as false. All other values are interpreted as true. @@ -65,6 +68,8 @@ The Remote GitHub MCP server has optional headers equivalent to the Local server - Equivalent to `GITHUB_LOCKDOWN_MODE` env var for Local server. - If this header is empty, "false", "f", "no", "n", "0", or "off" (ignoring whitespace and case), it will be interpreted as false. All other values are interpreted as true. +> **Looking for examples?** See the [Server Configuration Guide](./server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets. + Example: ```json diff --git a/docs/server-configuration.md b/docs/server-configuration.md new file mode 100644 index 000000000..e8b7637bd --- /dev/null +++ b/docs/server-configuration.md @@ -0,0 +1,350 @@ +# Server Configuration Guide + +This guide helps you choose the right configuration for your use case and shows you how to apply it. For the complete reference of available toolsets and tools, see the [README](../README.md#tool-configuration). + +## Quick Reference +We currently support the following ways in which the GitHub MCP Server can be configured: + +| Configuration | Remote Server | Local Server | +|---------------|---------------|--------------| +| Toolsets | `X-MCP-Toolsets` header or `/x/{toolset}` URL | `--toolsets` flag or `GITHUB_TOOLSETS` env var | +| Individual Tools | `X-MCP-Tools` header | `--tools` flag or `GITHUB_TOOLS` env var | +| Read-Only Mode | `X-MCP-Readonly` header or `/readonly` URL | `--read-only` flag or `GITHUB_READ_ONLY` env var | +| Dynamic Mode | Not available | `--dynamic-toolsets` flag or `GITHUB_DYNAMIC_TOOLSETS` env var | +| Lockdown Mode | `X-MCP-Lockdown` header | `--lockdown-mode` flag or `GITHUB_LOCKDOWN_MODE` env var | + +> **Default behavior:** If you don't specify any configuration, the server uses the **default toolsets**: `context`, `issues`, `pull_requests`, `repos`, `users`. + +--- + +## How Configuration Works + +All configuration options are **composable**: you can combine toolsets, individual tools, dynamic discovery, read-only mode and lockdown mode in any way that suits your workflow. + +Note: **read-only** mode acts as a strict security filter that takes precedence over any other configuration, by disabling write tools even when explicitly requested. + +--- + +## Configuration Examples + +The examples below use VS Code configuration format to illustrate the concepts. If you're using a different MCP host (Cursor, Claude Desktop, JetBrains, etc.), your configuration might need to look slightly different. See [installation guides](./installation-guides) for host-specific setup. + +### Enabling Specific Tools + +**Best for:** users who know exactly what they need and want to optimize context usage by loading only the tools they will use. + +**Example:** + + + + + + + +
Remote ServerLocal Server
+ +```json +{ + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "X-MCP-Tools": "get_file_contents,get_me,pull_request_read" + } +} +``` + + + +```json +{ + "type": "stdio", + "command": "go", + "args": [ + "run", + "./cmd/github-mcp-server", + "stdio", + "--tools=get_file_contents,get_me,pull_request_read" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } +} +``` + +
+ +--- + +### Enabling Specific Toolsets + +**Best for:** Users who want to enable multiple related toolsets. + + + + + + + +
Remote ServerLocal Server
+ +```json +{ + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "X-MCP-Toolsets": "issues,pull_requests" + } +} +``` + + + +```json +{ + "type": "stdio", + "command": "go", + "args": [ + "run", + "./cmd/github-mcp-server", + "stdio", + "--toolsets=issues,pull_requests" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } +} +``` + +
+ +--- + +### Enabling Toolsets + Tools + +**Best for:** Users who want broad functionality from some areas, plus specific tools from others. + +Enable entire toolsets, then add individual tools from toolsets you don't want fully enabled. + + + + + + + +
Remote ServerLocal Server
+ +```json +{ + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "X-MCP-Toolsets": "repos,issues", + "X-MCP-Tools": "get_gist,pull_request_read" + } +} +``` + + + +```json +{ + "type": "stdio", + "command": "go", + "args": [ + "run", + "./cmd/github-mcp-server", + "stdio", + "--toolsets=repos,issues", + "--tools=get_gist,pull_request_read" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } +} +``` + +
+ +**Result:** All repository and issue tools, plus just the gist tools you need. + +--- + +### Read-Only Mode + +**Best for:** Security conscious users who want to ensure the server won't allow operations that modify issues, pull requests, repositories etc. + +When active, this mode will disable all tools that are not read-only even if they were requested. + +**Example:** + + + + + + +
Remote ServerLocal Server
+ +**Option A: Header** +```json +{ + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "X-MCP-Toolsets": "issues,repos,pull_requests", + "X-MCP-Readonly": "true" + } +} +``` + +**Option B: URL path** +```json +{ + "type": "http", + "url": "https://api.githubcopilot.com/mcp/x/all/readonly" +} +``` + + + + +```json +{ + "type": "stdio", + "command": "go", + "args": [ + "run", + "./cmd/github-mcp-server", + "stdio", + "--toolsets=issues,repos,pull_requests", + "--read-only" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } +} +``` + +
+ +> Even if `issues` toolset contains `create_issue`, it will be excluded in read-only mode. + +--- + +### Dynamic Discovery (Local Only) + +**Best for:** Letting the LLM discover and enable toolsets as needed. + +Starts with only discovery tools (`enable_toolset`, `list_available_toolsets`, `get_toolset_tools`), then expands on demand. + + + + + + +
Local Server Only
+ +```json +{ + "type": "stdio", + "command": "go", + "args": [ + "run", + "./cmd/github-mcp-server", + "stdio", + "--dynamic-toolsets" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } +} +``` + +**With some tools pre-enabled:** +```json +{ + "type": "stdio", + "command": "go", + "args": [ + "run", + "./cmd/github-mcp-server", + "stdio", + "--dynamic-toolsets", + "--tools=get_me,search_code" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } +} +``` + +
+ +When both dynamic mode and specific tools are enabled in the server configuration, the server will start with the 3 dynamic tools + the specified tools. + +--- + +### Lockdown Mode + +**Best for:** Public repositories where you want to limit content from users without push access. + +Lockdown mode ensures the server only surfaces content in public repositories from users with push access to that repository. Private repositories are unaffected, and collaborators retain full access to their own content. + +**Example:** + + + + + + +
Remote ServerLocal Server
+ +```json +{ + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "X-MCP-Lockdown": "true" + } +} +``` + + + +```json +{ + "type": "stdio", + "command": "go", + "args": [ + "run", + "./cmd/github-mcp-server", + "stdio", + "--lockdown-mode" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + } +} +``` + +
+ +--- + +## Troubleshooting + +| Problem | Cause | Solution | +|---------|-------|----------| +| Server fails to start | Invalid tool name in `--tools` or `X-MCP-Tools` | Check tool name spelling; use exact names from [Tools list](../README.md#tools) | +| Write tools not working | Read-only mode enabled | Remove `--read-only` flag or `X-MCP-Readonly` header | +| Tools missing | Toolset not enabled | Add the required toolset or specific tool | +| Dynamic tools not available | Using remote server | Dynamic mode is available in the local MCP server only | + +--- + +## Useful links + +- [README: Tool Configuration](../README.md#tool-configuration) +- [README: Available Toolsets](../README.md#available-toolsets) — Complete list of toolsets +- [README: Tools](../README.md#tools) — Complete list of individual tools +- [Remote Server Documentation](./remote-server.md) — Remote-specific options and headers +- [Installation Guides](./installation-guides) — Host-specific setup instructions From ada4bc05a9c7c8246bd0651386a558802e23dec0 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 28 Nov 2025 11:35:33 +0100 Subject: [PATCH 3/3] Add ai_review_label to ai-issue-assessment.yml (#1501) * Initial plan * Add ai_review_label to ai-issue-assessment.yml Co-authored-by: JoannaaKL <67866556+JoannaaKL@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: JoannaaKL <67866556+JoannaaKL@users.noreply.github.com> --- .github/workflows/ai-issue-assessment.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ai-issue-assessment.yml b/.github/workflows/ai-issue-assessment.yml index 8e813e81d..7481ce6db 100644 --- a/.github/workflows/ai-issue-assessment.yml +++ b/.github/workflows/ai-issue-assessment.yml @@ -23,6 +23,7 @@ jobs: uses: github/ai-assessment-comment-labeler@e3bedc38cfffa9179fe4cee8f7ecc93bffb3fee7 # v1.0.1 with: token: ${{ secrets.GITHUB_TOKEN }} + ai_review_label: 'bug, enhancement' issue_number: ${{ github.event.issue.number }} issue_body: ${{ github.event.issue.body }} prompts_directory: '.github/prompts'