Merge branch 'main' into feature/reply-to-review-comments

Author: lossyrob

.github/copilot-instructions.md

@@ -9,7 +9,7 @@ This is the **GitHub MCP Server**, a Model Context Protocol (MCP) server that co
 - **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
+- **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.
 

.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

.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

.github/workflows/ai-issue-assessment.yml

@@ -0,0 +1,30 @@
+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 }}
+          ai_review_label: 'bug, enhancement'
+          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'

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:
@@ -717,8 +719,8 @@ The following sets of tools are available:
 
 - **issue_read** - Get issue details
   - `issue_number`: The number of the issue (number, required)
-  - `method`: The read operation to perform on a single issue. 
-Options are: 
+  - `method`: The read operation to perform on a single issue.
+Options are:
 1. get - Get details of a specific issue.
 2. get_comments - Get issue comments.
 3. get_sub_issues - Get sub-issues of the issue.
@@ -736,8 +738,8 @@ Options are:
   - `issue_number`: Issue number to update (number, optional)
   - `labels`: Labels to apply to this issue (string[], optional)
   - `method`: Write operation to perform on a single issue.
-Options are: 
-- 'create' - creates a new issue. 
+Options are:
+- 'create' - creates a new issue.
 - 'update' - updates an existing issue.
  (string, required)
   - `milestone`: Milestone number (number, optional)
@@ -817,7 +819,7 @@ Options are:
 <summary>Notifications</summary>
 
 - **dismiss_notification** - Dismiss notification
-  - `state`: The new state of the notification (read/done) (string, optional)
+  - `state`: The new state of the notification (read/done) (string, required)
   - `threadID`: The ID of the notification thread (string, required)
 
 - **get_notification_details** - Get notification details

cmd/github-mcp-server/generate_docs.go

@@ -15,7 +15,8 @@ import (
 	"github.com/github/github-mcp-server/pkg/toolsets"
 	"github.com/github/github-mcp-server/pkg/translations"
 	gogithub "github.com/google/go-github/v79/github"
-	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/google/jsonschema-go/jsonschema"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/shurcooL/githubv4"
 	"github.com/spf13/cobra"
 )
@@ -226,7 +227,16 @@ func generateToolDoc(tool mcp.Tool) string {
 	lines = append(lines, fmt.Sprintf("- **%s** - %s", tool.Name, tool.Annotations.Title))
 
 	// Parameters
-	schema := tool.InputSchema
+	if tool.InputSchema == nil {
+		lines = append(lines, "  - No parameters required")
+		return strings.Join(lines, "\n")
+	}
+	schema, ok := tool.InputSchema.(*jsonschema.Schema)
+	if !ok || schema == nil {
+		lines = append(lines, "  - No parameters required")
+		return strings.Join(lines, "\n")
+	}
+
 	if len(schema.Properties) > 0 {
 		// Get parameter names and sort them for deterministic order
 		var paramNames []string
@@ -243,30 +253,22 @@ func generateToolDoc(tool mcp.Tool) string {
 				requiredStr = "required"
 			}
 
-			// Get the type and description
-			typeStr := "unknown"
-			description := ""
-
-			if propMap, ok := prop.(map[string]interface{}); ok {
-				if typeVal, ok := propMap["type"].(string); ok {
-					if typeVal == "array" {
-						if items, ok := propMap["items"].(map[string]interface{}); ok {
-							if itemType, ok := items["type"].(string); ok {
-								typeStr = itemType + "[]"
-							}
-						} else {
-							typeStr = "array"
-						}
-					} else {
-						typeStr = typeVal
-					}
-				}
+			var typeStr, description string
 
-				if desc, ok := propMap["description"].(string); ok {
-					description = desc
+			// Get the type and description
+			switch prop.Type {
+			case "array":
+				if prop.Items != nil {
+					typeStr = prop.Items.Type + "[]"
+				} else {
+					typeStr = "array"
 				}
+			default:
+				typeStr = prop.Type
 			}
 
+			description = prop.Description
+
 			paramLine := fmt.Sprintf("  - `%s`: %s (%s, %s)", propName, description, typeStr, requiredStr)
 			lines = append(lines, paramLine)
 		}

docs/remote-server.md

@@ -53,18 +53,23 @@ 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.
 - `X-MCP-Lockdown`: Enables lockdown mode, hiding public issue details created by users without push access.
     - 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