From 72009399f849a659978d4e90f24944f7066d104f Mon Sep 17 00:00:00 2001
From: Tommaso Moro <37270480+tommaso-moro@users.noreply.github.com>
Date: Wed, 2 Jul 2025 08:37:43 +0100
Subject: [PATCH 01/32] add DS_Store to .gitignore (#626)

---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitignore b/.gitignore
index df489c390..0ad709cbf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,6 @@ __debug_bin*
 # Go
 vendor
 bin/
+
+# macOS
+.DS_Store
\ No newline at end of file

From 39109b3e5d775ee9828935c04853ac4d62485e23 Mon Sep 17 00:00:00 2001
From: JoannaaKL <joannaakl@github.com>
Date: Wed, 2 Jul 2025 15:09:04 +0200
Subject: [PATCH 02/32] Add discussion tools (#624)

---
 README.md                      |  30 +++
 docs/remote-server.md          |   1 +
 pkg/github/discussions.go      | 441 +++++++++++++++++++++++++++++++++
 pkg/github/discussions_test.go | 400 ++++++++++++++++++++++++++++++
 pkg/github/tools.go            |   9 +
 script/get-discussions         |   5 +
 6 files changed, 886 insertions(+)
 create mode 100644 pkg/github/discussions.go
 create mode 100644 pkg/github/discussions_test.go
 create mode 100755 script/get-discussions

diff --git a/README.md b/README.md
index 44a829601..b4c326c0e 100644
--- a/README.md
+++ b/README.md
@@ -269,6 +269,7 @@ The following sets of tools are available (all are on by default):
 | `context`               | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in |
 | `actions` | GitHub Actions workflows and CI/CD operations |
 | `code_security` | Code security related tools, such as GitHub Code Scanning |
+| `discussions` | GitHub Discussions related tools |
 | `experiments` | Experimental features that are not considered stable yet |
 | `issues` | GitHub Issues related tools |
 | `notifications` | GitHub Notifications related tools |
@@ -554,6 +555,35 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 
 <details>
 
+<summary>Discussions</summary>
+
+- **get_discussion** - Get discussion
+  - `discussionNumber`: Discussion Number (number, required)
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+
+- **get_discussion_comments** - Get discussion comments
+  - `discussionNumber`: Discussion Number (number, required)
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+
+- **list_discussion_categories** - List discussion categories
+  - `after`: Cursor for pagination, use the 'after' field from the previous response (string, optional)
+  - `before`: Cursor for pagination, use the 'before' field from the previous response (string, optional)
+  - `first`: Number of categories to return per page (min 1, max 100) (number, optional)
+  - `last`: Number of categories to return from the end (min 1, max 100) (number, optional)
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+
+- **list_discussions** - List discussions
+  - `category`: Optional filter by discussion category ID. If provided, only discussions with this category are listed. (string, optional)
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+
+</details>
+
+<details>
+
 <summary>Issues</summary>
 
 - **add_issue_comment** - Add comment to issue
diff --git a/docs/remote-server.md b/docs/remote-server.md
index 50404ec85..7b5f2c0d4 100644
--- a/docs/remote-server.md
+++ b/docs/remote-server.md
@@ -20,6 +20,7 @@ Below is a table of available toolsets for the remote GitHub MCP Server. Each to
 | all            | All available GitHub MCP tools                    | https://api.githubcopilot.com/mcp/                    | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D)                                      | [read-only](https://api.githubcopilot.com/mcp/readonly)                                                      | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Freadonly%22%7D) |
 | Actions        | GitHub Actions workflows and CI/CD operations    | https://api.githubcopilot.com/mcp/x/actions           | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%22%7D)                         | [read-only](https://api.githubcopilot.com/mcp/x/actions/readonly)                                              | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%2Freadonly%22%7D)                                                                          |
 | Code Security  | Code security related tools, such as GitHub Code Scanning | https://api.githubcopilot.com/mcp/x/code_security     | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%22%7D)             | [read-only](https://api.githubcopilot.com/mcp/x/code_security/readonly)                                        | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%2Freadonly%22%7D)                                                              |
+| Discussions    | GitHub Discussions related tools                 | https://api.githubcopilot.com/mcp/x/discussions       | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-discussions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdiscussions%22%7D)                 | [read-only](https://api.githubcopilot.com/mcp/x/discussions/readonly)                                          | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-discussions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdiscussions%2Freadonly%22%7D)                                                                  |
 | Experiments    | Experimental features that are not considered stable yet | https://api.githubcopilot.com/mcp/x/experiments       | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%22%7D)                 | [read-only](https://api.githubcopilot.com/mcp/x/experiments/readonly)                                          | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%2Freadonly%22%7D)                                                                  |
 | Issues         | GitHub Issues related tools                      | https://api.githubcopilot.com/mcp/x/issues            | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%22%7D)                           | [read-only](https://api.githubcopilot.com/mcp/x/issues/readonly)                                               | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%2Freadonly%22%7D)                                                                            |
 | Notifications  | GitHub Notifications related tools               | https://api.githubcopilot.com/mcp/x/notifications     | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%22%7D)             | [read-only](https://api.githubcopilot.com/mcp/x/notifications/readonly)                                        | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%2Freadonly%22%7D)                                                              |
diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go
new file mode 100644
index 000000000..d61fe969d
--- /dev/null
+++ b/pkg/github/discussions.go
@@ -0,0 +1,441 @@
+package github
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/go-viper/mapstructure/v2"
+	"github.com/google/go-github/v72/github"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+	"github.com/shurcooL/githubv4"
+)
+
+// GetAllDiscussionCategories retrieves all discussion categories for a repository
+// by paginating through all pages and returns them as a map where the key is the
+// category name and the value is the category ID.
+func GetAllDiscussionCategories(ctx context.Context, client *githubv4.Client, owner, repo string) (map[string]string, error) {
+	categories := make(map[string]string)
+	var after string
+	hasNextPage := true
+
+	for hasNextPage {
+		// Prepare GraphQL query with pagination
+		var q struct {
+			Repository struct {
+				DiscussionCategories struct {
+					Nodes []struct {
+						ID   githubv4.ID
+						Name githubv4.String
+					}
+					PageInfo struct {
+						HasNextPage githubv4.Boolean
+						EndCursor   githubv4.String
+					}
+				} `graphql:"discussionCategories(first: 100, after: $after)"`
+			} `graphql:"repository(owner: $owner, name: $repo)"`
+		}
+
+		vars := map[string]interface{}{
+			"owner": githubv4.String(owner),
+			"repo":  githubv4.String(repo),
+			"after": githubv4.String(after),
+		}
+
+		if err := client.Query(ctx, &q, vars); err != nil {
+			return nil, fmt.Errorf("failed to query discussion categories: %w", err)
+		}
+
+		// Add categories to the map
+		for _, category := range q.Repository.DiscussionCategories.Nodes {
+			categories[string(category.Name)] = fmt.Sprint(category.ID)
+		}
+
+		// Check if there are more pages
+		hasNextPage = bool(q.Repository.DiscussionCategories.PageInfo.HasNextPage)
+		if hasNextPage {
+			after = string(q.Repository.DiscussionCategories.PageInfo.EndCursor)
+		}
+	}
+
+	return categories, nil
+}
+
+func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("list_discussions",
+			mcp.WithDescription(t("TOOL_LIST_DISCUSSIONS_DESCRIPTION", "List discussions for a repository")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_LIST_DISCUSSIONS_USER_TITLE", "List discussions"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithString("category",
+				mcp.Description("Optional filter by discussion category ID. If provided, only discussions with this category are listed."),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			// Required params
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			// Optional params
+			category, err := OptionalParam[string](request, "category")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			client, err := getGQLClient(ctx)
+			if err != nil {
+				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
+			}
+
+			// If category filter is specified, use it as the category ID for server-side filtering
+			var categoryID *githubv4.ID
+			if category != "" {
+				id := githubv4.ID(category)
+				categoryID = &id
+			}
+
+			// Now execute the discussions query
+			var discussions []*github.Issue
+			if categoryID != nil {
+				// Query with category filter (server-side filtering)
+				var query struct {
+					Repository struct {
+						Discussions struct {
+							Nodes []struct {
+								Number    githubv4.Int
+								Title     githubv4.String
+								CreatedAt githubv4.DateTime
+								Category  struct {
+									Name githubv4.String
+								} `graphql:"category"`
+								URL githubv4.String `graphql:"url"`
+							}
+						} `graphql:"discussions(first: 100, categoryId: $categoryId)"`
+					} `graphql:"repository(owner: $owner, name: $repo)"`
+				}
+				vars := map[string]interface{}{
+					"owner":      githubv4.String(owner),
+					"repo":       githubv4.String(repo),
+					"categoryId": *categoryID,
+				}
+				if err := client.Query(ctx, &query, vars); err != nil {
+					return mcp.NewToolResultError(err.Error()), nil
+				}
+
+				// Map nodes to GitHub Issue objects
+				for _, n := range query.Repository.Discussions.Nodes {
+					di := &github.Issue{
+						Number:    github.Ptr(int(n.Number)),
+						Title:     github.Ptr(string(n.Title)),
+						HTMLURL:   github.Ptr(string(n.URL)),
+						CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time},
+						Labels: []*github.Label{
+							{
+								Name: github.Ptr(fmt.Sprintf("category:%s", string(n.Category.Name))),
+							},
+						},
+					}
+					discussions = append(discussions, di)
+				}
+			} else {
+				// Query without category filter
+				var query struct {
+					Repository struct {
+						Discussions struct {
+							Nodes []struct {
+								Number    githubv4.Int
+								Title     githubv4.String
+								CreatedAt githubv4.DateTime
+								Category  struct {
+									Name githubv4.String
+								} `graphql:"category"`
+								URL githubv4.String `graphql:"url"`
+							}
+						} `graphql:"discussions(first: 100)"`
+					} `graphql:"repository(owner: $owner, name: $repo)"`
+				}
+				vars := map[string]interface{}{
+					"owner": githubv4.String(owner),
+					"repo":  githubv4.String(repo),
+				}
+				if err := client.Query(ctx, &query, vars); err != nil {
+					return mcp.NewToolResultError(err.Error()), nil
+				}
+
+				// Map nodes to GitHub Issue objects
+				for _, n := range query.Repository.Discussions.Nodes {
+					di := &github.Issue{
+						Number:    github.Ptr(int(n.Number)),
+						Title:     github.Ptr(string(n.Title)),
+						HTMLURL:   github.Ptr(string(n.URL)),
+						CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time},
+						Labels: []*github.Label{
+							{
+								Name: github.Ptr(fmt.Sprintf("category:%s", string(n.Category.Name))),
+							},
+						},
+					}
+					discussions = append(discussions, di)
+				}
+			}
+
+			// Marshal and return
+			out, err := json.Marshal(discussions)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal discussions: %w", err)
+			}
+			return mcp.NewToolResultText(string(out)), nil
+		}
+}
+
+func GetDiscussion(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("get_discussion",
+			mcp.WithDescription(t("TOOL_GET_DISCUSSION_DESCRIPTION", "Get a specific discussion by ID")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_GET_DISCUSSION_USER_TITLE", "Get discussion"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithNumber("discussionNumber",
+				mcp.Required(),
+				mcp.Description("Discussion Number"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			// Decode params
+			var params struct {
+				Owner            string
+				Repo             string
+				DiscussionNumber int32
+			}
+			if err := mapstructure.Decode(request.Params.Arguments, &params); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			client, err := getGQLClient(ctx)
+			if err != nil {
+				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
+			}
+
+			var q struct {
+				Repository struct {
+					Discussion struct {
+						Number    githubv4.Int
+						Body      githubv4.String
+						State     githubv4.String
+						CreatedAt githubv4.DateTime
+						URL       githubv4.String `graphql:"url"`
+						Category  struct {
+							Name githubv4.String
+						} `graphql:"category"`
+					} `graphql:"discussion(number: $discussionNumber)"`
+				} `graphql:"repository(owner: $owner, name: $repo)"`
+			}
+			vars := map[string]interface{}{
+				"owner":            githubv4.String(params.Owner),
+				"repo":             githubv4.String(params.Repo),
+				"discussionNumber": githubv4.Int(params.DiscussionNumber),
+			}
+			if err := client.Query(ctx, &q, vars); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			d := q.Repository.Discussion
+			discussion := &github.Issue{
+				Number:    github.Ptr(int(d.Number)),
+				Body:      github.Ptr(string(d.Body)),
+				State:     github.Ptr(string(d.State)),
+				HTMLURL:   github.Ptr(string(d.URL)),
+				CreatedAt: &github.Timestamp{Time: d.CreatedAt.Time},
+				Labels: []*github.Label{
+					{
+						Name: github.Ptr(fmt.Sprintf("category:%s", string(d.Category.Name))),
+					},
+				},
+			}
+			out, err := json.Marshal(discussion)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal discussion: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(out)), nil
+		}
+}
+
+func GetDiscussionComments(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("get_discussion_comments",
+			mcp.WithDescription(t("TOOL_GET_DISCUSSION_COMMENTS_DESCRIPTION", "Get comments from a discussion")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_GET_DISCUSSION_COMMENTS_USER_TITLE", "Get discussion comments"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+			mcp.WithString("owner", mcp.Required(), mcp.Description("Repository owner")),
+			mcp.WithString("repo", mcp.Required(), mcp.Description("Repository name")),
+			mcp.WithNumber("discussionNumber", mcp.Required(), mcp.Description("Discussion Number")),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			// Decode params
+			var params struct {
+				Owner            string
+				Repo             string
+				DiscussionNumber int32
+			}
+			if err := mapstructure.Decode(request.Params.Arguments, &params); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			client, err := getGQLClient(ctx)
+			if err != nil {
+				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
+			}
+
+			var q struct {
+				Repository struct {
+					Discussion struct {
+						Comments struct {
+							Nodes []struct {
+								Body githubv4.String
+							}
+						} `graphql:"comments(first:100)"`
+					} `graphql:"discussion(number: $discussionNumber)"`
+				} `graphql:"repository(owner: $owner, name: $repo)"`
+			}
+			vars := map[string]interface{}{
+				"owner":            githubv4.String(params.Owner),
+				"repo":             githubv4.String(params.Repo),
+				"discussionNumber": githubv4.Int(params.DiscussionNumber),
+			}
+			if err := client.Query(ctx, &q, vars); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			var comments []*github.IssueComment
+			for _, c := range q.Repository.Discussion.Comments.Nodes {
+				comments = append(comments, &github.IssueComment{Body: github.Ptr(string(c.Body))})
+			}
+
+			out, err := json.Marshal(comments)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal comments: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(out)), nil
+		}
+}
+
+func ListDiscussionCategories(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("list_discussion_categories",
+			mcp.WithDescription(t("TOOL_LIST_DISCUSSION_CATEGORIES_DESCRIPTION", "List discussion categories with their id and name, for a repository")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_LIST_DISCUSSION_CATEGORIES_USER_TITLE", "List discussion categories"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithNumber("first",
+				mcp.Description("Number of categories to return per page (min 1, max 100)"),
+				mcp.Min(1),
+				mcp.Max(100),
+			),
+			mcp.WithNumber("last",
+				mcp.Description("Number of categories to return from the end (min 1, max 100)"),
+				mcp.Min(1),
+				mcp.Max(100),
+			),
+			mcp.WithString("after",
+				mcp.Description("Cursor for pagination, use the 'after' field from the previous response"),
+			),
+			mcp.WithString("before",
+				mcp.Description("Cursor for pagination, use the 'before' field from the previous response"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			// Decode params
+			var params struct {
+				Owner  string
+				Repo   string
+				First  int32
+				Last   int32
+				After  string
+				Before string
+			}
+			if err := mapstructure.Decode(request.Params.Arguments, &params); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			// Validate pagination parameters
+			if params.First != 0 && params.Last != 0 {
+				return mcp.NewToolResultError("only one of 'first' or 'last' may be specified"), nil
+			}
+			if params.After != "" && params.Before != "" {
+				return mcp.NewToolResultError("only one of 'after' or 'before' may be specified"), nil
+			}
+			if params.After != "" && params.Last != 0 {
+				return mcp.NewToolResultError("'after' cannot be used with 'last'. Did you mean to use 'before' instead?"), nil
+			}
+			if params.Before != "" && params.First != 0 {
+				return mcp.NewToolResultError("'before' cannot be used with 'first'. Did you mean to use 'after' instead?"), nil
+			}
+
+			client, err := getGQLClient(ctx)
+			if err != nil {
+				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
+			}
+			var q struct {
+				Repository struct {
+					DiscussionCategories struct {
+						Nodes []struct {
+							ID   githubv4.ID
+							Name githubv4.String
+						}
+					} `graphql:"discussionCategories(first: 100)"`
+				} `graphql:"repository(owner: $owner, name: $repo)"`
+			}
+			vars := map[string]interface{}{
+				"owner": githubv4.String(params.Owner),
+				"repo":  githubv4.String(params.Repo),
+			}
+			if err := client.Query(ctx, &q, vars); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			var categories []map[string]string
+			for _, c := range q.Repository.DiscussionCategories.Nodes {
+				categories = append(categories, map[string]string{
+					"id":   fmt.Sprint(c.ID),
+					"name": string(c.Name),
+				})
+			}
+			out, err := json.Marshal(categories)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal discussion categories: %w", err)
+			}
+			return mcp.NewToolResultText(string(out)), nil
+		}
+}
diff --git a/pkg/github/discussions_test.go b/pkg/github/discussions_test.go
new file mode 100644
index 000000000..545d604f9
--- /dev/null
+++ b/pkg/github/discussions_test.go
@@ -0,0 +1,400 @@
+package github
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/github/github-mcp-server/internal/githubv4mock"
+	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/google/go-github/v72/github"
+	"github.com/shurcooL/githubv4"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+var (
+	discussionsGeneral = []map[string]any{
+		{"number": 1, "title": "Discussion 1 title", "createdAt": "2023-01-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/1", "category": map[string]any{"name": "General"}},
+		{"number": 3, "title": "Discussion 3 title", "createdAt": "2023-03-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/3", "category": map[string]any{"name": "General"}},
+	}
+	discussionsAll = []map[string]any{
+		{"number": 1, "title": "Discussion 1 title", "createdAt": "2023-01-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/1", "category": map[string]any{"name": "General"}},
+		{"number": 2, "title": "Discussion 2 title", "createdAt": "2023-02-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/2", "category": map[string]any{"name": "Questions"}},
+		{"number": 3, "title": "Discussion 3 title", "createdAt": "2023-03-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/3", "category": map[string]any{"name": "General"}},
+	}
+	mockResponseListAll = githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussions": map[string]any{"nodes": discussionsAll},
+		},
+	})
+	mockResponseListGeneral = githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussions": map[string]any{"nodes": discussionsGeneral},
+		},
+	})
+	mockErrorRepoNotFound = githubv4mock.ErrorResponse("repository not found")
+)
+
+func Test_ListDiscussions(t *testing.T) {
+	mockClient := githubv4.NewClient(nil)
+	// Verify tool definition and schema
+	toolDef, _ := ListDiscussions(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper)
+	assert.Equal(t, "list_discussions", toolDef.Name)
+	assert.NotEmpty(t, toolDef.Description)
+	assert.Contains(t, toolDef.InputSchema.Properties, "owner")
+	assert.Contains(t, toolDef.InputSchema.Properties, "repo")
+	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo"})
+
+	// mock for the call to ListDiscussions without category filter
+	var qDiscussions struct {
+		Repository struct {
+			Discussions struct {
+				Nodes []struct {
+					Number    githubv4.Int
+					Title     githubv4.String
+					CreatedAt githubv4.DateTime
+					Category  struct {
+						Name githubv4.String
+					} `graphql:"category"`
+					URL githubv4.String `graphql:"url"`
+				}
+			} `graphql:"discussions(first: 100)"`
+		} `graphql:"repository(owner: $owner, name: $repo)"`
+	}
+
+	// mock for the call to get discussions with category filter
+	var qDiscussionsFiltered struct {
+		Repository struct {
+			Discussions struct {
+				Nodes []struct {
+					Number    githubv4.Int
+					Title     githubv4.String
+					CreatedAt githubv4.DateTime
+					Category  struct {
+						Name githubv4.String
+					} `graphql:"category"`
+					URL githubv4.String `graphql:"url"`
+				}
+			} `graphql:"discussions(first: 100, categoryId: $categoryId)"`
+		} `graphql:"repository(owner: $owner, name: $repo)"`
+	}
+
+	varsListAll := map[string]interface{}{
+		"owner": githubv4.String("owner"),
+		"repo":  githubv4.String("repo"),
+	}
+
+	varsRepoNotFound := map[string]interface{}{
+		"owner": githubv4.String("owner"),
+		"repo":  githubv4.String("nonexistent-repo"),
+	}
+
+	varsDiscussionsFiltered := map[string]interface{}{
+		"owner":      githubv4.String("owner"),
+		"repo":       githubv4.String("repo"),
+		"categoryId": githubv4.ID("DIC_kwDOABC123"),
+	}
+
+	tests := []struct {
+		name          string
+		reqParams     map[string]interface{}
+		expectError   bool
+		errContains   string
+		expectedCount int
+	}{
+		{
+			name: "list all discussions without category filter",
+			reqParams: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+			},
+			expectError:   false,
+			expectedCount: 3, // All discussions
+		},
+		{
+			name: "filter by category ID",
+			reqParams: map[string]interface{}{
+				"owner":    "owner",
+				"repo":     "repo",
+				"category": "DIC_kwDOABC123",
+			},
+			expectError:   false,
+			expectedCount: 2, // Only General discussions (matching the category ID)
+		},
+		{
+			name: "repository not found error",
+			reqParams: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "nonexistent-repo",
+			},
+			expectError: true,
+			errContains: "repository not found",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var httpClient *http.Client
+
+			switch tc.name {
+			case "list all discussions without category filter":
+				// Simple case - no category filter
+				matcher := githubv4mock.NewQueryMatcher(qDiscussions, varsListAll, mockResponseListAll)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "filter by category ID":
+				// Simple case - category filter using category ID directly
+				matcher := githubv4mock.NewQueryMatcher(qDiscussionsFiltered, varsDiscussionsFiltered, mockResponseListGeneral)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "repository not found error":
+				matcher := githubv4mock.NewQueryMatcher(qDiscussions, varsRepoNotFound, mockErrorRepoNotFound)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			}
+
+			gqlClient := githubv4.NewClient(httpClient)
+			_, handler := ListDiscussions(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper)
+
+			req := createMCPRequest(tc.reqParams)
+			res, err := handler(context.Background(), req)
+			text := getTextResult(t, res).Text
+
+			if tc.expectError {
+				require.True(t, res.IsError)
+				assert.Contains(t, text, tc.errContains)
+				return
+			}
+			require.NoError(t, err)
+
+			var returnedDiscussions []*github.Issue
+			err = json.Unmarshal([]byte(text), &returnedDiscussions)
+			require.NoError(t, err)
+
+			assert.Len(t, returnedDiscussions, tc.expectedCount, "Expected %d discussions, got %d", tc.expectedCount, len(returnedDiscussions))
+
+			// Verify that all returned discussions have a category label if filtered
+			if _, hasCategory := tc.reqParams["category"]; hasCategory {
+				for _, discussion := range returnedDiscussions {
+					require.NotEmpty(t, discussion.Labels, "Discussion should have category label")
+					assert.True(t, strings.HasPrefix(*discussion.Labels[0].Name, "category:"), "Discussion should have category label prefix")
+				}
+			}
+		})
+	}
+}
+
+func Test_GetDiscussion(t *testing.T) {
+	// Verify tool definition and schema
+	toolDef, _ := GetDiscussion(nil, translations.NullTranslationHelper)
+	assert.Equal(t, "get_discussion", toolDef.Name)
+	assert.NotEmpty(t, toolDef.Description)
+	assert.Contains(t, toolDef.InputSchema.Properties, "owner")
+	assert.Contains(t, toolDef.InputSchema.Properties, "repo")
+	assert.Contains(t, toolDef.InputSchema.Properties, "discussionNumber")
+	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo", "discussionNumber"})
+
+	var q struct {
+		Repository struct {
+			Discussion struct {
+				Number    githubv4.Int
+				Body      githubv4.String
+				State     githubv4.String
+				CreatedAt githubv4.DateTime
+				URL       githubv4.String `graphql:"url"`
+				Category  struct {
+					Name githubv4.String
+				} `graphql:"category"`
+			} `graphql:"discussion(number: $discussionNumber)"`
+		} `graphql:"repository(owner: $owner, name: $repo)"`
+	}
+	vars := map[string]interface{}{
+		"owner":            githubv4.String("owner"),
+		"repo":             githubv4.String("repo"),
+		"discussionNumber": githubv4.Int(1),
+	}
+	tests := []struct {
+		name        string
+		response    githubv4mock.GQLResponse
+		expectError bool
+		expected    *github.Issue
+		errContains string
+	}{
+		{
+			name: "successful retrieval",
+			response: githubv4mock.DataResponse(map[string]any{
+				"repository": map[string]any{"discussion": map[string]any{
+					"number":    1,
+					"body":      "This is a test discussion",
+					"state":     "open",
+					"url":       "https://github.com/owner/repo/discussions/1",
+					"createdAt": "2025-04-25T12:00:00Z",
+					"category":  map[string]any{"name": "General"},
+				}},
+			}),
+			expectError: false,
+			expected: &github.Issue{
+				HTMLURL:   github.Ptr("https://github.com/owner/repo/discussions/1"),
+				Number:    github.Ptr(1),
+				Body:      github.Ptr("This is a test discussion"),
+				State:     github.Ptr("open"),
+				CreatedAt: &github.Timestamp{Time: time.Date(2025, 4, 25, 12, 0, 0, 0, time.UTC)},
+				Labels: []*github.Label{
+					{
+						Name: github.Ptr("category:General"),
+					},
+				},
+			},
+		},
+		{
+			name:        "discussion not found",
+			response:    githubv4mock.ErrorResponse("discussion not found"),
+			expectError: true,
+			errContains: "discussion not found",
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			matcher := githubv4mock.NewQueryMatcher(q, vars, tc.response)
+			httpClient := githubv4mock.NewMockedHTTPClient(matcher)
+			gqlClient := githubv4.NewClient(httpClient)
+			_, handler := GetDiscussion(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper)
+
+			req := createMCPRequest(map[string]interface{}{"owner": "owner", "repo": "repo", "discussionNumber": int32(1)})
+			res, err := handler(context.Background(), req)
+			text := getTextResult(t, res).Text
+
+			if tc.expectError {
+				require.True(t, res.IsError)
+				assert.Contains(t, text, tc.errContains)
+				return
+			}
+
+			require.NoError(t, err)
+			var out github.Issue
+			require.NoError(t, json.Unmarshal([]byte(text), &out))
+			assert.Equal(t, *tc.expected.HTMLURL, *out.HTMLURL)
+			assert.Equal(t, *tc.expected.Number, *out.Number)
+			assert.Equal(t, *tc.expected.Body, *out.Body)
+			assert.Equal(t, *tc.expected.State, *out.State)
+			// Check category label
+			require.Len(t, out.Labels, 1)
+			assert.Equal(t, *tc.expected.Labels[0].Name, *out.Labels[0].Name)
+		})
+	}
+}
+
+func Test_GetDiscussionComments(t *testing.T) {
+	// Verify tool definition and schema
+	toolDef, _ := GetDiscussionComments(nil, translations.NullTranslationHelper)
+	assert.Equal(t, "get_discussion_comments", toolDef.Name)
+	assert.NotEmpty(t, toolDef.Description)
+	assert.Contains(t, toolDef.InputSchema.Properties, "owner")
+	assert.Contains(t, toolDef.InputSchema.Properties, "repo")
+	assert.Contains(t, toolDef.InputSchema.Properties, "discussionNumber")
+	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo", "discussionNumber"})
+
+	var q struct {
+		Repository struct {
+			Discussion struct {
+				Comments struct {
+					Nodes []struct {
+						Body githubv4.String
+					}
+				} `graphql:"comments(first:100)"`
+			} `graphql:"discussion(number: $discussionNumber)"`
+		} `graphql:"repository(owner: $owner, name: $repo)"`
+	}
+	vars := map[string]interface{}{
+		"owner":            githubv4.String("owner"),
+		"repo":             githubv4.String("repo"),
+		"discussionNumber": githubv4.Int(1),
+	}
+	mockResponse := githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussion": map[string]any{
+				"comments": map[string]any{
+					"nodes": []map[string]any{
+						{"body": "This is the first comment"},
+						{"body": "This is the second comment"},
+					},
+				},
+			},
+		},
+	})
+	matcher := githubv4mock.NewQueryMatcher(q, vars, mockResponse)
+	httpClient := githubv4mock.NewMockedHTTPClient(matcher)
+	gqlClient := githubv4.NewClient(httpClient)
+	_, handler := GetDiscussionComments(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper)
+
+	request := createMCPRequest(map[string]interface{}{
+		"owner":            "owner",
+		"repo":             "repo",
+		"discussionNumber": int32(1),
+	})
+
+	result, err := handler(context.Background(), request)
+	require.NoError(t, err)
+
+	textContent := getTextResult(t, result)
+
+	var returnedComments []*github.IssueComment
+	err = json.Unmarshal([]byte(textContent.Text), &returnedComments)
+	require.NoError(t, err)
+	assert.Len(t, returnedComments, 2)
+	expectedBodies := []string{"This is the first comment", "This is the second comment"}
+	for i, comment := range returnedComments {
+		assert.Equal(t, expectedBodies[i], *comment.Body)
+	}
+}
+
+func Test_ListDiscussionCategories(t *testing.T) {
+	var q struct {
+		Repository struct {
+			DiscussionCategories struct {
+				Nodes []struct {
+					ID   githubv4.ID
+					Name githubv4.String
+				}
+			} `graphql:"discussionCategories(first: 100)"`
+		} `graphql:"repository(owner: $owner, name: $repo)"`
+	}
+	vars := map[string]interface{}{
+		"owner": githubv4.String("owner"),
+		"repo":  githubv4.String("repo"),
+	}
+	mockResp := githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussionCategories": map[string]any{
+				"nodes": []map[string]any{
+					{"id": "123", "name": "CategoryOne"},
+					{"id": "456", "name": "CategoryTwo"},
+				},
+			},
+		},
+	})
+	matcher := githubv4mock.NewQueryMatcher(q, vars, mockResp)
+	httpClient := githubv4mock.NewMockedHTTPClient(matcher)
+	gqlClient := githubv4.NewClient(httpClient)
+
+	tool, handler := ListDiscussionCategories(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper)
+	assert.Equal(t, "list_discussion_categories", tool.Name)
+	assert.NotEmpty(t, tool.Description)
+	assert.Contains(t, tool.InputSchema.Properties, "owner")
+	assert.Contains(t, tool.InputSchema.Properties, "repo")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"})
+
+	request := createMCPRequest(map[string]interface{}{"owner": "owner", "repo": "repo"})
+	result, err := handler(context.Background(), request)
+	require.NoError(t, err)
+
+	text := getTextResult(t, result).Text
+	var categories []map[string]string
+	require.NoError(t, json.Unmarshal([]byte(text), &categories))
+	assert.Len(t, categories, 2)
+	assert.Equal(t, "123", categories[0]["id"])
+	assert.Equal(t, "CategoryOne", categories[0]["name"])
+	assert.Equal(t, "456", categories[1]["id"])
+	assert.Equal(t, "CategoryTwo", categories[1]["name"])
+}
diff --git a/pkg/github/tools.go b/pkg/github/tools.go
index 76b31d477..9f36cfc3d 100644
--- a/pkg/github/tools.go
+++ b/pkg/github/tools.go
@@ -116,6 +116,14 @@ func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetG
 			toolsets.NewServerTool(ManageRepositoryNotificationSubscription(getClient, t)),
 		)
 
+	discussions := toolsets.NewToolset("discussions", "GitHub Discussions related tools").
+		AddReadTools(
+			toolsets.NewServerTool(ListDiscussions(getGQLClient, t)),
+			toolsets.NewServerTool(GetDiscussion(getGQLClient, t)),
+			toolsets.NewServerTool(GetDiscussionComments(getGQLClient, t)),
+			toolsets.NewServerTool(ListDiscussionCategories(getGQLClient, t)),
+		)
+
 	actions := toolsets.NewToolset("actions", "GitHub Actions workflows and CI/CD operations").
 		AddReadTools(
 			toolsets.NewServerTool(ListWorkflows(getClient, t)),
@@ -156,6 +164,7 @@ func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetG
 	tsg.AddToolset(secretProtection)
 	tsg.AddToolset(notifications)
 	tsg.AddToolset(experiments)
+	tsg.AddToolset(discussions)
 
 	return tsg
 }
diff --git a/script/get-discussions b/script/get-discussions
new file mode 100755
index 000000000..3e68abf24
--- /dev/null
+++ b/script/get-discussions
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# echo '{"jsonrpc":"2.0","id":3,"params":{"name":"list_discussions","arguments": {"owner": "github", "repo": "securitylab", "first": 10, "since": "2025-04-01T00:00:00Z"}},"method":"tools/call"}' | go run  cmd/github-mcp-server/main.go stdio  | jq .
+echo '{"jsonrpc":"2.0","id":3,"params":{"name":"list_discussions","arguments": {"owner": "github", "repo": "securitylab", "first": 10, "since": "2025-04-01T00:00:00Z", "sort": "CREATED_AT", "direction": "DESC"}},"method":"tools/call"}' | go run  cmd/github-mcp-server/main.go stdio  | jq .
+

From 6043bec223ef0de6b05fd3bdc40ed11ca4011ebb Mon Sep 17 00:00:00 2001
From: JoannaaKL <joannaakl@github.com>
Date: Wed, 2 Jul 2025 18:12:16 +0200
Subject: [PATCH 03/32] Cleanup (#628)

* Remove unused function and add test script

* Call test from the workflow
---
 .github/workflows/go.yml  |  2 +-
 pkg/github/discussions.go | 50 ---------------------------------------
 script/lint               |  1 -
 script/test               |  3 +++
 4 files changed, 4 insertions(+), 52 deletions(-)
 create mode 100755 script/test

diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
index 0a45569ec..e3ef25022 100644
--- a/.github/workflows/go.yml
+++ b/.github/workflows/go.yml
@@ -26,7 +26,7 @@ jobs:
         run: go mod download
 
       - name: Run unit tests
-        run: go test -race ./...
+        run: script/test
 
       - name: Build
         run: go build -v ./cmd/github-mcp-server
diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go
index d61fe969d..a7ec8e20f 100644
--- a/pkg/github/discussions.go
+++ b/pkg/github/discussions.go
@@ -13,56 +13,6 @@ import (
 	"github.com/shurcooL/githubv4"
 )
 
-// GetAllDiscussionCategories retrieves all discussion categories for a repository
-// by paginating through all pages and returns them as a map where the key is the
-// category name and the value is the category ID.
-func GetAllDiscussionCategories(ctx context.Context, client *githubv4.Client, owner, repo string) (map[string]string, error) {
-	categories := make(map[string]string)
-	var after string
-	hasNextPage := true
-
-	for hasNextPage {
-		// Prepare GraphQL query with pagination
-		var q struct {
-			Repository struct {
-				DiscussionCategories struct {
-					Nodes []struct {
-						ID   githubv4.ID
-						Name githubv4.String
-					}
-					PageInfo struct {
-						HasNextPage githubv4.Boolean
-						EndCursor   githubv4.String
-					}
-				} `graphql:"discussionCategories(first: 100, after: $after)"`
-			} `graphql:"repository(owner: $owner, name: $repo)"`
-		}
-
-		vars := map[string]interface{}{
-			"owner": githubv4.String(owner),
-			"repo":  githubv4.String(repo),
-			"after": githubv4.String(after),
-		}
-
-		if err := client.Query(ctx, &q, vars); err != nil {
-			return nil, fmt.Errorf("failed to query discussion categories: %w", err)
-		}
-
-		// Add categories to the map
-		for _, category := range q.Repository.DiscussionCategories.Nodes {
-			categories[string(category.Name)] = fmt.Sprint(category.ID)
-		}
-
-		// Check if there are more pages
-		hasNextPage = bool(q.Repository.DiscussionCategories.PageInfo.HasNextPage)
-		if hasNextPage {
-			after = string(q.Repository.DiscussionCategories.PageInfo.EndCursor)
-		}
-	}
-
-	return categories, nil
-}
-
 func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_discussions",
 			mcp.WithDescription(t("TOOL_LIST_DISCUSSIONS_DESCRIPTION", "List discussions for a repository")),
diff --git a/script/lint b/script/lint
index 58884e3a0..e6ea9da89 100755
--- a/script/lint
+++ b/script/lint
@@ -7,7 +7,6 @@ BINDIR="$(git rev-parse --show-toplevel)"/bin
 BINARY=$BINDIR/golangci-lint
 GOLANGCI_LINT_VERSION=v2.2.1
 
-
 if [ ! -f "$BINARY" ]; then
     curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s "$GOLANGCI_LINT_VERSION"
 fi
diff --git a/script/test b/script/test
new file mode 100755
index 000000000..7f0dd0c20
--- /dev/null
+++ b/script/test
@@ -0,0 +1,3 @@
+set -eu
+
+go test -race ./...
\ No newline at end of file

From f88456f9897fb9eb1252b2502598761e53c9731a Mon Sep 17 00:00:00 2001
From: JoannaaKL <joannaakl@github.com>
Date: Wed, 2 Jul 2025 20:07:59 +0200
Subject: [PATCH 04/32] Update list commits tool description (#629)

---
 README.md                                  |  2 +-
 pkg/github/__toolsnaps__/list_commits.snap |  4 ++--
 pkg/github/repositories.go                 | 12 ++++++++----
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index b4c326c0e..8a0364932 100644
--- a/README.md
+++ b/README.md
@@ -903,7 +903,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
-  - `sha`: SHA or Branch name (string, optional)
+  - `sha`: The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch. (string, optional)
 
 - **list_tags** - List tags
   - `owner`: Repository owner (string, required)
diff --git a/pkg/github/__toolsnaps__/list_commits.snap b/pkg/github/__toolsnaps__/list_commits.snap
index 1e769c718..c43f7b0cd 100644
--- a/pkg/github/__toolsnaps__/list_commits.snap
+++ b/pkg/github/__toolsnaps__/list_commits.snap
@@ -3,7 +3,7 @@
     "title": "List commits",
     "readOnlyHint": true
   },
-  "description": "Get list of commits of a branch in a GitHub repository",
+  "description": "Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).",
   "inputSchema": {
     "properties": {
       "author": {
@@ -30,7 +30,7 @@
         "type": "string"
       },
       "sha": {
-        "description": "SHA or Branch name",
+        "description": "The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch.",
         "type": "string"
       }
     },
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index 5b116745e..29f776a05 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -97,7 +97,7 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too
 // ListCommits creates a tool to get commits of a branch in a repository.
 func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_commits",
-			mcp.WithDescription(t("TOOL_LIST_COMMITS_DESCRIPTION", "Get list of commits of a branch in a GitHub repository")),
+			mcp.WithDescription(t("TOOL_LIST_COMMITS_DESCRIPTION", "Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
 				Title:        t("TOOL_LIST_COMMITS_USER_TITLE", "List commits"),
 				ReadOnlyHint: ToBoolPtr(true),
@@ -111,7 +111,7 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 				mcp.Description("Repository name"),
 			),
 			mcp.WithString("sha",
-				mcp.Description("SHA or Branch name"),
+				mcp.Description("The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch."),
 			),
 			mcp.WithString("author",
 				mcp.Description("Author username or email address"),
@@ -139,13 +139,17 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
-
+			// Set default perPage to 30 if not provided
+			perPage := pagination.perPage
+			if perPage == 0 {
+				perPage = 30
+			}
 			opts := &github.CommitsListOptions{
 				SHA:    sha,
 				Author: author,
 				ListOptions: github.ListOptions{
 					Page:    pagination.page,
-					PerPage: pagination.perPage,
+					PerPage: perPage,
 				},
 			}
 

From 23f6f3a7780ab9c5d3a38703b555911fad1dc24a Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Thu, 3 Jul 2025 12:26:57 +0100
Subject: [PATCH 05/32] Add Dependabot Alert Tools (#631)

* add dependabit get and list tools

* add toolsnaps

* add unit tests for new tools

* generate-docs
---
 README.md                                     |  18 ++
 docs/remote-server.md                         |   1 +
 .../__toolsnaps__/get_dependabot_alert.snap   |  30 ++
 .../__toolsnaps__/list_dependabot_alerts.snap |  46 +++
 pkg/github/dependabot.go                      | 161 ++++++++++
 pkg/github/dependabot_test.go                 | 276 ++++++++++++++++++
 pkg/github/tools.go                           |  15 +
 7 files changed, 547 insertions(+)
 create mode 100644 pkg/github/__toolsnaps__/get_dependabot_alert.snap
 create mode 100644 pkg/github/__toolsnaps__/list_dependabot_alerts.snap
 create mode 100644 pkg/github/dependabot.go
 create mode 100644 pkg/github/dependabot_test.go

diff --git a/README.md b/README.md
index 8a0364932..0bb054355 100644
--- a/README.md
+++ b/README.md
@@ -269,6 +269,7 @@ The following sets of tools are available (all are on by default):
 | `context`               | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in |
 | `actions` | GitHub Actions workflows and CI/CD operations |
 | `code_security` | Code security related tools, such as GitHub Code Scanning |
+| `dependabot` | Dependabot tools |
 | `discussions` | GitHub Discussions related tools |
 | `experiments` | Experimental features that are not considered stable yet |
 | `issues` | GitHub Issues related tools |
@@ -555,6 +556,23 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 
 <details>
 
+<summary>Dependabot</summary>
+
+- **get_dependabot_alert** - Get dependabot alert
+  - `alertNumber`: The number of the alert. (number, required)
+  - `owner`: The owner of the repository. (string, required)
+  - `repo`: The name of the repository. (string, required)
+
+- **list_dependabot_alerts** - List dependabot alerts
+  - `owner`: The owner of the repository. (string, required)
+  - `repo`: The name of the repository. (string, required)
+  - `severity`: Filter dependabot alerts by severity (string, optional)
+  - `state`: Filter dependabot alerts by state. Defaults to open (string, optional)
+
+</details>
+
+<details>
+
 <summary>Discussions</summary>
 
 - **get_discussion** - Get discussion
diff --git a/docs/remote-server.md b/docs/remote-server.md
index 7b5f2c0d4..c36124ecc 100644
--- a/docs/remote-server.md
+++ b/docs/remote-server.md
@@ -20,6 +20,7 @@ Below is a table of available toolsets for the remote GitHub MCP Server. Each to
 | all            | All available GitHub MCP tools                    | https://api.githubcopilot.com/mcp/                    | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D)                                      | [read-only](https://api.githubcopilot.com/mcp/readonly)                                                      | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Freadonly%22%7D) |
 | Actions        | GitHub Actions workflows and CI/CD operations    | https://api.githubcopilot.com/mcp/x/actions           | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%22%7D)                         | [read-only](https://api.githubcopilot.com/mcp/x/actions/readonly)                                              | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%2Freadonly%22%7D)                                                                          |
 | Code Security  | Code security related tools, such as GitHub Code Scanning | https://api.githubcopilot.com/mcp/x/code_security     | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%22%7D)             | [read-only](https://api.githubcopilot.com/mcp/x/code_security/readonly)                                        | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%2Freadonly%22%7D)                                                              |
+| Dependabot     | Dependabot tools                                 | https://api.githubcopilot.com/mcp/x/dependabot        | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-dependabot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdependabot%22%7D)                   | [read-only](https://api.githubcopilot.com/mcp/x/dependabot/readonly)                                           | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-dependabot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdependabot%2Freadonly%22%7D)                                                                    |
 | Discussions    | GitHub Discussions related tools                 | https://api.githubcopilot.com/mcp/x/discussions       | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-discussions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdiscussions%22%7D)                 | [read-only](https://api.githubcopilot.com/mcp/x/discussions/readonly)                                          | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-discussions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdiscussions%2Freadonly%22%7D)                                                                  |
 | Experiments    | Experimental features that are not considered stable yet | https://api.githubcopilot.com/mcp/x/experiments       | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%22%7D)                 | [read-only](https://api.githubcopilot.com/mcp/x/experiments/readonly)                                          | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%2Freadonly%22%7D)                                                                  |
 | Issues         | GitHub Issues related tools                      | https://api.githubcopilot.com/mcp/x/issues            | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%22%7D)                           | [read-only](https://api.githubcopilot.com/mcp/x/issues/readonly)                                               | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%2Freadonly%22%7D)                                                                            |
diff --git a/pkg/github/__toolsnaps__/get_dependabot_alert.snap b/pkg/github/__toolsnaps__/get_dependabot_alert.snap
new file mode 100644
index 000000000..76b5ef126
--- /dev/null
+++ b/pkg/github/__toolsnaps__/get_dependabot_alert.snap
@@ -0,0 +1,30 @@
+{
+  "annotations": {
+    "title": "Get dependabot alert",
+    "readOnlyHint": true
+  },
+  "description": "Get details of a specific dependabot alert in a GitHub repository.",
+  "inputSchema": {
+    "properties": {
+      "alertNumber": {
+        "description": "The number of the alert.",
+        "type": "number"
+      },
+      "owner": {
+        "description": "The owner of the repository.",
+        "type": "string"
+      },
+      "repo": {
+        "description": "The name of the repository.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "alertNumber"
+    ],
+    "type": "object"
+  },
+  "name": "get_dependabot_alert"
+}
\ No newline at end of file
diff --git a/pkg/github/__toolsnaps__/list_dependabot_alerts.snap b/pkg/github/__toolsnaps__/list_dependabot_alerts.snap
new file mode 100644
index 000000000..681d640b7
--- /dev/null
+++ b/pkg/github/__toolsnaps__/list_dependabot_alerts.snap
@@ -0,0 +1,46 @@
+{
+  "annotations": {
+    "title": "List dependabot alerts",
+    "readOnlyHint": true
+  },
+  "description": "List dependabot alerts in a GitHub repository.",
+  "inputSchema": {
+    "properties": {
+      "owner": {
+        "description": "The owner of the repository.",
+        "type": "string"
+      },
+      "repo": {
+        "description": "The name of the repository.",
+        "type": "string"
+      },
+      "severity": {
+        "description": "Filter dependabot alerts by severity",
+        "enum": [
+          "low",
+          "medium",
+          "high",
+          "critical"
+        ],
+        "type": "string"
+      },
+      "state": {
+        "default": "open",
+        "description": "Filter dependabot alerts by state. Defaults to open",
+        "enum": [
+          "open",
+          "fixed",
+          "dismissed",
+          "auto_dismissed"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "owner",
+      "repo"
+    ],
+    "type": "object"
+  },
+  "name": "list_dependabot_alerts"
+}
\ No newline at end of file
diff --git a/pkg/github/dependabot.go b/pkg/github/dependabot.go
new file mode 100644
index 000000000..af21b83d1
--- /dev/null
+++ b/pkg/github/dependabot.go
@@ -0,0 +1,161 @@
+package github
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	ghErrors "github.com/github/github-mcp-server/pkg/errors"
+	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/google/go-github/v72/github"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+func GetDependabotAlert(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool(
+			"get_dependabot_alert",
+			mcp.WithDescription(t("TOOL_GET_DEPENDABOT_ALERT_DESCRIPTION", "Get details of a specific dependabot alert in a GitHub repository.")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_GET_DEPENDABOT_ALERT_USER_TITLE", "Get dependabot alert"),
+				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.WithNumber("alertNumber",
+				mcp.Required(),
+				mcp.Description("The number of the alert."),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			alertNumber, err := RequiredInt(request, "alertNumber")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			alert, resp, err := client.Dependabot.GetRepoAlert(ctx, owner, repo, alertNumber)
+			if err != nil {
+				return ghErrors.NewGitHubAPIErrorResponse(ctx,
+					fmt.Sprintf("failed to get alert with number '%d'", alertNumber),
+					resp,
+					err,
+				), nil
+			}
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != http.StatusOK {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to get alert: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(alert)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal alert: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}
+
+func ListDependabotAlerts(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	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"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			state, err := OptionalParam[string](request, "state")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			severity, err := OptionalParam[string](request, "severity")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			alerts, resp, err := client.Dependabot.ListRepoAlerts(ctx, owner, repo, &github.ListAlertsOptions{
+				State:    ToStringPtr(state),
+				Severity: ToStringPtr(severity),
+			})
+			if err != nil {
+				return ghErrors.NewGitHubAPIErrorResponse(ctx,
+					fmt.Sprintf("failed to list alerts for repository '%s/%s'", owner, repo),
+					resp,
+					err,
+				), nil
+			}
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != http.StatusOK {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to list alerts: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(alerts)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal alerts: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}
diff --git a/pkg/github/dependabot_test.go b/pkg/github/dependabot_test.go
new file mode 100644
index 000000000..f7c091981
--- /dev/null
+++ b/pkg/github/dependabot_test.go
@@ -0,0 +1,276 @@
+package github
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/github/github-mcp-server/internal/toolsnaps"
+	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/google/go-github/v72/github"
+	"github.com/migueleliasweb/go-github-mock/src/mock"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_GetDependabotAlert(t *testing.T) {
+	// Verify tool definition
+	mockClient := github.NewClient(nil)
+	tool, _ := GetDependabotAlert(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	require.NoError(t, toolsnaps.Test(tool.Name, tool))
+
+	// Validate tool schema
+	assert.Equal(t, "get_dependabot_alert", tool.Name)
+	assert.NotEmpty(t, tool.Description)
+	assert.Contains(t, tool.InputSchema.Properties, "owner")
+	assert.Contains(t, tool.InputSchema.Properties, "repo")
+	assert.Contains(t, tool.InputSchema.Properties, "alertNumber")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "alertNumber"})
+
+	// Setup mock alert for success case
+	mockAlert := &github.DependabotAlert{
+		Number:  github.Ptr(42),
+		State:   github.Ptr("open"),
+		HTMLURL: github.Ptr("https://github.com/owner/repo/security/dependabot/42"),
+	}
+
+	tests := []struct {
+		name           string
+		mockedClient   *http.Client
+		requestArgs    map[string]interface{}
+		expectError    bool
+		expectedAlert  *github.DependabotAlert
+		expectedErrMsg string
+	}{
+		{
+			name: "successful alert fetch",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatch(
+					mock.GetReposDependabotAlertsByOwnerByRepoByAlertNumber,
+					mockAlert,
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":       "owner",
+				"repo":        "repo",
+				"alertNumber": float64(42),
+			},
+			expectError:   false,
+			expectedAlert: mockAlert,
+		},
+		{
+			name: "alert fetch fails",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposDependabotAlertsByOwnerByRepoByAlertNumber,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusNotFound)
+						_, _ = w.Write([]byte(`{"message": "Not Found"}`))
+					}),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":       "owner",
+				"repo":        "repo",
+				"alertNumber": float64(9999),
+			},
+			expectError:    true,
+			expectedErrMsg: "failed to get alert",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Setup client with mock
+			client := github.NewClient(tc.mockedClient)
+			_, handler := GetDependabotAlert(stubGetClientFn(client), translations.NullTranslationHelper)
+
+			// Create call request
+			request := createMCPRequest(tc.requestArgs)
+
+			// Call handler
+			result, err := handler(context.Background(), request)
+
+			// Verify results
+			if tc.expectError {
+				require.NoError(t, err)
+				require.True(t, result.IsError)
+				errorContent := getErrorResult(t, result)
+				assert.Contains(t, errorContent.Text, tc.expectedErrMsg)
+				return
+			}
+
+			require.NoError(t, err)
+			require.False(t, result.IsError)
+
+			// Parse the result and get the text content if no error
+			textContent := getTextResult(t, result)
+
+			// Unmarshal and verify the result
+			var returnedAlert github.DependabotAlert
+			err = json.Unmarshal([]byte(textContent.Text), &returnedAlert)
+			assert.NoError(t, err)
+			assert.Equal(t, *tc.expectedAlert.Number, *returnedAlert.Number)
+			assert.Equal(t, *tc.expectedAlert.State, *returnedAlert.State)
+			assert.Equal(t, *tc.expectedAlert.HTMLURL, *returnedAlert.HTMLURL)
+		})
+	}
+}
+
+func Test_ListDependabotAlerts(t *testing.T) {
+	// Verify tool definition once
+	mockClient := github.NewClient(nil)
+	tool, _ := ListDependabotAlerts(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	require.NoError(t, toolsnaps.Test(tool.Name, tool))
+
+	assert.Equal(t, "list_dependabot_alerts", tool.Name)
+	assert.NotEmpty(t, tool.Description)
+	assert.Contains(t, tool.InputSchema.Properties, "owner")
+	assert.Contains(t, tool.InputSchema.Properties, "repo")
+	assert.Contains(t, tool.InputSchema.Properties, "state")
+	assert.Contains(t, tool.InputSchema.Properties, "severity")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"})
+
+	// Setup mock alerts for success case
+	criticalAlert := github.DependabotAlert{
+		Number:  github.Ptr(1),
+		HTMLURL: github.Ptr("https://github.com/owner/repo/security/dependabot/1"),
+		State:   github.Ptr("open"),
+		SecurityAdvisory: &github.DependabotSecurityAdvisory{
+			Severity: github.Ptr("critical"),
+		},
+	}
+	highSeverityAlert := github.DependabotAlert{
+		Number:  github.Ptr(2),
+		HTMLURL: github.Ptr("https://github.com/owner/repo/security/dependabot/2"),
+		State:   github.Ptr("fixed"),
+		SecurityAdvisory: &github.DependabotSecurityAdvisory{
+			Severity: github.Ptr("high"),
+		},
+	}
+
+	tests := []struct {
+		name           string
+		mockedClient   *http.Client
+		requestArgs    map[string]interface{}
+		expectError    bool
+		expectedAlerts []*github.DependabotAlert
+		expectedErrMsg string
+	}{
+		{
+			name: "successful open alerts listing",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposDependabotAlertsByOwnerByRepo,
+					expectQueryParams(t, map[string]string{
+						"state": "open",
+					}).andThen(
+						mockResponse(t, http.StatusOK, []*github.DependabotAlert{&criticalAlert}),
+					),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+				"state": "open",
+			},
+			expectError:    false,
+			expectedAlerts: []*github.DependabotAlert{&criticalAlert},
+		},
+		{
+			name: "successful severity filtered listing",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposDependabotAlertsByOwnerByRepo,
+					expectQueryParams(t, map[string]string{
+						"severity": "high",
+					}).andThen(
+						mockResponse(t, http.StatusOK, []*github.DependabotAlert{&highSeverityAlert}),
+					),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":    "owner",
+				"repo":     "repo",
+				"severity": "high",
+			},
+			expectError:    false,
+			expectedAlerts: []*github.DependabotAlert{&highSeverityAlert},
+		},
+		{
+			name: "successful all alerts listing",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposDependabotAlertsByOwnerByRepo,
+					expectQueryParams(t, map[string]string{}).andThen(
+						mockResponse(t, http.StatusOK, []*github.DependabotAlert{&criticalAlert, &highSeverityAlert}),
+					),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+			},
+			expectError:    false,
+			expectedAlerts: []*github.DependabotAlert{&criticalAlert, &highSeverityAlert},
+		},
+		{
+			name: "alerts listing fails",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposDependabotAlertsByOwnerByRepo,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusUnauthorized)
+						_, _ = w.Write([]byte(`{"message": "Unauthorized access"}`))
+					}),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+			},
+			expectError:    true,
+			expectedErrMsg: "failed to list alerts",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			client := github.NewClient(tc.mockedClient)
+			_, handler := ListDependabotAlerts(stubGetClientFn(client), translations.NullTranslationHelper)
+
+			request := createMCPRequest(tc.requestArgs)
+
+			result, err := handler(context.Background(), request)
+
+			if tc.expectError {
+				require.NoError(t, err)
+				require.True(t, result.IsError)
+				errorContent := getErrorResult(t, result)
+				assert.Contains(t, errorContent.Text, tc.expectedErrMsg)
+				return
+			}
+
+			require.NoError(t, err)
+			require.False(t, result.IsError)
+
+			textContent := getTextResult(t, result)
+
+			// Unmarshal and verify the result
+			var returnedAlerts []*github.DependabotAlert
+			err = json.Unmarshal([]byte(textContent.Text), &returnedAlerts)
+			assert.NoError(t, err)
+			assert.Len(t, returnedAlerts, len(tc.expectedAlerts))
+			for i, alert := range returnedAlerts {
+				assert.Equal(t, *tc.expectedAlerts[i].Number, *alert.Number)
+				assert.Equal(t, *tc.expectedAlerts[i].HTMLURL, *alert.HTMLURL)
+				assert.Equal(t, *tc.expectedAlerts[i].State, *alert.State)
+				if tc.expectedAlerts[i].SecurityAdvisory != nil && tc.expectedAlerts[i].SecurityAdvisory.Severity != nil &&
+					alert.SecurityAdvisory != nil && alert.SecurityAdvisory.Severity != nil {
+					assert.Equal(t, *tc.expectedAlerts[i].SecurityAdvisory.Severity, *alert.SecurityAdvisory.Severity)
+				}
+			}
+		})
+	}
+}
diff --git a/pkg/github/tools.go b/pkg/github/tools.go
index 9f36cfc3d..a469b7678 100644
--- a/pkg/github/tools.go
+++ b/pkg/github/tools.go
@@ -103,6 +103,11 @@ func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetG
 			toolsets.NewServerTool(GetSecretScanningAlert(getClient, t)),
 			toolsets.NewServerTool(ListSecretScanningAlerts(getClient, t)),
 		)
+	dependabot := toolsets.NewToolset("dependabot", "Dependabot tools").
+		AddReadTools(
+			toolsets.NewServerTool(GetDependabotAlert(getClient, t)),
+			toolsets.NewServerTool(ListDependabotAlerts(getClient, t)),
+		)
 
 	notifications := toolsets.NewToolset("notifications", "GitHub Notifications related tools").
 		AddReadTools(
@@ -162,6 +167,7 @@ func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetG
 	tsg.AddToolset(actions)
 	tsg.AddToolset(codeSecurity)
 	tsg.AddToolset(secretProtection)
+	tsg.AddToolset(dependabot)
 	tsg.AddToolset(notifications)
 	tsg.AddToolset(experiments)
 	tsg.AddToolset(discussions)
@@ -188,3 +194,12 @@ func InitDynamicToolset(s *server.MCPServer, tsg *toolsets.ToolsetGroup, t trans
 func ToBoolPtr(b bool) *bool {
 	return &b
 }
+
+// ToStringPtr converts a string to a *string pointer.
+// Returns nil if the string is empty.
+func ToStringPtr(s string) *string {
+	if s == "" {
+		return nil
+	}
+	return &s
+}

From 08a49b0f81f0c26a0240044d5bfe2e10de5f18ce Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Thu, 3 Jul 2025 15:33:21 +0100
Subject: [PATCH 06/32] use WithPagination tool option (#632)

---
 README.md                                     | 20 +++---
 .../__toolsnaps__/get_issue_comments.snap     |  9 ++-
 pkg/github/actions.go                         | 68 +++++--------------
 pkg/github/actions_test.go                    |  4 +-
 pkg/github/issues.go                          | 17 ++---
 pkg/github/issues_test.go                     |  4 +-
 6 files changed, 40 insertions(+), 82 deletions(-)

diff --git a/README.md b/README.md
index 0bb054355..68742752f 100644
--- a/README.md
+++ b/README.md
@@ -478,15 +478,15 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 - **list_workflow_jobs** - List workflow jobs
   - `filter`: Filters jobs by their completed_at timestamp (string, optional)
   - `owner`: Repository owner (string, required)
-  - `page`: The page number of the results to fetch (number, optional)
-  - `per_page`: The number of results per page (max 100) (number, optional)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
   - `run_id`: The unique identifier of the workflow run (number, required)
 
 - **list_workflow_run_artifacts** - List workflow artifacts
   - `owner`: Repository owner (string, required)
-  - `page`: The page number of the results to fetch (number, optional)
-  - `per_page`: The number of results per page (max 100) (number, optional)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
   - `run_id`: The unique identifier of the workflow run (number, required)
 
@@ -495,16 +495,16 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `branch`: Returns workflow runs associated with a branch. Use the name of the branch. (string, optional)
   - `event`: Returns workflow runs for a specific event type (string, optional)
   - `owner`: Repository owner (string, required)
-  - `page`: The page number of the results to fetch (number, optional)
-  - `per_page`: The number of results per page (max 100) (number, optional)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
   - `status`: Returns workflow runs with the check run status (string, optional)
   - `workflow_id`: The workflow ID or workflow file name (string, required)
 
 - **list_workflows** - List workflows
   - `owner`: Repository owner (string, required)
-  - `page`: The page number of the results to fetch (number, optional)
-  - `per_page`: The number of results per page (max 100) (number, optional)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
 
 - **rerun_failed_jobs** - Rerun failed jobs
@@ -632,8 +632,8 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 - **get_issue_comments** - Get issue comments
   - `issue_number`: Issue number (number, required)
   - `owner`: Repository owner (string, required)
-  - `page`: Page number (number, optional)
-  - `per_page`: Number of records per page (number, optional)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
 
 - **list_issues** - List issues
diff --git a/pkg/github/__toolsnaps__/get_issue_comments.snap b/pkg/github/__toolsnaps__/get_issue_comments.snap
index fa1fb0d6c..b28f45204 100644
--- a/pkg/github/__toolsnaps__/get_issue_comments.snap
+++ b/pkg/github/__toolsnaps__/get_issue_comments.snap
@@ -15,11 +15,14 @@
         "type": "string"
       },
       "page": {
-        "description": "Page number",
+        "description": "Page number for pagination (min 1)",
+        "minimum": 1,
         "type": "number"
       },
-      "per_page": {
-        "description": "Number of records per page",
+      "perPage": {
+        "description": "Results per page for pagination (min 1, max 100)",
+        "maximum": 100,
+        "minimum": 1,
         "type": "number"
       },
       "repo": {
diff --git a/pkg/github/actions.go b/pkg/github/actions.go
index 8c7b08a85..95b1ec7ba 100644
--- a/pkg/github/actions.go
+++ b/pkg/github/actions.go
@@ -37,12 +37,7 @@ func ListWorkflows(getClient GetClientFn, t translations.TranslationHelperFunc)
 				mcp.Required(),
 				mcp.Description(DescriptionRepositoryName),
 			),
-			mcp.WithNumber("per_page",
-				mcp.Description("The number of results per page (max 100)"),
-			),
-			mcp.WithNumber("page",
-				mcp.Description("The page number of the results to fetch"),
-			),
+			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			owner, err := RequiredParam[string](request, "owner")
@@ -55,11 +50,7 @@ func ListWorkflows(getClient GetClientFn, t translations.TranslationHelperFunc)
 			}
 
 			// Get optional pagination parameters
-			perPage, err := OptionalIntParam(request, "per_page")
-			if err != nil {
-				return mcp.NewToolResultError(err.Error()), nil
-			}
-			page, err := OptionalIntParam(request, "page")
+			pagination, err := OptionalPaginationParams(request)
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
@@ -71,8 +62,8 @@ func ListWorkflows(getClient GetClientFn, t translations.TranslationHelperFunc)
 
 			// Set up list options
 			opts := &github.ListOptions{
-				PerPage: perPage,
-				Page:    page,
+				PerPage: pagination.perPage,
+				Page:    pagination.page,
 			}
 
 			workflows, resp, err := client.Actions.ListWorkflows(ctx, owner, repo, opts)
@@ -157,12 +148,7 @@ func ListWorkflowRuns(getClient GetClientFn, t translations.TranslationHelperFun
 				mcp.Description("Returns workflow runs with the check run status"),
 				mcp.Enum("queued", "in_progress", "completed", "requested", "waiting"),
 			),
-			mcp.WithNumber("per_page",
-				mcp.Description("The number of results per page (max 100)"),
-			),
-			mcp.WithNumber("page",
-				mcp.Description("The page number of the results to fetch"),
-			),
+			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			owner, err := RequiredParam[string](request, "owner")
@@ -197,11 +183,7 @@ func ListWorkflowRuns(getClient GetClientFn, t translations.TranslationHelperFun
 			}
 
 			// Get optional pagination parameters
-			perPage, err := OptionalIntParam(request, "per_page")
-			if err != nil {
-				return mcp.NewToolResultError(err.Error()), nil
-			}
-			page, err := OptionalIntParam(request, "page")
+			pagination, err := OptionalPaginationParams(request)
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
@@ -218,8 +200,8 @@ func ListWorkflowRuns(getClient GetClientFn, t translations.TranslationHelperFun
 				Event:  event,
 				Status: status,
 				ListOptions: github.ListOptions{
-					PerPage: perPage,
-					Page:    page,
+					PerPage: pagination.perPage,
+					Page:    pagination.page,
 				},
 			}
 
@@ -483,12 +465,7 @@ func ListWorkflowJobs(getClient GetClientFn, t translations.TranslationHelperFun
 				mcp.Description("Filters jobs by their completed_at timestamp"),
 				mcp.Enum("latest", "all"),
 			),
-			mcp.WithNumber("per_page",
-				mcp.Description("The number of results per page (max 100)"),
-			),
-			mcp.WithNumber("page",
-				mcp.Description("The page number of the results to fetch"),
-			),
+			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			owner, err := RequiredParam[string](request, "owner")
@@ -512,11 +489,7 @@ func ListWorkflowJobs(getClient GetClientFn, t translations.TranslationHelperFun
 			}
 
 			// Get optional pagination parameters
-			perPage, err := OptionalIntParam(request, "per_page")
-			if err != nil {
-				return mcp.NewToolResultError(err.Error()), nil
-			}
-			page, err := OptionalIntParam(request, "page")
+			pagination, err := OptionalPaginationParams(request)
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
@@ -530,8 +503,8 @@ func ListWorkflowJobs(getClient GetClientFn, t translations.TranslationHelperFun
 			opts := &github.ListWorkflowJobsOptions{
 				Filter: filter,
 				ListOptions: github.ListOptions{
-					PerPage: perPage,
-					Page:    page,
+					PerPage: pagination.perPage,
+					Page:    pagination.page,
 				},
 			}
 
@@ -1022,12 +995,7 @@ func ListWorkflowRunArtifacts(getClient GetClientFn, t translations.TranslationH
 				mcp.Required(),
 				mcp.Description("The unique identifier of the workflow run"),
 			),
-			mcp.WithNumber("per_page",
-				mcp.Description("The number of results per page (max 100)"),
-			),
-			mcp.WithNumber("page",
-				mcp.Description("The page number of the results to fetch"),
-			),
+			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			owner, err := RequiredParam[string](request, "owner")
@@ -1045,11 +1013,7 @@ func ListWorkflowRunArtifacts(getClient GetClientFn, t translations.TranslationH
 			runID := int64(runIDInt)
 
 			// Get optional pagination parameters
-			perPage, err := OptionalIntParam(request, "per_page")
-			if err != nil {
-				return mcp.NewToolResultError(err.Error()), nil
-			}
-			page, err := OptionalIntParam(request, "page")
+			pagination, err := OptionalPaginationParams(request)
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
@@ -1061,8 +1025,8 @@ func ListWorkflowRunArtifacts(getClient GetClientFn, t translations.TranslationH
 
 			// Set up list options
 			opts := &github.ListOptions{
-				PerPage: perPage,
-				Page:    page,
+				PerPage: pagination.perPage,
+				Page:    pagination.page,
 			}
 
 			artifacts, resp, err := client.Actions.ListWorkflowRunArtifacts(ctx, owner, repo, runID, opts)
diff --git a/pkg/github/actions_test.go b/pkg/github/actions_test.go
index 1b904b9b1..f885ec5b9 100644
--- a/pkg/github/actions_test.go
+++ b/pkg/github/actions_test.go
@@ -23,7 +23,7 @@ func Test_ListWorkflows(t *testing.T) {
 	assert.NotEmpty(t, tool.Description)
 	assert.Contains(t, tool.InputSchema.Properties, "owner")
 	assert.Contains(t, tool.InputSchema.Properties, "repo")
-	assert.Contains(t, tool.InputSchema.Properties, "per_page")
+	assert.Contains(t, tool.InputSchema.Properties, "perPage")
 	assert.Contains(t, tool.InputSchema.Properties, "page")
 	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"})
 
@@ -393,7 +393,7 @@ func Test_ListWorkflowRunArtifacts(t *testing.T) {
 	assert.Contains(t, tool.InputSchema.Properties, "owner")
 	assert.Contains(t, tool.InputSchema.Properties, "repo")
 	assert.Contains(t, tool.InputSchema.Properties, "run_id")
-	assert.Contains(t, tool.InputSchema.Properties, "per_page")
+	assert.Contains(t, tool.InputSchema.Properties, "perPage")
 	assert.Contains(t, tool.InputSchema.Properties, "page")
 	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "run_id"})
 
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
index 6121786d2..9d51aeb50 100644
--- a/pkg/github/issues.go
+++ b/pkg/github/issues.go
@@ -608,12 +608,7 @@ func GetIssueComments(getClient GetClientFn, t translations.TranslationHelperFun
 				mcp.Required(),
 				mcp.Description("Issue number"),
 			),
-			mcp.WithNumber("page",
-				mcp.Description("Page number"),
-			),
-			mcp.WithNumber("per_page",
-				mcp.Description("Number of records per page"),
-			),
+			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			owner, err := RequiredParam[string](request, "owner")
@@ -628,19 +623,15 @@ func GetIssueComments(getClient GetClientFn, t translations.TranslationHelperFun
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
-			page, err := OptionalIntParamWithDefault(request, "page", 1)
-			if err != nil {
-				return mcp.NewToolResultError(err.Error()), nil
-			}
-			perPage, err := OptionalIntParamWithDefault(request, "per_page", 30)
+			pagination, err := OptionalPaginationParams(request)
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 
 			opts := &github.IssueListCommentsOptions{
 				ListOptions: github.ListOptions{
-					Page:    page,
-					PerPage: perPage,
+					Page:    pagination.page,
+					PerPage: pagination.perPage,
 				},
 			}
 
diff --git a/pkg/github/issues_test.go b/pkg/github/issues_test.go
index 056fa7ed8..a6facbe2f 100644
--- a/pkg/github/issues_test.go
+++ b/pkg/github/issues_test.go
@@ -1087,7 +1087,7 @@ func Test_GetIssueComments(t *testing.T) {
 	assert.Contains(t, tool.InputSchema.Properties, "repo")
 	assert.Contains(t, tool.InputSchema.Properties, "issue_number")
 	assert.Contains(t, tool.InputSchema.Properties, "page")
-	assert.Contains(t, tool.InputSchema.Properties, "per_page")
+	assert.Contains(t, tool.InputSchema.Properties, "perPage")
 	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "issue_number"})
 
 	// Setup mock comments for success case
@@ -1152,7 +1152,7 @@ func Test_GetIssueComments(t *testing.T) {
 				"repo":         "repo",
 				"issue_number": float64(42),
 				"page":         float64(2),
-				"per_page":     float64(10),
+				"perPage":      float64(10),
 			},
 			expectError:      false,
 			expectedComments: mockComments,

From 6c0453a9c141a3491f9a3c5f26dbff3284d2d910 Mon Sep 17 00:00:00 2001
From: LuluBeatson <lulubeatson@github.com>
Date: Fri, 4 Jul 2025 10:32:43 +0100
Subject: [PATCH 07/32] omit site_admin from get_me output

---
 pkg/github/context_tools.go | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pkg/github/context_tools.go b/pkg/github/context_tools.go
index bed2f4a39..280420b91 100644
--- a/pkg/github/context_tools.go
+++ b/pkg/github/context_tools.go
@@ -38,6 +38,9 @@ func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Too
 			), nil
 		}
 
+		// Set nil to omit from output
+		user.SiteAdmin = nil
+
 		return MarshalledTextResult(user), nil
 	})
 

From 37d1ed6fd8e4937a2ea40d68c9a7684bb76a8a1b Mon Sep 17 00:00:00 2001
From: LuluBeatson <lulubeatson@github.com>
Date: Fri, 4 Jul 2025 12:05:05 +0100
Subject: [PATCH 08/32] return MinimalUser

---
 pkg/github/context_tools.go      | 15 ++++++++++++---
 pkg/github/context_tools_test.go | 12 ++++--------
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/pkg/github/context_tools.go b/pkg/github/context_tools.go
index 280420b91..43a5ce726 100644
--- a/pkg/github/context_tools.go
+++ b/pkg/github/context_tools.go
@@ -38,10 +38,19 @@ func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Too
 			), nil
 		}
 
-		// Set nil to omit from output
-		user.SiteAdmin = nil
+		// Create minimal user representation instead of returning full user object
+		minimalUser := MinimalUser{
+			Login: user.GetLogin(),
+			ID:    user.GetID(),
+		}
+		if user.HTMLURL != nil {
+			minimalUser.ProfileURL = *user.HTMLURL
+		}
+		if user.AvatarURL != nil {
+			minimalUser.AvatarURL = *user.AvatarURL
+		}
 
-		return MarshalledTextResult(user), nil
+		return MarshalledTextResult(minimalUser), nil
 	})
 
 	return tool, handler
diff --git a/pkg/github/context_tools_test.go b/pkg/github/context_tools_test.go
index 0d9193976..675e04dce 100644
--- a/pkg/github/context_tools_test.go
+++ b/pkg/github/context_tools_test.go
@@ -117,17 +117,13 @@ func Test_GetMe(t *testing.T) {
 			}
 
 			// Unmarshal and verify the result
-			var returnedUser github.User
+			var returnedUser MinimalUser
 			err = json.Unmarshal([]byte(textContent.Text), &returnedUser)
 			require.NoError(t, err)
 
-			// Verify user details
-			assert.Equal(t, *tc.expectedUser.Login, *returnedUser.Login)
-			assert.Equal(t, *tc.expectedUser.Name, *returnedUser.Name)
-			assert.Equal(t, *tc.expectedUser.Email, *returnedUser.Email)
-			assert.Equal(t, *tc.expectedUser.Bio, *returnedUser.Bio)
-			assert.Equal(t, *tc.expectedUser.HTMLURL, *returnedUser.HTMLURL)
-			assert.Equal(t, *tc.expectedUser.Type, *returnedUser.Type)
+			// Verify minimal user details
+			assert.Equal(t, *tc.expectedUser.Login, returnedUser.Login)
+			assert.Equal(t, *tc.expectedUser.HTMLURL, returnedUser.ProfileURL)
 		})
 	}
 }

From 1d057c975d3821d3d6cec17c01df56fdecb87fbc Mon Sep 17 00:00:00 2001
From: LuluBeatson <lulubeatson@github.com>
Date: Fri, 4 Jul 2025 12:29:29 +0100
Subject: [PATCH 09/32] refactor: user get methods to avoid nil checks

---
 pkg/github/context_tools.go | 12 ++++--------
 pkg/github/search.go        | 14 +++++---------
 2 files changed, 9 insertions(+), 17 deletions(-)

diff --git a/pkg/github/context_tools.go b/pkg/github/context_tools.go
index 43a5ce726..cf859f8bd 100644
--- a/pkg/github/context_tools.go
+++ b/pkg/github/context_tools.go
@@ -40,14 +40,10 @@ func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Too
 
 		// Create minimal user representation instead of returning full user object
 		minimalUser := MinimalUser{
-			Login: user.GetLogin(),
-			ID:    user.GetID(),
-		}
-		if user.HTMLURL != nil {
-			minimalUser.ProfileURL = *user.HTMLURL
-		}
-		if user.AvatarURL != nil {
-			minimalUser.AvatarURL = *user.AvatarURL
+			Login:      user.GetLogin(),
+			ID:         user.GetID(),
+			ProfileURL: user.GetHTMLURL(),
+			AvatarURL:  user.GetAvatarURL(),
 		}
 
 		return MarshalledTextResult(minimalUser), nil
diff --git a/pkg/github/search.go b/pkg/github/search.go
index 5106b84d8..82f920351 100644
--- a/pkg/github/search.go
+++ b/pkg/github/search.go
@@ -224,15 +224,11 @@ func userOrOrgHandler(accountType string, getClient GetClientFn) server.ToolHand
 
 		for _, user := range result.Users {
 			if user.Login != nil {
-				mu := MinimalUser{Login: *user.Login}
-				if user.ID != nil {
-					mu.ID = *user.ID
-				}
-				if user.HTMLURL != nil {
-					mu.ProfileURL = *user.HTMLURL
-				}
-				if user.AvatarURL != nil {
-					mu.AvatarURL = *user.AvatarURL
+				mu := MinimalUser{
+					Login:      user.GetLogin(),
+					ID:         user.GetID(),
+					ProfileURL: user.GetHTMLURL(),
+					AvatarURL:  user.GetAvatarURL(),
 				}
 				minimalUsers = append(minimalUsers, mu)
 			}

From e43fca195b1655d5c9fb63d1bca404098f3db7f4 Mon Sep 17 00:00:00 2001
From: LuluBeatson <lulubeatson@github.com>
Date: Fri, 4 Jul 2025 13:20:28 +0100
Subject: [PATCH 10/32] embed optional UserDetails in MinimalUser

---
 pkg/github/context_tools.go      | 42 ++++++++++++++++++++++++++++++++
 pkg/github/context_tools_test.go | 30 ++++++++++++++++-------
 pkg/github/search.go             | 10 +++++---
 3 files changed, 69 insertions(+), 13 deletions(-)

diff --git a/pkg/github/context_tools.go b/pkg/github/context_tools.go
index cf859f8bd..3525277fe 100644
--- a/pkg/github/context_tools.go
+++ b/pkg/github/context_tools.go
@@ -2,6 +2,7 @@ package github
 
 import (
 	"context"
+	"time"
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
@@ -9,6 +10,28 @@ import (
 	"github.com/mark3labs/mcp-go/server"
 )
 
+// UserDetails contains additional fields about a GitHub user not already
+// present in MinimalUser. Used by get_me context tool but omitted from search_users.
+type UserDetails struct {
+	Name              string    `json:"name,omitempty"`
+	Company           string    `json:"company,omitempty"`
+	Blog              string    `json:"blog,omitempty"`
+	Location          string    `json:"location,omitempty"`
+	Email             string    `json:"email,omitempty"`
+	Hireable          bool      `json:"hireable,omitempty"`
+	Bio               string    `json:"bio,omitempty"`
+	TwitterUsername   string    `json:"twitter_username,omitempty"`
+	PublicRepos       int       `json:"public_repos"`
+	PublicGists       int       `json:"public_gists"`
+	Followers         int       `json:"followers"`
+	Following         int       `json:"following"`
+	CreatedAt         time.Time `json:"created_at"`
+	UpdatedAt         time.Time `json:"updated_at"`
+	PrivateGists      int       `json:"private_gists,omitempty"`
+	TotalPrivateRepos int64     `json:"total_private_repos,omitempty"`
+	OwnedPrivateRepos int64     `json:"owned_private_repos,omitempty"`
+}
+
 // GetMe creates a tool to get details of the authenticated user.
 func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) {
 	tool := mcp.NewTool("get_me",
@@ -44,6 +67,25 @@ func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Too
 			ID:         user.GetID(),
 			ProfileURL: user.GetHTMLURL(),
 			AvatarURL:  user.GetAvatarURL(),
+			Details: &UserDetails{
+				Name:              user.GetName(),
+				Company:           user.GetCompany(),
+				Blog:              user.GetBlog(),
+				Location:          user.GetLocation(),
+				Email:             user.GetEmail(),
+				Hireable:          user.GetHireable(),
+				Bio:               user.GetBio(),
+				TwitterUsername:   user.GetTwitterUsername(),
+				PublicRepos:       user.GetPublicRepos(),
+				PublicGists:       user.GetPublicGists(),
+				Followers:         user.GetFollowers(),
+				Following:         user.GetFollowing(),
+				CreatedAt:         user.GetCreatedAt().Time,
+				UpdatedAt:         user.GetUpdatedAt().Time,
+				PrivateGists:      user.GetPrivateGists(),
+				TotalPrivateRepos: user.GetTotalPrivateRepos(),
+				OwnedPrivateRepos: user.GetOwnedPrivateRepos(),
+			},
 		}
 
 		return MarshalledTextResult(minimalUser), nil
diff --git a/pkg/github/context_tools_test.go b/pkg/github/context_tools_test.go
index 675e04dce..03af4175d 100644
--- a/pkg/github/context_tools_test.go
+++ b/pkg/github/context_tools_test.go
@@ -26,15 +26,17 @@ func Test_GetMe(t *testing.T) {
 
 	// Setup mock user response
 	mockUser := &github.User{
-		Login:     github.Ptr("testuser"),
-		Name:      github.Ptr("Test User"),
-		Email:     github.Ptr("test@example.com"),
-		Bio:       github.Ptr("GitHub user for testing"),
-		Company:   github.Ptr("Test Company"),
-		Location:  github.Ptr("Test Location"),
-		HTMLURL:   github.Ptr("https://github.com/testuser"),
-		CreatedAt: &github.Timestamp{Time: time.Now().Add(-365 * 24 * time.Hour)},
-		Type:      github.Ptr("User"),
+		Login:           github.Ptr("testuser"),
+		Name:            github.Ptr("Test User"),
+		Email:           github.Ptr("test@example.com"),
+		Bio:             github.Ptr("GitHub user for testing"),
+		Company:         github.Ptr("Test Company"),
+		Location:        github.Ptr("Test Location"),
+		HTMLURL:         github.Ptr("https://github.com/testuser"),
+		CreatedAt:       &github.Timestamp{Time: time.Now().Add(-365 * 24 * time.Hour)},
+		Type:            github.Ptr("User"),
+		Hireable:        github.Ptr(true),
+		TwitterUsername: github.Ptr("testuser_twitter"),
 		Plan: &github.Plan{
 			Name: github.Ptr("pro"),
 		},
@@ -124,6 +126,16 @@ func Test_GetMe(t *testing.T) {
 			// Verify minimal user details
 			assert.Equal(t, *tc.expectedUser.Login, returnedUser.Login)
 			assert.Equal(t, *tc.expectedUser.HTMLURL, returnedUser.ProfileURL)
+
+			// Verify user details
+			require.NotNil(t, returnedUser.Details)
+			assert.Equal(t, *tc.expectedUser.Name, returnedUser.Details.Name)
+			assert.Equal(t, *tc.expectedUser.Email, returnedUser.Details.Email)
+			assert.Equal(t, *tc.expectedUser.Bio, returnedUser.Details.Bio)
+			assert.Equal(t, *tc.expectedUser.Company, returnedUser.Details.Company)
+			assert.Equal(t, *tc.expectedUser.Location, returnedUser.Details.Location)
+			assert.Equal(t, *tc.expectedUser.Hireable, returnedUser.Details.Hireable)
+			assert.Equal(t, *tc.expectedUser.TwitterUsername, returnedUser.Details.TwitterUsername)
 		})
 	}
 }
diff --git a/pkg/github/search.go b/pkg/github/search.go
index 82f920351..a72b38bc6 100644
--- a/pkg/github/search.go
+++ b/pkg/github/search.go
@@ -155,11 +155,13 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to
 		}
 }
 
+// MinimalUser is the output type for user and organization search results.
 type MinimalUser struct {
-	Login      string `json:"login"`
-	ID         int64  `json:"id,omitempty"`
-	ProfileURL string `json:"profile_url,omitempty"`
-	AvatarURL  string `json:"avatar_url,omitempty"`
+	Login      string       `json:"login"`
+	ID         int64        `json:"id,omitempty"`
+	ProfileURL string       `json:"profile_url,omitempty"`
+	AvatarURL  string       `json:"avatar_url,omitempty"`
+	Details    *UserDetails `json:"details,omitempty"` // Optional field for additional user details
 }
 
 type MinimalSearchUsersResult struct {

From ea7304769f9d48c1e603cac589dfebbc2c641ef4 Mon Sep 17 00:00:00 2001
From: Sam Morrow <info@sam-morrow.com>
Date: Fri, 4 Jul 2025 16:49:44 +0200
Subject: [PATCH 11/32] fix: stale information in CONTRIBUTING.md

---
 CONTRIBUTING.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6fa9c2ebe..314e4e0b2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,14 +19,12 @@ These are one time installations required to be able to test your changes locall
 
 ## Submitting a pull request
 
-> **Important**: Please open your pull request against the `next` branch, not `main`. The `next` branch is where we integrate new features and changes before they are merged to `main`.
-
 1. [Fork][fork] and clone the repository
 1. Make sure the tests pass on your machine: `go test -v ./...`
 1. Make sure linter passes on your machine: `golangci-lint run`
 1. Create a new branch: `git checkout -b my-branch-name`
 1. Make your change, add tests, and make sure the tests and linter still pass
-1. Push to your fork and [submit a pull request][pr] targeting the `next` branch
+1. Push to your fork and [submit a pull request][pr] targeting the `main` branch
 1. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:

From fc117136812d9ff5e24407206d0b983828363c3e Mon Sep 17 00:00:00 2001
From: John Wesley Walker III <81404201+jww3@users.noreply.github.com>
Date: Mon, 7 Jul 2025 11:23:09 +0200
Subject: [PATCH 12/32] Updated links to MCP Specification in
 `docs/host-integration.md` (#641)

---
 docs/host-integration.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/host-integration.md b/docs/host-integration.md
index d9f6d9050..9a1d9396f 100644
--- a/docs/host-integration.md
+++ b/docs/host-integration.md
@@ -64,7 +64,7 @@ flowchart LR
   - **Local MCP Server**: An MCP Server running locally, side-by-side with the Application.
   - **Remote MCP Server**: An MCP Server running remotely, accessed via the internet.  Most Remote MCP Servers require authentication via OAuth.
 
-For more detail, see the [official MCP specification](https://modelcontextprotocol.io/specification/draft).
+For more detail, see the [official MCP specification](https://modelcontextprotocol.io/specification/2025-06-18).
 
 > [!NOTE]
 > GitHub offers both a Local MCP Server and a Remote MCP Server.
@@ -84,7 +84,7 @@ For the Remote GitHub MCP Server, the recommended way to obtain a valid access t
 > The Remote GitHub MCP Server itself does not provide Authentication services.
 > Your client application must obtain valid GitHub access tokens through one of the supported methods.
 
-The expected flow for obtaining a valid access token via OAuth is depicted in the [MCP Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization#authorization-flow-steps).  For convenience, we've embedded a copy of the authorization flow below.  Please study it carefully as the remainder of this document is written with this flow in mind.
+The expected flow for obtaining a valid access token via OAuth is depicted in the [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-flow-steps).  For convenience, we've embedded a copy of the authorization flow below.  Please study it carefully as the remainder of this document is written with this flow in mind.
 
 ```mermaid
 sequenceDiagram

From 39d7fec500a623320176613e24c4bcceeac90213 Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Mon, 7 Jul 2025 12:59:49 +0100
Subject: [PATCH 13/32] Update `list_commits` Filtering Descriptions (#634)

* update sha arg description for list_commits, get_file_contents

* update perPage description for pagination to inform of default 30

* toolsnaps, docs

* revert perPage description
---
 README.md                                       | 6 +++---
 pkg/github/__toolsnaps__/get_file_contents.snap | 2 +-
 pkg/github/__toolsnaps__/list_commits.snap      | 4 ++--
 pkg/github/repositories.go                      | 6 +++---
 pkg/github/server.go                            | 4 +++-
 5 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 68742752f..b281ad042 100644
--- a/README.md
+++ b/README.md
@@ -902,7 +902,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `path`: Path to file/directory (directories must end with a slash '/') (string, required)
   - `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional)
   - `repo`: Repository name (string, required)
-  - `sha`: Accepts optional git sha, if sha is specified it will be used instead of ref (string, optional)
+  - `sha`: Accepts optional commit SHA. If specified, it will be used instead of ref (string, optional)
 
 - **get_tag** - Get tag details
   - `owner`: Repository owner (string, required)
@@ -916,12 +916,12 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `repo`: Repository name (string, required)
 
 - **list_commits** - List commits
-  - `author`: Author username or email address (string, optional)
+  - `author`: Author username or email address to filter commits by (string, optional)
   - `owner`: Repository owner (string, required)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
-  - `sha`: The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch. (string, optional)
+  - `sha`: Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA. (string, optional)
 
 - **list_tags** - List tags
   - `owner`: Repository owner (string, required)
diff --git a/pkg/github/__toolsnaps__/get_file_contents.snap b/pkg/github/__toolsnaps__/get_file_contents.snap
index b3975abbc..e550e8db8 100644
--- a/pkg/github/__toolsnaps__/get_file_contents.snap
+++ b/pkg/github/__toolsnaps__/get_file_contents.snap
@@ -23,7 +23,7 @@
         "type": "string"
       },
       "sha": {
-        "description": "Accepts optional git sha, if sha is specified it will be used instead of ref",
+        "description": "Accepts optional commit SHA. If specified, it will be used instead of ref",
         "type": "string"
       }
     },
diff --git a/pkg/github/__toolsnaps__/list_commits.snap b/pkg/github/__toolsnaps__/list_commits.snap
index c43f7b0cd..a802436c2 100644
--- a/pkg/github/__toolsnaps__/list_commits.snap
+++ b/pkg/github/__toolsnaps__/list_commits.snap
@@ -7,7 +7,7 @@
   "inputSchema": {
     "properties": {
       "author": {
-        "description": "Author username or email address",
+        "description": "Author username or email address to filter commits by",
         "type": "string"
       },
       "owner": {
@@ -30,7 +30,7 @@
         "type": "string"
       },
       "sha": {
-        "description": "The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch.",
+        "description": "Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA.",
         "type": "string"
       }
     },
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index 29f776a05..cf71a5839 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -111,10 +111,10 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 				mcp.Description("Repository name"),
 			),
 			mcp.WithString("sha",
-				mcp.Description("The commit SHA, branch name, or tag name to list commits from. If not specified, defaults to the repository's default branch."),
+				mcp.Description("Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA."),
 			),
 			mcp.WithString("author",
-				mcp.Description("Author username or email address"),
+				mcp.Description("Author username or email address to filter commits by"),
 			),
 			WithPagination(),
 		),
@@ -470,7 +470,7 @@ func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t t
 				mcp.Description("Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`"),
 			),
 			mcp.WithString("sha",
-				mcp.Description("Accepts optional git sha, if sha is specified it will be used instead of ref"),
+				mcp.Description("Accepts optional commit SHA. If specified, it will be used instead of ref"),
 			),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
diff --git a/pkg/github/server.go b/pkg/github/server.go
index 85d078f1b..e7b831791 100644
--- a/pkg/github/server.go
+++ b/pkg/github/server.go
@@ -175,7 +175,9 @@ func OptionalStringArrayParam(r mcp.CallToolRequest, p string) ([]string, error)
 }
 
 // WithPagination returns a ToolOption that adds "page" and "perPage" parameters to the tool.
-// The "page" parameter is optional, min 1. The "perPage" parameter is optional, min 1, max 100.
+// The "page" parameter is optional, min 1.
+// The "perPage" parameter is optional, min 1, max 100. If unset, defaults to 30.
+// https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
 func WithPagination() mcp.ToolOption {
 	return func(tool *mcp.Tool) {
 		mcp.WithNumber("page",

From 3730b840fea960643d3e3ee2e506619a0bf7ab62 Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Mon, 7 Jul 2025 14:43:05 +0100
Subject: [PATCH 14/32] fix: get_discussion graphQL invalid field (#648)

* rm State which does not exist on type Discussion

* update Test_GetDiscussion

* use Discussion object instead of Issue
---
 pkg/github/discussions.go      | 32 ++++++++++++--------------------
 pkg/github/discussions_test.go | 28 ++++++++++------------------
 2 files changed, 22 insertions(+), 38 deletions(-)

diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go
index a7ec8e20f..3e53a633b 100644
--- a/pkg/github/discussions.go
+++ b/pkg/github/discussions.go
@@ -62,7 +62,7 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 			}
 
 			// Now execute the discussions query
-			var discussions []*github.Issue
+			var discussions []*github.Discussion
 			if categoryID != nil {
 				// Query with category filter (server-side filtering)
 				var query struct {
@@ -89,17 +89,15 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 					return mcp.NewToolResultError(err.Error()), nil
 				}
 
-				// Map nodes to GitHub Issue objects
+				// Map nodes to GitHub Discussion objects
 				for _, n := range query.Repository.Discussions.Nodes {
-					di := &github.Issue{
+					di := &github.Discussion{
 						Number:    github.Ptr(int(n.Number)),
 						Title:     github.Ptr(string(n.Title)),
 						HTMLURL:   github.Ptr(string(n.URL)),
 						CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time},
-						Labels: []*github.Label{
-							{
-								Name: github.Ptr(fmt.Sprintf("category:%s", string(n.Category.Name))),
-							},
+						DiscussionCategory: &github.DiscussionCategory{
+							Name: github.Ptr(string(n.Category.Name)),
 						},
 					}
 					discussions = append(discussions, di)
@@ -129,17 +127,15 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 					return mcp.NewToolResultError(err.Error()), nil
 				}
 
-				// Map nodes to GitHub Issue objects
+				// Map nodes to GitHub Discussion objects
 				for _, n := range query.Repository.Discussions.Nodes {
-					di := &github.Issue{
+					di := &github.Discussion{
 						Number:    github.Ptr(int(n.Number)),
 						Title:     github.Ptr(string(n.Title)),
 						HTMLURL:   github.Ptr(string(n.URL)),
 						CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time},
-						Labels: []*github.Label{
-							{
-								Name: github.Ptr(fmt.Sprintf("category:%s", string(n.Category.Name))),
-							},
+						DiscussionCategory: &github.DiscussionCategory{
+							Name: github.Ptr(string(n.Category.Name)),
 						},
 					}
 					discussions = append(discussions, di)
@@ -195,7 +191,6 @@ func GetDiscussion(getGQLClient GetGQLClientFn, t translations.TranslationHelper
 					Discussion struct {
 						Number    githubv4.Int
 						Body      githubv4.String
-						State     githubv4.String
 						CreatedAt githubv4.DateTime
 						URL       githubv4.String `graphql:"url"`
 						Category  struct {
@@ -213,16 +208,13 @@ func GetDiscussion(getGQLClient GetGQLClientFn, t translations.TranslationHelper
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 			d := q.Repository.Discussion
-			discussion := &github.Issue{
+			discussion := &github.Discussion{
 				Number:    github.Ptr(int(d.Number)),
 				Body:      github.Ptr(string(d.Body)),
-				State:     github.Ptr(string(d.State)),
 				HTMLURL:   github.Ptr(string(d.URL)),
 				CreatedAt: &github.Timestamp{Time: d.CreatedAt.Time},
-				Labels: []*github.Label{
-					{
-						Name: github.Ptr(fmt.Sprintf("category:%s", string(d.Category.Name))),
-					},
+				DiscussionCategory: &github.DiscussionCategory{
+					Name: github.Ptr(string(d.Category.Name)),
 				},
 			}
 			out, err := json.Marshal(discussion)
diff --git a/pkg/github/discussions_test.go b/pkg/github/discussions_test.go
index 545d604f9..5132c6ce0 100644
--- a/pkg/github/discussions_test.go
+++ b/pkg/github/discussions_test.go
@@ -4,7 +4,6 @@ import (
 	"context"
 	"encoding/json"
 	"net/http"
-	"strings"
 	"testing"
 	"time"
 
@@ -168,17 +167,17 @@ func Test_ListDiscussions(t *testing.T) {
 			}
 			require.NoError(t, err)
 
-			var returnedDiscussions []*github.Issue
+			var returnedDiscussions []*github.Discussion
 			err = json.Unmarshal([]byte(text), &returnedDiscussions)
 			require.NoError(t, err)
 
 			assert.Len(t, returnedDiscussions, tc.expectedCount, "Expected %d discussions, got %d", tc.expectedCount, len(returnedDiscussions))
 
-			// Verify that all returned discussions have a category label if filtered
+			// Verify that all returned discussions have a category if filtered
 			if _, hasCategory := tc.reqParams["category"]; hasCategory {
 				for _, discussion := range returnedDiscussions {
-					require.NotEmpty(t, discussion.Labels, "Discussion should have category label")
-					assert.True(t, strings.HasPrefix(*discussion.Labels[0].Name, "category:"), "Discussion should have category label prefix")
+					require.NotNil(t, discussion.DiscussionCategory, "Discussion should have category")
+					assert.NotEmpty(t, *discussion.DiscussionCategory.Name, "Discussion should have category name")
 				}
 			}
 		})
@@ -200,7 +199,6 @@ func Test_GetDiscussion(t *testing.T) {
 			Discussion struct {
 				Number    githubv4.Int
 				Body      githubv4.String
-				State     githubv4.String
 				CreatedAt githubv4.DateTime
 				URL       githubv4.String `graphql:"url"`
 				Category  struct {
@@ -218,7 +216,7 @@ func Test_GetDiscussion(t *testing.T) {
 		name        string
 		response    githubv4mock.GQLResponse
 		expectError bool
-		expected    *github.Issue
+		expected    *github.Discussion
 		errContains string
 	}{
 		{
@@ -227,23 +225,19 @@ func Test_GetDiscussion(t *testing.T) {
 				"repository": map[string]any{"discussion": map[string]any{
 					"number":    1,
 					"body":      "This is a test discussion",
-					"state":     "open",
 					"url":       "https://github.com/owner/repo/discussions/1",
 					"createdAt": "2025-04-25T12:00:00Z",
 					"category":  map[string]any{"name": "General"},
 				}},
 			}),
 			expectError: false,
-			expected: &github.Issue{
+			expected: &github.Discussion{
 				HTMLURL:   github.Ptr("https://github.com/owner/repo/discussions/1"),
 				Number:    github.Ptr(1),
 				Body:      github.Ptr("This is a test discussion"),
-				State:     github.Ptr("open"),
 				CreatedAt: &github.Timestamp{Time: time.Date(2025, 4, 25, 12, 0, 0, 0, time.UTC)},
-				Labels: []*github.Label{
-					{
-						Name: github.Ptr("category:General"),
-					},
+				DiscussionCategory: &github.DiscussionCategory{
+					Name: github.Ptr("General"),
 				},
 			},
 		},
@@ -272,15 +266,13 @@ func Test_GetDiscussion(t *testing.T) {
 			}
 
 			require.NoError(t, err)
-			var out github.Issue
+			var out github.Discussion
 			require.NoError(t, json.Unmarshal([]byte(text), &out))
 			assert.Equal(t, *tc.expected.HTMLURL, *out.HTMLURL)
 			assert.Equal(t, *tc.expected.Number, *out.Number)
 			assert.Equal(t, *tc.expected.Body, *out.Body)
-			assert.Equal(t, *tc.expected.State, *out.State)
 			// Check category label
-			require.Len(t, out.Labels, 1)
-			assert.Equal(t, *tc.expected.Labels[0].Name, *out.Labels[0].Name)
+			assert.Equal(t, *tc.expected.DiscussionCategory.Name, *out.DiscussionCategory.Name)
 		})
 	}
 }

From 0cf70ebdb5486293095848844620cc01e4f2bedf Mon Sep 17 00:00:00 2001
From: Tony Truong <tonytrg@github.com>
Date: Mon, 7 Jul 2025 18:07:48 +0200
Subject: [PATCH 15/32] Remove redundant param for get_me and update
 contribution guide (#649)

* remove reason param for get_me

* updating toolsnap

* update contributing

* updating tool get_me

* add small changes

* update snapshots
---
 CONTRIBUTING.md                      | 19 +++++++++++--------
 README.md                            |  2 +-
 pkg/github/__toolsnaps__/get_me.snap |  9 ++-------
 pkg/github/context_tools.go          |  5 +----
 4 files changed, 15 insertions(+), 20 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 314e4e0b2..b4012f0b2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,18 +14,21 @@ Please note that this project is released with a [Contributor Code of Conduct](C
 
 These are one time installations required to be able to test your changes locally as part of the pull request (PR) submission process.
 
-1. install Go [through download](https://go.dev/doc/install) | [through Homebrew](https://formulae.brew.sh/formula/go)
-1. [install golangci-lint v2](https://golangci-lint.run/welcome/install/#local-installation)
+1. Install Go [through download](https://go.dev/doc/install) | [through Homebrew](https://formulae.brew.sh/formula/go)
+2. [Install golangci-lint v2](https://golangci-lint.run/welcome/install/#local-installation)
 
 ## Submitting a pull request
 
 1. [Fork][fork] and clone the repository
-1. Make sure the tests pass on your machine: `go test -v ./...`
-1. Make sure linter passes on your machine: `golangci-lint run`
-1. Create a new branch: `git checkout -b my-branch-name`
-1. Make your change, add tests, and make sure the tests and linter still pass
-1. Push to your fork and [submit a pull request][pr] targeting the `main` branch
-1. Pat yourself on the back and wait for your pull request to be reviewed and merged.
+2. Make sure the tests pass on your machine: `go test -v ./...`
+3. Make sure linter passes on your machine: `golangci-lint run`
+4. Create a new branch: `git checkout -b my-branch-name`
+5. Add your changes and tests, and make sure the Action workflows still pass
+    - Run linter: `script/lint`
+    - Update snapshots and run tests: `UPDATE_TOOLSNAPS=true go test ./...`
+    - Update readme documentation: `script/generate-docs`
+6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
+7. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 
diff --git a/README.md b/README.md
index b281ad042..8ba842a46 100644
--- a/README.md
+++ b/README.md
@@ -550,7 +550,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 <summary>Context</summary>
 
 - **get_me** - Get my user profile
-  - `reason`: Optional: the reason for requesting the user information (string, optional)
+  - No parameters required
 
 </details>
 
diff --git a/pkg/github/__toolsnaps__/get_me.snap b/pkg/github/__toolsnaps__/get_me.snap
index fc098f9d1..13b061741 100644
--- a/pkg/github/__toolsnaps__/get_me.snap
+++ b/pkg/github/__toolsnaps__/get_me.snap
@@ -3,14 +3,9 @@
     "title": "Get my user profile",
     "readOnlyHint": true
   },
-  "description": "Get details of the authenticated GitHub user. Use this when a request includes \"me\", \"my\". The output will not change unless the user changes their profile, so only call this once.",
+  "description": "Get details of the authenticated GitHub user. Use this when a request is about the user's own profile for GitHub. Or when information is missing to build other tool calls.",
   "inputSchema": {
-    "properties": {
-      "reason": {
-        "description": "Optional: the reason for requesting the user information",
-        "type": "string"
-      }
-    },
+    "properties": {},
     "type": "object"
   },
   "name": "get_me"
diff --git a/pkg/github/context_tools.go b/pkg/github/context_tools.go
index 3525277fe..9817fea7b 100644
--- a/pkg/github/context_tools.go
+++ b/pkg/github/context_tools.go
@@ -35,14 +35,11 @@ type UserDetails struct {
 // GetMe creates a tool to get details of the authenticated user.
 func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) {
 	tool := mcp.NewTool("get_me",
-		mcp.WithDescription(t("TOOL_GET_ME_DESCRIPTION", "Get details of the authenticated GitHub user. Use this when a request includes \"me\", \"my\". The output will not change unless the user changes their profile, so only call this once.")),
+		mcp.WithDescription(t("TOOL_GET_ME_DESCRIPTION", "Get details of the authenticated GitHub user. Use this when a request is about the user's own profile for GitHub. Or when information is missing to build other tool calls.")),
 		mcp.WithToolAnnotation(mcp.ToolAnnotation{
 			Title:        t("TOOL_GET_ME_USER_TITLE", "Get my user profile"),
 			ReadOnlyHint: ToBoolPtr(true),
 		}),
-		mcp.WithString("reason",
-			mcp.Description("Optional: the reason for requesting the user information"),
-		),
 	)
 
 	type args struct{}

From 3341e6bc461b461f0789518879f97bbd86ef7ee9 Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Tue, 8 Jul 2025 17:51:24 +0100
Subject: [PATCH 16/32] Update `create_or_update_file` SHA Arg Description
 (#651)

* sha arg prompt as required if updating file

* generate docs and toolsnaps

* shorten
---
 README.md                                           | 2 +-
 pkg/github/__toolsnaps__/create_or_update_file.snap | 2 +-
 pkg/github/repositories.go                          | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 8ba842a46..70e8c3ca1 100644
--- a/README.md
+++ b/README.md
@@ -870,7 +870,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
   - `owner`: Repository owner (username or organization) (string, required)
   - `path`: Path where to create/update the file (string, required)
   - `repo`: Repository name (string, required)
-  - `sha`: SHA of file being replaced (for updates) (string, optional)
+  - `sha`: Required if updating an existing file. The blob SHA of the file being replaced. (string, optional)
 
 - **create_repository** - Create repository
   - `autoInit`: Initialize with README (boolean, optional)
diff --git a/pkg/github/__toolsnaps__/create_or_update_file.snap b/pkg/github/__toolsnaps__/create_or_update_file.snap
index dfbb34423..61adef72c 100644
--- a/pkg/github/__toolsnaps__/create_or_update_file.snap
+++ b/pkg/github/__toolsnaps__/create_or_update_file.snap
@@ -31,7 +31,7 @@
         "type": "string"
       },
       "sha": {
-        "description": "SHA of file being replaced (for updates)",
+        "description": "Required if updating an existing file. The blob SHA of the file being replaced.",
         "type": "string"
       }
     },
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index cf71a5839..8a7a8af4a 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -288,7 +288,7 @@ func CreateOrUpdateFile(getClient GetClientFn, t translations.TranslationHelperF
 				mcp.Description("Branch to create/update the file in"),
 			),
 			mcp.WithString("sha",
-				mcp.Description("SHA of file being replaced (for updates)"),
+				mcp.Description("Required if updating an existing file. The blob SHA of the file being replaced."),
 			),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {

From 89bb9286ca5b758df8b95fccf90e94efbf9d25da Mon Sep 17 00:00:00 2001
From: Nhu Do <nhu-do@github.com>
Date: Wed, 9 Jul 2025 15:04:48 -0400
Subject: [PATCH 17/32] Include Copilot coding agent tool on the remote GitHub
 MCP server (#656)

* Update README.md

* Update remote-server.md
---
 README.md             | 15 +++++++++++++++
 docs/remote-server.md | 10 ++++++++++
 2 files changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 70e8c3ca1..8cff2e138 100644
--- a/README.md
+++ b/README.md
@@ -982,6 +982,21 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 </details>
 <!-- END AUTOMATED TOOLS -->
 
+### Additional Tools in Remote Github MCP Server
+
+<details>
+
+<summary>Copilot coding agent</summary>
+
+-   **create_pull_request_with_copilot** - Perform task with GitHub Copilot coding agent
+    -   `owner`: Repository owner. You can guess the owner, but confirm it with the user before proceeding. (string, required)
+    -   `repo`: Repository name. You can guess the repository name, but confirm it with the user before proceeding. (string, required)
+    -   `problem_statement`: Detailed description of the task to be performed (e.g., 'Implement a feature that does X', 'Fix bug Y', etc.) (string, required)
+    -   `title`: Title for the pull request that will be created (string, required)
+    -   `base_ref`: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)
+
+</details>
+
 ## Library Usage
 
 The exported Go API of this module should currently be considered unstable, and subject to breaking changes. In the future, we may offer stability; please file an issue if there is a use case where this would be valuable.
diff --git a/docs/remote-server.md b/docs/remote-server.md
index c36124ecc..49794c605 100644
--- a/docs/remote-server.md
+++ b/docs/remote-server.md
@@ -10,6 +10,8 @@ Easily connect to the GitHub MCP Server using the hosted version – no local se
 
 The remote GitHub MCP server is built using this repository as a library, and binding it into GitHub server infrastructure with an internal repository. You can open issues and propose changes in this repository, and we regularly update the remote server to include the latest version of this code.
 
+The remote server has [additional tools](#toolsets-only-available-in-the-remote-mcp-server) that are not available in the local MCP server, such as the `create_pull_request_with_copilot` tool for invoking Copilot coding agent.
+
 ## Remote MCP Toolsets
 
 Below is a table of available toolsets for the remote GitHub MCP Server. Each toolset is provided as a distinct URL so you can mix and match to create the perfect combination of tools for your use-case. Add `/readonly` to the end of any URL to restrict the tools in the toolset to only those that enable read access. We also provide the option to use [headers](#headers) instead.
@@ -33,6 +35,14 @@ Below is a table of available toolsets for the remote GitHub MCP Server. Each to
 
 <!-- END AUTOMATED TOOLSETS -->
 
+### Additional _Remote_ Server Toolsets
+
+These toolsets are only available in the remote GitHub MCP Server and are not included in the local MCP server.
+
+| Name                 | Description                                   | API URL                                     | 1-Click Install (VS Code)                                                                                                                                                                          | Read-only Link                                                    | 1-Click Read-only Install (VS Code)                                                                                                                                                                                     |
+| -------------------- | --------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Copilot coding agent | Perform task with GitHub Copilot coding agent | https://api.githubcopilot.com/mcp/x/copilot | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-copilot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcopilot%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/copilot/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-copilot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcopilot%2Freadonly%22%7D) |
+
 ### Headers
 
 You can configure toolsets and readonly mode by providing HTTP headers in your server configuration.

From 42e5ce9b88ee289bb8d7a297c1d8a580e06c9e86 Mon Sep 17 00:00:00 2001
From: Tommaso Moro <37270480+tommaso-moro@users.noreply.github.com>
Date: Fri, 11 Jul 2025 09:21:45 +0100
Subject: [PATCH 18/32] Tommy/(Bug-fix): adjust tool description to account for
 author in prompt (#658)

* adjust tool description

* removed dead code

* improve desription

* update description for tests
---
 pkg/github/__toolsnaps__/list_pull_requests.snap | 2 +-
 pkg/github/pullrequests.go                       | 3 +--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/pkg/github/__toolsnaps__/list_pull_requests.snap b/pkg/github/__toolsnaps__/list_pull_requests.snap
index b8369784d..fee7e2ff1 100644
--- a/pkg/github/__toolsnaps__/list_pull_requests.snap
+++ b/pkg/github/__toolsnaps__/list_pull_requests.snap
@@ -3,7 +3,7 @@
     "title": "List pull requests",
     "readOnlyHint": true
   },
-  "description": "List pull requests in a GitHub repository.",
+  "description": "List pull requests in a GitHub repository. If the user specifies an author, then DO NOT use this tool and use the search_pull_requests tool instead.",
   "inputSchema": {
     "properties": {
       "base": {
diff --git a/pkg/github/pullrequests.go b/pkg/github/pullrequests.go
index bad822b13..32c7e850c 100644
--- a/pkg/github/pullrequests.go
+++ b/pkg/github/pullrequests.go
@@ -330,7 +330,7 @@ func UpdatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu
 // ListPullRequests creates a tool to list and filter repository pull requests.
 func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) {
 	return mcp.NewTool("list_pull_requests",
-			mcp.WithDescription(t("TOOL_LIST_PULL_REQUESTS_DESCRIPTION", "List pull requests in a GitHub repository.")),
+			mcp.WithDescription(t("TOOL_LIST_PULL_REQUESTS_DESCRIPTION", "List pull requests in a GitHub repository. If the user specifies an author, then DO NOT use this tool and use the search_pull_requests tool instead.")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
 				Title:        t("TOOL_LIST_PULL_REQUESTS_USER_TITLE", "List pull requests"),
 				ReadOnlyHint: ToBoolPtr(true),
@@ -396,7 +396,6 @@ func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFun
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
-
 			opts := &github.PullRequestListOptions{
 				State:     state,
 				Head:      head,

From c23b1f9f6e629febc4a6c1ad50da0f991d9ec0fe Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Fri, 11 Jul 2025 16:23:55 +0100
Subject: [PATCH 19/32] `get_file_content` Match Paths in Git Tree if Full Path
 Unknown (#650)

* add contingency to match path in git tree

* resolveGitReference helper

* fix: handling of directories

* Test_filterPaths

* filterPaths - trailing slashes

* fix: close response body, improve error messages, docs

* update tool result message about resolved git ref

* unit test cases for filterPaths maxResults param

* resolveGitReference - NewGitHubAPIErrorToCtx
---
 pkg/github/repositories.go      | 158 ++++++++++++++++++-------
 pkg/github/repositories_test.go | 204 +++++++++++++++++++++++++++++++-
 2 files changed, 317 insertions(+), 45 deletions(-)

diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index 8a7a8af4a..732f20ab1 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -8,7 +8,6 @@ import (
 	"io"
 	"net/http"
 	"net/url"
-	"strconv"
 	"strings"
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
@@ -495,33 +494,18 @@ func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t t
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 
-			rawOpts := &raw.ContentOpts{}
-
-			if strings.HasPrefix(ref, "refs/pull/") {
-				prNumber := strings.TrimSuffix(strings.TrimPrefix(ref, "refs/pull/"), "/head")
-				if len(prNumber) > 0 {
-					// fetch the PR from the API to get the latest commit and use SHA
-					githubClient, err := getClient(ctx)
-					if err != nil {
-						return nil, fmt.Errorf("failed to get GitHub client: %w", err)
-					}
-					prNum, err := strconv.Atoi(prNumber)
-					if err != nil {
-						return nil, fmt.Errorf("invalid pull request number: %w", err)
-					}
-					pr, _, err := githubClient.PullRequests.Get(ctx, owner, repo, prNum)
-					if err != nil {
-						return nil, fmt.Errorf("failed to get pull request: %w", err)
-					}
-					sha = pr.GetHead().GetSHA()
-					ref = ""
-				}
+			client, err := getClient(ctx)
+			if err != nil {
+				return mcp.NewToolResultError("failed to get GitHub client"), nil
 			}
 
-			rawOpts.SHA = sha
-			rawOpts.Ref = ref
+			rawOpts, err := resolveGitReference(ctx, client, owner, repo, ref, sha)
+			if err != nil {
+				return mcp.NewToolResultError(fmt.Sprintf("failed to resolve git reference: %s", err)), nil
+			}
 
-			// If the path is (most likely) not to be a directory, we will first try to get the raw content from the GitHub raw content API.
+			// If the path is (most likely) not to be a directory, we will
+			// first try to get the raw content from the GitHub raw content API.
 			if path != "" && !strings.HasSuffix(path, "/") {
 
 				rawClient, err := getRawClient(ctx)
@@ -580,36 +564,51 @@ func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t t
 				}
 			}
 
-			client, err := getClient(ctx)
-			if err != nil {
-				return mcp.NewToolResultError("failed to get GitHub client"), nil
-			}
-
-			if sha != "" {
-				ref = sha
+			if rawOpts.SHA != "" {
+				ref = rawOpts.SHA
 			}
 			if strings.HasSuffix(path, "/") {
 				opts := &github.RepositoryContentGetOptions{Ref: ref}
 				_, dirContent, resp, err := client.Repositories.GetContents(ctx, owner, repo, path, opts)
-				if err != nil {
-					return mcp.NewToolResultError("failed to get file contents"), nil
-				}
-				defer func() { _ = resp.Body.Close() }()
-
-				if resp.StatusCode != 200 {
-					body, err := io.ReadAll(resp.Body)
+				if err == nil && resp.StatusCode == http.StatusOK {
+					defer func() { _ = resp.Body.Close() }()
+					r, err := json.Marshal(dirContent)
 					if err != nil {
-						return mcp.NewToolResultError("failed to read response body"), nil
+						return mcp.NewToolResultError("failed to marshal response"), nil
 					}
-					return mcp.NewToolResultError(fmt.Sprintf("failed to get file contents: %s", string(body))), nil
+					return mcp.NewToolResultText(string(r)), nil
 				}
+			}
+
+			// The path does not point to a file or directory.
+			// Instead let's try to find it in the Git Tree by matching the end of the path.
+
+			// Step 1: Get Git Tree recursively
+			tree, resp, err := client.Git.GetTree(ctx, owner, repo, ref, true)
+			if err != nil {
+				return ghErrors.NewGitHubAPIErrorResponse(ctx,
+					"failed to get git tree",
+					resp,
+					err,
+				), nil
+			}
+			defer func() { _ = resp.Body.Close() }()
 
-				r, err := json.Marshal(dirContent)
+			// Step 2: Filter tree for matching paths
+			const maxMatchingFiles = 3
+			matchingFiles := filterPaths(tree.Entries, path, maxMatchingFiles)
+			if len(matchingFiles) > 0 {
+				matchingFilesJSON, err := json.Marshal(matchingFiles)
+				if err != nil {
+					return mcp.NewToolResultError(fmt.Sprintf("failed to marshal matching files: %s", err)), nil
+				}
+				resolvedRefs, err := json.Marshal(rawOpts)
 				if err != nil {
-					return mcp.NewToolResultError("failed to marshal response"), nil
+					return mcp.NewToolResultError(fmt.Sprintf("failed to marshal resolved refs: %s", err)), nil
 				}
-				return mcp.NewToolResultText(string(r)), nil
+				return mcp.NewToolResultText(fmt.Sprintf("Path did not point to a file or directory, but resolved git ref to %s with possible path matches: %s", resolvedRefs, matchingFilesJSON)), nil
 			}
+
 			return mcp.NewToolResultError("Failed to get file contents. The path does not point to a file or directory, or the file does not exist in the repository."), nil
 		}
 }
@@ -1293,3 +1292,74 @@ func GetTag(getClient GetClientFn, t translations.TranslationHelperFunc) (tool m
 			return mcp.NewToolResultText(string(r)), nil
 		}
 }
+
+// filterPaths filters the entries in a GitHub tree to find paths that
+// match the given suffix.
+// maxResults limits the number of results returned to first maxResults entries,
+// a maxResults of -1 means no limit.
+// It returns a slice of strings containing the matching paths.
+// Directories are returned with a trailing slash.
+func filterPaths(entries []*github.TreeEntry, path string, maxResults int) []string {
+	// Remove trailing slash for matching purposes, but flag whether we
+	// only want directories.
+	dirOnly := false
+	if strings.HasSuffix(path, "/") {
+		dirOnly = true
+		path = strings.TrimSuffix(path, "/")
+	}
+
+	matchedPaths := []string{}
+	for _, entry := range entries {
+		if len(matchedPaths) == maxResults {
+			break // Limit the number of results to maxResults
+		}
+		if dirOnly && entry.GetType() != "tree" {
+			continue // Skip non-directory entries if dirOnly is true
+		}
+		entryPath := entry.GetPath()
+		if entryPath == "" {
+			continue // Skip empty paths
+		}
+		if strings.HasSuffix(entryPath, path) {
+			if entry.GetType() == "tree" {
+				entryPath += "/" // Return directories with a trailing slash
+			}
+			matchedPaths = append(matchedPaths, entryPath)
+		}
+	}
+	return matchedPaths
+}
+
+// resolveGitReference resolves git references with the following logic:
+// 1. If SHA is provided, it takes precedence
+// 2. If neither is provided, use the default branch as ref
+// 3. Get commit SHA from the ref
+// Refs can look like `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`
+// The function returns the resolved ref, commit SHA and any error.
+func resolveGitReference(ctx context.Context, githubClient *github.Client, owner, repo, ref, sha string) (*raw.ContentOpts, error) {
+	// 1. If SHA is provided, use it directly
+	if sha != "" {
+		return &raw.ContentOpts{Ref: "", SHA: sha}, nil
+	}
+
+	// 2. If neither provided, use the default branch as ref
+	if ref == "" {
+		repoInfo, resp, err := githubClient.Repositories.Get(ctx, owner, repo)
+		if err != nil {
+			_, _ = ghErrors.NewGitHubAPIErrorToCtx(ctx, "failed to get repository info", resp, err)
+			return nil, fmt.Errorf("failed to get repository info: %w", err)
+		}
+		ref = fmt.Sprintf("refs/heads/%s", repoInfo.GetDefaultBranch())
+	}
+
+	// 3. Get the SHA from the ref
+	reference, resp, err := githubClient.Git.GetRef(ctx, owner, repo, ref)
+	if err != nil {
+		_, _ = ghErrors.NewGitHubAPIErrorToCtx(ctx, "failed to get reference", resp, err)
+		return nil, fmt.Errorf("failed to get reference: %w", err)
+	}
+	sha = reference.GetObject().GetSHA()
+
+	// Use provided ref, or it will be empty which defaults to the default branch
+	return &raw.ContentOpts{Ref: ref, SHA: sha}, nil
+}
diff --git a/pkg/github/repositories_test.go b/pkg/github/repositories_test.go
index b621cec43..0b9c5d9f9 100644
--- a/pkg/github/repositories_test.go
+++ b/pkg/github/repositories_test.go
@@ -69,6 +69,13 @@ func Test_GetFileContents(t *testing.T) {
 		{
 			name: "successful text content fetch",
 			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposGitRefByOwnerByRepoByRef,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						_, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`))
+					}),
+				),
 				mock.WithRequestMatchHandler(
 					raw.GetRawReposContentsByOwnerByRepoByBranchByPath,
 					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
@@ -93,6 +100,13 @@ func Test_GetFileContents(t *testing.T) {
 		{
 			name: "successful file blob content fetch",
 			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposGitRefByOwnerByRepoByRef,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						_, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`))
+					}),
+				),
 				mock.WithRequestMatchHandler(
 					raw.GetRawReposContentsByOwnerByRepoByBranchByPath,
 					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
@@ -117,6 +131,20 @@ func Test_GetFileContents(t *testing.T) {
 		{
 			name: "successful directory content fetch",
 			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposByOwnerByRepo,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						_, _ = w.Write([]byte(`{"name": "repo", "default_branch": "main"}`))
+					}),
+				),
+				mock.WithRequestMatchHandler(
+					mock.GetReposGitRefByOwnerByRepoByRef,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						_, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`))
+					}),
+				),
 				mock.WithRequestMatchHandler(
 					mock.GetReposContentsByOwnerByRepoByPath,
 					expectQueryParams(t, map[string]string{}).andThen(
@@ -143,6 +171,13 @@ func Test_GetFileContents(t *testing.T) {
 		{
 			name: "content fetch fails",
 			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposGitRefByOwnerByRepoByRef,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						_, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`))
+					}),
+				),
 				mock.WithRequestMatchHandler(
 					mock.GetReposContentsByOwnerByRepoByPath,
 					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
@@ -203,7 +238,7 @@ func Test_GetFileContents(t *testing.T) {
 				textContent := getTextResult(t, result)
 				var returnedContents []*github.RepositoryContent
 				err = json.Unmarshal([]byte(textContent.Text), &returnedContents)
-				require.NoError(t, err)
+				require.NoError(t, err, "Failed to unmarshal directory content result: %v", textContent.Text)
 				assert.Len(t, returnedContents, len(expected))
 				for i, content := range returnedContents {
 					assert.Equal(t, *expected[i].Name, *content.Name)
@@ -2049,3 +2084,170 @@ func Test_GetTag(t *testing.T) {
 		})
 	}
 }
+
+func Test_filterPaths(t *testing.T) {
+	tests := []struct {
+		name       string
+		tree       []*github.TreeEntry
+		path       string
+		maxResults int
+		expected   []string
+	}{
+		{
+			name: "file name",
+			tree: []*github.TreeEntry{
+				{Path: github.Ptr("folder/foo.txt"), Type: github.Ptr("blob")},
+				{Path: github.Ptr("bar.txt"), Type: github.Ptr("blob")},
+				{Path: github.Ptr("nested/folder/foo.txt"), Type: github.Ptr("blob")},
+				{Path: github.Ptr("nested/folder/baz.txt"), Type: github.Ptr("blob")},
+			},
+			path:       "foo.txt",
+			maxResults: -1,
+			expected:   []string{"folder/foo.txt", "nested/folder/foo.txt"},
+		},
+		{
+			name: "dir name",
+			tree: []*github.TreeEntry{
+				{Path: github.Ptr("folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("bar.txt"), Type: github.Ptr("blob")},
+				{Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("nested/folder/baz.txt"), Type: github.Ptr("blob")},
+			},
+			path:       "folder/",
+			maxResults: -1,
+			expected:   []string{"folder/", "nested/folder/"},
+		},
+		{
+			name: "dir and file match",
+			tree: []*github.TreeEntry{
+				{Path: github.Ptr("name"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("name"), Type: github.Ptr("blob")},
+			},
+			path:       "name", // No trailing slash can match both files and directories
+			maxResults: -1,
+			expected:   []string{"name/", "name"},
+		},
+		{
+			name: "dir only match",
+			tree: []*github.TreeEntry{
+				{Path: github.Ptr("name"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("name"), Type: github.Ptr("blob")},
+			},
+			path:       "name/", // Trialing slash ensures only directories are matched
+			maxResults: -1,
+			expected:   []string{"name/"},
+		},
+		{
+			name: "max results limit 2",
+			tree: []*github.TreeEntry{
+				{Path: github.Ptr("folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("nested/nested/folder"), Type: github.Ptr("tree")},
+			},
+			path:       "folder/",
+			maxResults: 2,
+			expected:   []string{"folder/", "nested/folder/"},
+		},
+		{
+			name: "max results limit 1",
+			tree: []*github.TreeEntry{
+				{Path: github.Ptr("folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("nested/nested/folder"), Type: github.Ptr("tree")},
+			},
+			path:       "folder/",
+			maxResults: 1,
+			expected:   []string{"folder/"},
+		},
+		{
+			name: "max results limit 0",
+			tree: []*github.TreeEntry{
+				{Path: github.Ptr("folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")},
+				{Path: github.Ptr("nested/nested/folder"), Type: github.Ptr("tree")},
+			},
+			path:       "folder/",
+			maxResults: 0,
+			expected:   []string{},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := filterPaths(tc.tree, tc.path, tc.maxResults)
+			assert.Equal(t, tc.expected, result)
+		})
+	}
+}
+
+func Test_resolveGitReference(t *testing.T) {
+	ctx := context.Background()
+	owner := "owner"
+	repo := "repo"
+	mockedClient := mock.NewMockedHTTPClient(
+		mock.WithRequestMatchHandler(
+			mock.GetReposByOwnerByRepo,
+			http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte(`{"name": "repo", "default_branch": "main"}`))
+			}),
+		),
+		mock.WithRequestMatchHandler(
+			mock.GetReposGitRefByOwnerByRepoByRef,
+			http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": "123sha456"}}`))
+			}),
+		),
+	)
+
+	tests := []struct {
+		name           string
+		ref            string
+		sha            string
+		expectedOutput *raw.ContentOpts
+	}{
+		{
+			name: "sha takes precedence over ref",
+			ref:  "refs/heads/main",
+			sha:  "123sha456",
+			expectedOutput: &raw.ContentOpts{
+				SHA: "123sha456",
+			},
+		},
+		{
+			name: "use default branch if ref and sha both empty",
+			ref:  "",
+			sha:  "",
+			expectedOutput: &raw.ContentOpts{
+				Ref: "refs/heads/main",
+				SHA: "123sha456",
+			},
+		},
+		{
+			name: "get SHA from ref",
+			ref:  "refs/heads/main",
+			sha:  "",
+			expectedOutput: &raw.ContentOpts{
+				Ref: "refs/heads/main",
+				SHA: "123sha456",
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Setup client with mock
+			client := github.NewClient(mockedClient)
+			opts, err := resolveGitReference(ctx, client, owner, repo, tc.ref, tc.sha)
+			require.NoError(t, err)
+
+			if tc.expectedOutput.SHA != "" {
+				assert.Equal(t, tc.expectedOutput.SHA, opts.SHA)
+			}
+			if tc.expectedOutput.Ref != "" {
+				assert.Equal(t, tc.expectedOutput.Ref, opts.Ref)
+			}
+		})
+	}
+}

From d15026b0eb2a2e5d3265a2601798ab28017dc719 Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Fri, 11 Jul 2025 18:07:28 +0100
Subject: [PATCH 20/32] fix: get_file_contents use "/" for root (#666)

* update path description to use "/" for root

* update docs and toolsnaps

* use mcp.DefaultString, revert description, update unit test
---
 README.md                                       | 2 +-
 pkg/github/__toolsnaps__/get_file_contents.snap | 4 ++--
 pkg/github/repositories.go                      | 2 +-
 pkg/github/repositories_test.go                 | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 8cff2e138..c5274ff83 100644
--- a/README.md
+++ b/README.md
@@ -899,7 +899,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 
 - **get_file_contents** - Get file or directory contents
   - `owner`: Repository owner (username or organization) (string, required)
-  - `path`: Path to file/directory (directories must end with a slash '/') (string, required)
+  - `path`: Path to file/directory (directories must end with a slash '/') (string, optional)
   - `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional)
   - `repo`: Repository name (string, required)
   - `sha`: Accepts optional commit SHA. If specified, it will be used instead of ref (string, optional)
diff --git a/pkg/github/__toolsnaps__/get_file_contents.snap b/pkg/github/__toolsnaps__/get_file_contents.snap
index e550e8db8..53f5a29e5 100644
--- a/pkg/github/__toolsnaps__/get_file_contents.snap
+++ b/pkg/github/__toolsnaps__/get_file_contents.snap
@@ -11,6 +11,7 @@
         "type": "string"
       },
       "path": {
+        "default": "/",
         "description": "Path to file/directory (directories must end with a slash '/')",
         "type": "string"
       },
@@ -29,8 +30,7 @@
     },
     "required": [
       "owner",
-      "repo",
-      "path"
+      "repo"
     ],
     "type": "object"
   },
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index 732f20ab1..186bd2321 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -462,8 +462,8 @@ func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t t
 				mcp.Description("Repository name"),
 			),
 			mcp.WithString("path",
-				mcp.Required(),
 				mcp.Description("Path to file/directory (directories must end with a slash '/')"),
+				mcp.DefaultString("/"),
 			),
 			mcp.WithString("ref",
 				mcp.Description("Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`"),
diff --git a/pkg/github/repositories_test.go b/pkg/github/repositories_test.go
index 0b9c5d9f9..4977bb0a9 100644
--- a/pkg/github/repositories_test.go
+++ b/pkg/github/repositories_test.go
@@ -33,7 +33,7 @@ func Test_GetFileContents(t *testing.T) {
 	assert.Contains(t, tool.InputSchema.Properties, "path")
 	assert.Contains(t, tool.InputSchema.Properties, "ref")
 	assert.Contains(t, tool.InputSchema.Properties, "sha")
-	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "path"})
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"})
 
 	// Mock response for raw content
 	mockRawContent := []byte("# Test Repository\n\nThis is a test repository.")

From be91795fd34faaff4dcb76179a7cccd9998a005a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20H=C3=B8st=20Normark?= <m@martinnormark.com>
Date: Tue, 15 Jul 2025 16:21:24 +0200
Subject: [PATCH 21/32] Bump go-github to v73.0.0 (#597)

* Bump go-github to v73.0.0

* Clean up go.mod and update licenses

* Updated remaining imports to use github package v73 instead of v72

---------

Co-authored-by: Tommaso Moro <37270480+tommaso-moro@users.noreply.github.com>
Co-authored-by: tommaso-moro <tommaso-moro@github.com>
---
 cmd/github-mcp-server/generate_docs.go                        | 2 +-
 e2e/e2e_test.go                                               | 2 +-
 go.mod                                                        | 2 +-
 go.sum                                                        | 4 ++--
 internal/ghmcp/server.go                                      | 2 +-
 pkg/errors/error.go                                           | 2 +-
 pkg/errors/error_test.go                                      | 2 +-
 pkg/github/actions.go                                         | 2 +-
 pkg/github/actions_test.go                                    | 2 +-
 pkg/github/code_scanning.go                                   | 2 +-
 pkg/github/code_scanning_test.go                              | 2 +-
 pkg/github/context_tools_test.go                              | 2 +-
 pkg/github/dependabot.go                                      | 2 +-
 pkg/github/dependabot_test.go                                 | 2 +-
 pkg/github/discussions.go                                     | 2 +-
 pkg/github/discussions_test.go                                | 2 +-
 pkg/github/issues.go                                          | 2 +-
 pkg/github/issues_test.go                                     | 2 +-
 pkg/github/notifications.go                                   | 2 +-
 pkg/github/notifications_test.go                              | 2 +-
 pkg/github/pullrequests.go                                    | 2 +-
 pkg/github/pullrequests_test.go                               | 2 +-
 pkg/github/repositories.go                                    | 2 +-
 pkg/github/repositories_test.go                               | 2 +-
 pkg/github/repository_resource.go                             | 2 +-
 pkg/github/repository_resource_test.go                        | 2 +-
 pkg/github/search.go                                          | 2 +-
 pkg/github/search_test.go                                     | 2 +-
 pkg/github/search_utils.go                                    | 2 +-
 pkg/github/secret_scanning.go                                 | 2 +-
 pkg/github/secret_scanning_test.go                            | 2 +-
 pkg/github/server.go                                          | 2 +-
 pkg/github/server_test.go                                     | 2 +-
 pkg/github/tools.go                                           | 2 +-
 pkg/raw/raw.go                                                | 2 +-
 pkg/raw/raw_test.go                                           | 2 +-
 third-party-licenses.darwin.md                                | 2 +-
 third-party-licenses.linux.md                                 | 2 +-
 third-party-licenses.windows.md                               | 2 +-
 .../github.com/google/go-github/{v72 => v73}/github/LICENSE   | 0
 40 files changed, 40 insertions(+), 40 deletions(-)
 rename third-party/github.com/google/go-github/{v72 => v73}/github/LICENSE (100%)

diff --git a/cmd/github-mcp-server/generate_docs.go b/cmd/github-mcp-server/generate_docs.go
index dfd66d288..983ed4398 100644
--- a/cmd/github-mcp-server/generate_docs.go
+++ b/cmd/github-mcp-server/generate_docs.go
@@ -13,7 +13,7 @@ import (
 	"github.com/github/github-mcp-server/pkg/raw"
 	"github.com/github/github-mcp-server/pkg/toolsets"
 	"github.com/github/github-mcp-server/pkg/translations"
-	gogithub "github.com/google/go-github/v72/github"
+	gogithub "github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/shurcooL/githubv4"
 	"github.com/spf13/cobra"
diff --git a/e2e/e2e_test.go b/e2e/e2e_test.go
index bc5a3fde3..d46e8de8b 100644
--- a/e2e/e2e_test.go
+++ b/e2e/e2e_test.go
@@ -18,7 +18,7 @@ import (
 	"github.com/github/github-mcp-server/internal/ghmcp"
 	"github.com/github/github-mcp-server/pkg/github"
 	"github.com/github/github-mcp-server/pkg/translations"
-	gogithub "github.com/google/go-github/v72/github"
+	gogithub "github.com/google/go-github/v73/github"
 	mcpClient "github.com/mark3labs/mcp-go/client"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/stretchr/testify/require"
diff --git a/go.mod b/go.mod
index 4cc7682fd..3df6bf3d5 100644
--- a/go.mod
+++ b/go.mod
@@ -3,7 +3,7 @@ module github.com/github/github-mcp-server
 go 1.23.7
 
 require (
-	github.com/google/go-github/v72 v72.0.0
+	github.com/google/go-github/v73 v73.0.0
 	github.com/josephburnett/jd v1.9.2
 	github.com/mark3labs/mcp-go v0.32.0
 	github.com/migueleliasweb/go-github-mock v1.3.0
diff --git a/go.sum b/go.sum
index 5e601d909..d77cdf0d9 100644
--- a/go.sum
+++ b/go.sum
@@ -20,8 +20,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-github/v71 v71.0.0 h1:Zi16OymGKZZMm8ZliffVVJ/Q9YZreDKONCr+WUd0Z30=
 github.com/google/go-github/v71 v71.0.0/go.mod h1:URZXObp2BLlMjwu0O8g4y6VBneUj2bCHgnI8FfgZ51M=
-github.com/google/go-github/v72 v72.0.0 h1:FcIO37BLoVPBO9igQQ6tStsv2asG4IPcYFi655PPvBM=
-github.com/google/go-github/v72 v72.0.0/go.mod h1:WWtw8GMRiL62mvIquf1kO3onRHeWWKmK01qdCY8c5fg=
+github.com/google/go-github/v73 v73.0.0 h1:aR+Utnh+Y4mMkS+2qLQwcQ/cF9mOTpdwnzlaw//rG24=
+github.com/google/go-github/v73 v73.0.0/go.mod h1:fa6w8+/V+edSU0muqdhCVY7Beh1M8F1IlQPZIANKIYw=
 github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8=
 github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
diff --git a/internal/ghmcp/server.go b/internal/ghmcp/server.go
index 568af10d1..d993b130a 100644
--- a/internal/ghmcp/server.go
+++ b/internal/ghmcp/server.go
@@ -17,7 +17,7 @@ import (
 	mcplog "github.com/github/github-mcp-server/pkg/log"
 	"github.com/github/github-mcp-server/pkg/raw"
 	"github.com/github/github-mcp-server/pkg/translations"
-	gogithub "github.com/google/go-github/v72/github"
+	gogithub "github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 	"github.com/shurcooL/githubv4"
diff --git a/pkg/errors/error.go b/pkg/errors/error.go
index 9d81e9010..c89ab2d79 100644
--- a/pkg/errors/error.go
+++ b/pkg/errors/error.go
@@ -4,7 +4,7 @@ import (
 	"context"
 	"fmt"
 
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 )
 
diff --git a/pkg/errors/error_test.go b/pkg/errors/error_test.go
index e7a5b6ea1..3498e3d8a 100644
--- a/pkg/errors/error_test.go
+++ b/pkg/errors/error_test.go
@@ -6,7 +6,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
diff --git a/pkg/github/actions.go b/pkg/github/actions.go
index 95b1ec7ba..3c441d5aa 100644
--- a/pkg/github/actions.go
+++ b/pkg/github/actions.go
@@ -11,7 +11,7 @@ import (
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/actions_test.go b/pkg/github/actions_test.go
index f885ec5b9..cb33cbe6b 100644
--- a/pkg/github/actions_test.go
+++ b/pkg/github/actions_test.go
@@ -8,7 +8,7 @@ import (
 	"testing"
 
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/code_scanning.go b/pkg/github/code_scanning.go
index 3b07692c0..6b15c0c45 100644
--- a/pkg/github/code_scanning.go
+++ b/pkg/github/code_scanning.go
@@ -9,7 +9,7 @@ import (
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/code_scanning_test.go b/pkg/github/code_scanning_test.go
index bd76ccbae..66f6fd6cc 100644
--- a/pkg/github/code_scanning_test.go
+++ b/pkg/github/code_scanning_test.go
@@ -8,7 +8,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/context_tools_test.go b/pkg/github/context_tools_test.go
index 03af4175d..56f61e936 100644
--- a/pkg/github/context_tools_test.go
+++ b/pkg/github/context_tools_test.go
@@ -8,7 +8,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/dependabot.go b/pkg/github/dependabot.go
index af21b83d1..c2a4d5b0d 100644
--- a/pkg/github/dependabot.go
+++ b/pkg/github/dependabot.go
@@ -9,7 +9,7 @@ import (
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/dependabot_test.go b/pkg/github/dependabot_test.go
index f7c091981..8a7270d7f 100644
--- a/pkg/github/dependabot_test.go
+++ b/pkg/github/dependabot_test.go
@@ -8,7 +8,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go
index 3e53a633b..23e2724d4 100644
--- a/pkg/github/discussions.go
+++ b/pkg/github/discussions.go
@@ -7,7 +7,7 @@ import (
 
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/go-viper/mapstructure/v2"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 	"github.com/shurcooL/githubv4"
diff --git a/pkg/github/discussions_test.go b/pkg/github/discussions_test.go
index 5132c6ce0..c6688a519 100644
--- a/pkg/github/discussions_test.go
+++ b/pkg/github/discussions_test.go
@@ -9,7 +9,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/githubv4mock"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/shurcooL/githubv4"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
index 9d51aeb50..29d32bd18 100644
--- a/pkg/github/issues.go
+++ b/pkg/github/issues.go
@@ -11,7 +11,7 @@ import (
 
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/go-viper/mapstructure/v2"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 	"github.com/shurcooL/githubv4"
diff --git a/pkg/github/issues_test.go b/pkg/github/issues_test.go
index a6facbe2f..146259477 100644
--- a/pkg/github/issues_test.go
+++ b/pkg/github/issues_test.go
@@ -11,7 +11,7 @@ import (
 	"github.com/github/github-mcp-server/internal/githubv4mock"
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/shurcooL/githubv4"
 	"github.com/stretchr/testify/assert"
diff --git a/pkg/github/notifications.go b/pkg/github/notifications.go
index b6b6bfd79..a41edaf42 100644
--- a/pkg/github/notifications.go
+++ b/pkg/github/notifications.go
@@ -11,7 +11,7 @@ import (
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/notifications_test.go b/pkg/github/notifications_test.go
index a83df3ed8..1d2382369 100644
--- a/pkg/github/notifications_test.go
+++ b/pkg/github/notifications_test.go
@@ -8,7 +8,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/pullrequests.go b/pkg/github/pullrequests.go
index 32c7e850c..aeca650fa 100644
--- a/pkg/github/pullrequests.go
+++ b/pkg/github/pullrequests.go
@@ -8,7 +8,7 @@ import (
 	"net/http"
 
 	"github.com/go-viper/mapstructure/v2"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 	"github.com/shurcooL/githubv4"
diff --git a/pkg/github/pullrequests_test.go b/pkg/github/pullrequests_test.go
index 30341e86c..e39315232 100644
--- a/pkg/github/pullrequests_test.go
+++ b/pkg/github/pullrequests_test.go
@@ -10,7 +10,7 @@ import (
 	"github.com/github/github-mcp-server/internal/githubv4mock"
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/shurcooL/githubv4"
 
 	"github.com/migueleliasweb/go-github-mock/src/mock"
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index 186bd2321..58e4a7421 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -13,7 +13,7 @@ import (
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/raw"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/repositories_test.go b/pkg/github/repositories_test.go
index 4977bb0a9..0633e2123 100644
--- a/pkg/github/repositories_test.go
+++ b/pkg/github/repositories_test.go
@@ -12,7 +12,7 @@ import (
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/raw"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
diff --git a/pkg/github/repository_resource.go b/pkg/github/repository_resource.go
index a454db630..70ca6ba65 100644
--- a/pkg/github/repository_resource.go
+++ b/pkg/github/repository_resource.go
@@ -14,7 +14,7 @@ import (
 
 	"github.com/github/github-mcp-server/pkg/raw"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/repository_resource_test.go b/pkg/github/repository_resource_test.go
index 0e9f018e7..2e3e911a9 100644
--- a/pkg/github/repository_resource_test.go
+++ b/pkg/github/repository_resource_test.go
@@ -8,7 +8,7 @@ import (
 
 	"github.com/github/github-mcp-server/pkg/raw"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/search.go b/pkg/github/search.go
index a72b38bc6..04a1facc0 100644
--- a/pkg/github/search.go
+++ b/pkg/github/search.go
@@ -8,7 +8,7 @@ import (
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/search_test.go b/pkg/github/search_test.go
index bfd014993..21f7a0ca2 100644
--- a/pkg/github/search_test.go
+++ b/pkg/github/search_test.go
@@ -8,7 +8,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/toolsnaps"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/search_utils.go b/pkg/github/search_utils.go
index 6642dad8f..5dd48040e 100644
--- a/pkg/github/search_utils.go
+++ b/pkg/github/search_utils.go
@@ -7,7 +7,7 @@ import (
 	"io"
 	"net/http"
 
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 )
 
diff --git a/pkg/github/secret_scanning.go b/pkg/github/secret_scanning.go
index bea6df2ae..dc199b4e6 100644
--- a/pkg/github/secret_scanning.go
+++ b/pkg/github/secret_scanning.go
@@ -9,7 +9,7 @@ import (
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/secret_scanning_test.go b/pkg/github/secret_scanning_test.go
index 38b573e09..96b281830 100644
--- a/pkg/github/secret_scanning_test.go
+++ b/pkg/github/secret_scanning_test.go
@@ -7,7 +7,7 @@ import (
 	"testing"
 
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
diff --git a/pkg/github/server.go b/pkg/github/server.go
index e7b831791..ea476e3ac 100644
--- a/pkg/github/server.go
+++ b/pkg/github/server.go
@@ -5,7 +5,7 @@ import (
 	"errors"
 	"fmt"
 
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
diff --git a/pkg/github/server_test.go b/pkg/github/server_test.go
index 3f00d7b24..6353f254d 100644
--- a/pkg/github/server_test.go
+++ b/pkg/github/server_test.go
@@ -9,7 +9,7 @@ import (
 	"testing"
 
 	"github.com/github/github-mcp-server/pkg/raw"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/shurcooL/githubv4"
 	"github.com/stretchr/testify/assert"
 )
diff --git a/pkg/github/tools.go b/pkg/github/tools.go
index a469b7678..77a1ccd3b 100644
--- a/pkg/github/tools.go
+++ b/pkg/github/tools.go
@@ -6,7 +6,7 @@ import (
 	"github.com/github/github-mcp-server/pkg/raw"
 	"github.com/github/github-mcp-server/pkg/toolsets"
 	"github.com/github/github-mcp-server/pkg/translations"
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/mark3labs/mcp-go/server"
 	"github.com/shurcooL/githubv4"
 )
diff --git a/pkg/raw/raw.go b/pkg/raw/raw.go
index 17995ccae..af669c905 100644
--- a/pkg/raw/raw.go
+++ b/pkg/raw/raw.go
@@ -6,7 +6,7 @@ import (
 	"net/http"
 	"net/url"
 
-	gogithub "github.com/google/go-github/v72/github"
+	gogithub "github.com/google/go-github/v73/github"
 )
 
 // GetRawClientFn is a function type that returns a RawClient instance.
diff --git a/pkg/raw/raw_test.go b/pkg/raw/raw_test.go
index f02033159..18a48130d 100644
--- a/pkg/raw/raw_test.go
+++ b/pkg/raw/raw_test.go
@@ -6,7 +6,7 @@ import (
 	"net/url"
 	"testing"
 
-	"github.com/google/go-github/v72/github"
+	"github.com/google/go-github/v73/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/require"
 )
diff --git a/third-party-licenses.darwin.md b/third-party-licenses.darwin.md
index e616fa560..6a9f895cb 100644
--- a/third-party-licenses.darwin.md
+++ b/third-party-licenses.darwin.md
@@ -13,7 +13,7 @@ Some packages may only be included on certain architectures or operating systems
  - [github.com/go-openapi/swag](https://pkg.go.dev/github.com/go-openapi/swag) ([Apache-2.0](https://github.com/go-openapi/swag/blob/v0.21.1/LICENSE))
  - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.3.0/LICENSE))
  - [github.com/google/go-github/v71/github](https://pkg.go.dev/github.com/google/go-github/v71/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v71.0.0/LICENSE))
- - [github.com/google/go-github/v72/github](https://pkg.go.dev/github.com/google/go-github/v72/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v72.0.0/LICENSE))
+ - [github.com/google/go-github/v73/github](https://pkg.go.dev/github.com/google/go-github/v73/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v73.0.0/LICENSE))
  - [github.com/google/go-querystring/query](https://pkg.go.dev/github.com/google/go-querystring/query) ([BSD-3-Clause](https://github.com/google/go-querystring/blob/v1.1.0/LICENSE))
  - [github.com/google/uuid](https://pkg.go.dev/github.com/google/uuid) ([BSD-3-Clause](https://github.com/google/uuid/blob/v1.6.0/LICENSE))
  - [github.com/gorilla/mux](https://pkg.go.dev/github.com/gorilla/mux) ([BSD-3-Clause](https://github.com/gorilla/mux/blob/v1.8.0/LICENSE))
diff --git a/third-party-licenses.linux.md b/third-party-licenses.linux.md
index e616fa560..6a9f895cb 100644
--- a/third-party-licenses.linux.md
+++ b/third-party-licenses.linux.md
@@ -13,7 +13,7 @@ Some packages may only be included on certain architectures or operating systems
  - [github.com/go-openapi/swag](https://pkg.go.dev/github.com/go-openapi/swag) ([Apache-2.0](https://github.com/go-openapi/swag/blob/v0.21.1/LICENSE))
  - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.3.0/LICENSE))
  - [github.com/google/go-github/v71/github](https://pkg.go.dev/github.com/google/go-github/v71/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v71.0.0/LICENSE))
- - [github.com/google/go-github/v72/github](https://pkg.go.dev/github.com/google/go-github/v72/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v72.0.0/LICENSE))
+ - [github.com/google/go-github/v73/github](https://pkg.go.dev/github.com/google/go-github/v73/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v73.0.0/LICENSE))
  - [github.com/google/go-querystring/query](https://pkg.go.dev/github.com/google/go-querystring/query) ([BSD-3-Clause](https://github.com/google/go-querystring/blob/v1.1.0/LICENSE))
  - [github.com/google/uuid](https://pkg.go.dev/github.com/google/uuid) ([BSD-3-Clause](https://github.com/google/uuid/blob/v1.6.0/LICENSE))
  - [github.com/gorilla/mux](https://pkg.go.dev/github.com/gorilla/mux) ([BSD-3-Clause](https://github.com/gorilla/mux/blob/v1.8.0/LICENSE))
diff --git a/third-party-licenses.windows.md b/third-party-licenses.windows.md
index d34ce2449..505c2d83e 100644
--- a/third-party-licenses.windows.md
+++ b/third-party-licenses.windows.md
@@ -13,7 +13,7 @@ Some packages may only be included on certain architectures or operating systems
  - [github.com/go-openapi/swag](https://pkg.go.dev/github.com/go-openapi/swag) ([Apache-2.0](https://github.com/go-openapi/swag/blob/v0.21.1/LICENSE))
  - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.3.0/LICENSE))
  - [github.com/google/go-github/v71/github](https://pkg.go.dev/github.com/google/go-github/v71/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v71.0.0/LICENSE))
- - [github.com/google/go-github/v72/github](https://pkg.go.dev/github.com/google/go-github/v72/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v72.0.0/LICENSE))
+ - [github.com/google/go-github/v73/github](https://pkg.go.dev/github.com/google/go-github/v73/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v73.0.0/LICENSE))
  - [github.com/google/go-querystring/query](https://pkg.go.dev/github.com/google/go-querystring/query) ([BSD-3-Clause](https://github.com/google/go-querystring/blob/v1.1.0/LICENSE))
  - [github.com/google/uuid](https://pkg.go.dev/github.com/google/uuid) ([BSD-3-Clause](https://github.com/google/uuid/blob/v1.6.0/LICENSE))
  - [github.com/gorilla/mux](https://pkg.go.dev/github.com/gorilla/mux) ([BSD-3-Clause](https://github.com/gorilla/mux/blob/v1.8.0/LICENSE))
diff --git a/third-party/github.com/google/go-github/v72/github/LICENSE b/third-party/github.com/google/go-github/v73/github/LICENSE
similarity index 100%
rename from third-party/github.com/google/go-github/v72/github/LICENSE
rename to third-party/github.com/google/go-github/v73/github/LICENSE

From 05681870383a5e8b142467c85bdeab021ec2f2bf Mon Sep 17 00:00:00 2001
From: yonaka <yonaka@jugoya.ai>
Date: Thu, 17 Jul 2025 21:29:46 +0900
Subject: [PATCH 22/32] Always include SHA in get_file_contents responses
 (#676)

* fix: Add SHA to get_file_contents while preserving MCP behavior (#595)

Enhance get_file_contents to include SHA information without changing
the existing MCP server response format.

Changes:
- Add Contents API call to retrieve SHA before fetching raw content
- Include SHA in resourceURI (repo://owner/repo/sha/{SHA}/contents/path)
- Add SHA to success messages
- Update tests to verify SHA inclusion
- Maintain original behavior: text files return raw text, binaries return base64

This preserves backward compatibility while providing SHA information
for better file versioning support.

Closes #595

* fix: Improve error handling for Contents API response

Ensure response body is properly closed even when an error occurs by moving
the defer statement before the error check. This prevents potential resource
leaks when the Contents API returns an error with a non-nil response.

Changes:
- Move defer respContents.Body.Close() before error checking
- Rename errContents to err for consistency
- Add nil check for respContents before attempting to close body

This follows Go best practices for handling HTTP responses and prevents
potential goroutine/memory leaks.

* revert changes to resource URI

* use GraphQL API to get file SHA

* refactor: mock GQL client instead of getFileSHA function to follow conventions

* lint

* revert GraphQL

---------

Co-authored-by: LuluBeatson <lulubeatson@github.com>
---
 pkg/github/repositories.go      | 36 +++++++++++++++++++++++++++++----
 pkg/github/repositories_test.go | 28 +++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index 58e4a7421..2e56c8644 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -507,6 +507,24 @@ func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t t
 			// If the path is (most likely) not to be a directory, we will
 			// first try to get the raw content from the GitHub raw content API.
 			if path != "" && !strings.HasSuffix(path, "/") {
+				// First, get file info from Contents API to retrieve SHA
+				var fileSHA string
+				opts := &github.RepositoryContentGetOptions{Ref: ref}
+				fileContent, _, respContents, err := client.Repositories.GetContents(ctx, owner, repo, path, opts)
+				if respContents != nil {
+					defer func() { _ = respContents.Body.Close() }()
+				}
+				if err != nil {
+					return ghErrors.NewGitHubAPIErrorResponse(ctx,
+						"failed to get file SHA",
+						respContents,
+						err,
+					), nil
+				}
+				if fileContent == nil || fileContent.SHA == nil {
+					return mcp.NewToolResultError("file content SHA is nil"), nil
+				}
+				fileSHA = *fileContent.SHA
 
 				rawClient, err := getRawClient(ctx)
 				if err != nil {
@@ -548,18 +566,28 @@ func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t t
 					}
 
 					if strings.HasPrefix(contentType, "application") || strings.HasPrefix(contentType, "text") {
-						return mcp.NewToolResultResource("successfully downloaded text file", mcp.TextResourceContents{
+						result := mcp.TextResourceContents{
 							URI:      resourceURI,
 							Text:     string(body),
 							MIMEType: contentType,
-						}), nil
+						}
+						// Include SHA in the result metadata
+						if fileSHA != "" {
+							return mcp.NewToolResultResource(fmt.Sprintf("successfully downloaded text file (SHA: %s)", fileSHA), result), nil
+						}
+						return mcp.NewToolResultResource("successfully downloaded text file", result), nil
 					}
 
-					return mcp.NewToolResultResource("successfully downloaded binary file", mcp.BlobResourceContents{
+					result := mcp.BlobResourceContents{
 						URI:      resourceURI,
 						Blob:     base64.StdEncoding.EncodeToString(body),
 						MIMEType: contentType,
-					}), nil
+					}
+					// Include SHA in the result metadata
+					if fileSHA != "" {
+						return mcp.NewToolResultResource(fmt.Sprintf("successfully downloaded binary file (SHA: %s)", fileSHA), result), nil
+					}
+					return mcp.NewToolResultResource("successfully downloaded binary file", result), nil
 
 				}
 			}
diff --git a/pkg/github/repositories_test.go b/pkg/github/repositories_test.go
index 0633e2123..1572a12f4 100644
--- a/pkg/github/repositories_test.go
+++ b/pkg/github/repositories_test.go
@@ -76,6 +76,20 @@ func Test_GetFileContents(t *testing.T) {
 						_, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`))
 					}),
 				),
+				mock.WithRequestMatchHandler(
+					mock.GetReposContentsByOwnerByRepoByPath,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						fileContent := &github.RepositoryContent{
+							Name: github.Ptr("README.md"),
+							Path: github.Ptr("README.md"),
+							SHA:  github.Ptr("abc123"),
+							Type: github.Ptr("file"),
+						}
+						contentBytes, _ := json.Marshal(fileContent)
+						_, _ = w.Write(contentBytes)
+					}),
+				),
 				mock.WithRequestMatchHandler(
 					raw.GetRawReposContentsByOwnerByRepoByBranchByPath,
 					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
@@ -107,6 +121,20 @@ func Test_GetFileContents(t *testing.T) {
 						_, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`))
 					}),
 				),
+				mock.WithRequestMatchHandler(
+					mock.GetReposContentsByOwnerByRepoByPath,
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						fileContent := &github.RepositoryContent{
+							Name: github.Ptr("test.png"),
+							Path: github.Ptr("test.png"),
+							SHA:  github.Ptr("def456"),
+							Type: github.Ptr("file"),
+						}
+						contentBytes, _ := json.Marshal(fileContent)
+						_, _ = w.Write(contentBytes)
+					}),
+				),
 				mock.WithRequestMatchHandler(
 					raw.GetRawReposContentsByOwnerByRepoByBranchByPath,
 					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {

From 1a74e6d63edfe7930bbd589b9eac91c8b341d03c Mon Sep 17 00:00:00 2001
From: Dimitrios Philliou <d1m1tr10s@github.com>
Date: Fri, 18 Jul 2025 01:33:59 -0700
Subject: [PATCH 23/32] Reorganize README, add dedicated install guides,
 include policies and governance info for the github server (#695)

* Refactor README and add host installation guides, governance docs

- Reorganized README for clarity and navigation
- Added dedicated installation guides for Claude, Cursor, Windsurf, JetBrains, and more
- Clarified contribution guidelines and approval criteria
- Added policies and governance documentation

* Update README.md

* Update README with configuration section for remote GitHub MCP Server

* Update MCP access policy description in README

Removing coding agent from the policy note, as the GitHub server is unaffected by this policy

* Update configuration steps for GitHub Copilot in JetBrains IDEs...

...to reflect changes in accessing settings and configuring MCP.

* Update install-other-copilot-ides.md

* Update Eclipse MCP support version and configuration steps...

...for GitHub Copilot plugin in installation guide.

* Update docs/installation-guides/install-cursor.md

* Update docs/installation-guides/install-windsurf.md

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

---------

Co-authored-by: Tony Truong <tonytrg@github.com>
---
 CONTRIBUTING.md                               |  11 +
 README.md                                     | 466 +++++++++---------
 docs/installation-guides/README.md            |  95 ++++
 docs/installation-guides/install-claude.md    | 204 ++++++++
 docs/installation-guides/install-cursor.md    | 123 +++++
 .../install-other-copilot-ides.md             | 265 ++++++++++
 docs/installation-guides/install-windsurf.md  | 107 ++++
 docs/policies-and-governance.md               | 216 ++++++++
 8 files changed, 1261 insertions(+), 226 deletions(-)
 create mode 100644 docs/installation-guides/README.md
 create mode 100644 docs/installation-guides/install-claude.md
 create mode 100644 docs/installation-guides/install-cursor.md
 create mode 100644 docs/installation-guides/install-other-copilot-ides.md
 create mode 100644 docs/installation-guides/install-windsurf.md
 create mode 100644 docs/policies-and-governance.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b4012f0b2..2307f6a28 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,6 +10,17 @@ Contributions to this project are [released](https://help.github.com/articles/gi
 
 Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
 
+## What we're looking for
+
+We can't guarantee that every tool, feature, or pull request will be approved or merged. Our focus is on supporting high-quality, high-impact capabilities that advance agentic workflows and deliver clear value to developers.
+
+To increase the chances your request is accepted:
+* Include real use cases or examples that demonstrate practical value
+* If your request stalls, you can open a Discussion post and link to your issue or PR
+* We actively revisit requests that gain strong community engagement (👍s, comments, or evidence of real-world use)
+
+Thanks for contributing and for helping us build toolsets that are truly valuable!
+
 ## Prerequisites for running and testing code
 
 These are one time installations required to be able to test your changes locally as part of the pull request (PR) submission process.
diff --git a/README.md b/README.md
index c5274ff83..7a6860262 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,16 @@
 # GitHub MCP Server
 
-The GitHub MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
-server that provides seamless integration with GitHub APIs, enabling advanced
-automation and interaction capabilities for developers and tools.
+The GitHub MCP Server connects AI tools directly to GitHub's platform. This gives AI agents, assistants, and chatbots the ability to read repositories and code files, manage issues and PRs, analyze code, and automate workflows. All through natural language interactions.
 
 ### Use Cases
 
-- Automating GitHub workflows and processes.
-- Extracting and analyzing data from GitHub repositories.
-- Building AI powered tools and applications that interact with GitHub's ecosystem.
+- Repository Management: Browse and query code, search files, analyze commits, and understand project structure across any repository you have access to.
+- Issue & PR Automation: Create, update, and manage issues and pull requests. Let AI help triage bugs, review code changes, and maintain project boards.
+- CI/CD & Workflow Intelligence: Monitor GitHub Actions workflow runs, analyze build failures, manage releases, and get insights into your development pipeline.
+- Code Analysis: Examine security findings, review Dependabot alerts, understand code patterns, and get comprehensive insights into your codebase.
+- Team Collaboration: Access discussions, manage notifications, analyze team activity, and streamline processes for your team.
+
+Built for developers who want to connect their AI tools to GitHub context and capabilities, from simple natural language queries to complex multi-step agent workflows.
 
 ---
 
@@ -18,17 +20,15 @@ automation and interaction capabilities for developers and tools.
 
 The remote GitHub MCP Server is hosted by GitHub and provides the easiest method for getting up and running. If your MCP host does not support remote MCP servers, don't worry! You can use the [local version of the GitHub MCP Server](https://github.com/github/github-mcp-server?tab=readme-ov-file#local-github-mcp-server) instead.
 
-## Prerequisites
-
-1. An MCP host that supports the latest MCP specification and remote servers, such as [VS Code](https://code.visualstudio.com/).
+### Prerequisites
 
-## Installation
+1. A compatible MCP host with remote server support (VS Code 1.101+, Claude Desktop, Cursor, Windsurf, etc.)
+2. Any applicable [policies enabled](https://github.com/github/github-mcp-server/blob/main/docs/policies-and-governance.md)
 
-### Usage with VS Code
+### Install in VS Code
 
 For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start. Make sure you're using [VS Code 1.101](https://code.visualstudio.com/updates/v1_101) or [later](https://code.visualstudio.com/updates) for remote MCP and OAuth support.
 
-
 Alternatively, to manually configure VS Code, choose the appropriate JSON block from the examples below and add it to your host configuration:
 
 <table>
@@ -77,48 +77,21 @@ Alternatively, to manually configure VS Code, choose the appropriate JSON block
 </tr>
 </table>
 
-### Usage in other MCP Hosts
-
-For MCP Hosts that are [Remote MCP-compatible](docs/host-integration.md), choose the appropriate JSON block from the examples below and add it to your host configuration:
+### Install in other MCP hosts
+- **[GitHub Copilot in other IDEs](/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
+- **[Claude Applications](/docs/installation-guides/install-claude.md)** - Installation guide for Claude Web, Claude Desktop and Claude Code CLI
+- **[Cursor](/docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE
+- **[Windsurf](/docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE
 
-<table>
-<tr><th>Using OAuth</th><th>Using a GitHub PAT</th></tr>
-<tr valign=top>
-<td>
-  
-```json
-{
-  "mcpServers": {
-    "github": {
-      "url": "https://api.githubcopilot.com/mcp/"
-    }
-  }
-}
-```
+> **Note:** Each MCP host application needs to configure a GitHub App or OAuth App to support remote access via OAuth. Any host application that supports remote MCP servers should support the remote GitHub server with PAT authentication. Configuration details and support levels vary by host. Make sure to refer to the host application's documentation for more info.
 
-</td>
-<td>
-
-```json
-{
-  "mcpServers": {
-    "github": {
-      "url": "https://api.githubcopilot.com/mcp/",
-      "authorization_token": "Bearer <your GitHub PAT>"
-    }
-  }
-}
-```
-
-</td>
-</tr>
-</table>
-
-> **Note:** The exact configuration format may vary by host. Refer to your host's documentation for the correct syntax and location for remote MCP server setup.
+> ⚠️ **Public Preview Status:** The **remote** GitHub MCP Server is currently in Public Preview. During preview, access may be gated depending on authentication type and surface:
+> - OAuth: Subject to GitHub Copilot Editor Preview Policy until GA
+> - PAT: Controlled via your organization's PAT policies
+> - MCP Servers in Copilot policy: Enables/disables access to all MCP servers in VS Code, with other Copilot editors migrating to this policy in the coming months.
 
 ### Configuration
-
-See [Remote Server Documentation](docs/remote-server.md) on how to pass additional configuration settings to the remote GitHub MCP Server.
+See [Remote Server Documentation](/docs/remote-server.md) on how to pass additional configuration settings to the remote GitHub MCP Server.
 
 ---
 
@@ -126,22 +99,72 @@ See [Remote Server Documentation](docs/remote-server.md) on how to pass addition
 
 [![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D&quality=insiders)
 
-## Prerequisites
+### Prerequisites
 
 1. To run the server in a container, you will need to have [Docker](https://www.docker.com/) installed.
 2. Once Docker is installed, you will also need to ensure Docker is running. The image is public; if you get errors on pull, you may have an expired token and need to `docker logout ghcr.io`.
 3. Lastly you will need to [Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new).
 The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools (to learn more about access tokens, please check out the [documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)).
 
+<details><summary><b>Handling PATs Securely</b></summary>
+
+### Environment Variables (Recommended)
+To keep your GitHub PAT secure and reusable across different MCP hosts:
+
+1. **Store your PAT in environment variables**
+   ```bash
+   export GITHUB_PAT=your_token_here
+   ```
+   Or create a `.env` file:
+   ```env
+   GITHUB_PAT=your_token_here
+   ```
+
+2. **Protect your `.env` file**
+   ```bash
+   # Add to .gitignore to prevent accidental commits
+   echo ".env" >> .gitignore
+   ```
+
+3. **Reference the token in configurations**
+   ```bash
+   # CLI usage
+   claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT
+   
+   # In config files (where supported)
+   "env": {
+     "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
+   }
+   ```
+
+> **Note**: Environment variable support varies by host app and IDE. Some applications (like Windsurf) require hardcoded tokens in config files.
+
+### Token Security Best Practices
+
+- **Minimum scopes**: Only grant necessary permissions
+  - `repo` - Repository operations
+  - `read:packages` - Docker image access
+- **Separate tokens**: Use different PATs for different projects/environments
+- **Regular rotation**: Update tokens periodically
+- **Never commit**: Keep tokens out of version control
+- **File permissions**: Restrict access to config files containing tokens
+  ```bash
+  chmod 600 ~/.your-app/config.json
+  ```
+
+</details>
+
 ## Installation
 
-### Usage with VS Code
+### Install in GitHub Copilot on VS Code
+
+For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start.
 
-For quick installation, use one of the one-click install buttons. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start.
+More about using MCP server tools in VS Code's [agent mode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
 
-### Usage in other MCP Hosts
+Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc.)
 
-Add the following JSON block to your IDE MCP settings.
+Add the following JSON block to your IDE's MCP settings.
 
 ```json
 {
@@ -174,8 +197,11 @@ Add the following JSON block to your IDE MCP settings.
 }
 ```
 
-Optionally, you can add a similar example (i.e. without the mcp key) to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
+Optionally, you can add a similar example (i.e. without the mcp key) to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with other host applications that accept the same format.
 
+<details>
+<summary><b>Example JSON block without the MCP key included</b></summary>
+<br>
 
 ```json
 {
@@ -204,33 +230,21 @@ Optionally, you can add a similar example (i.e. without the mcp key) to a file c
     }
   }
 }
-
 ```
 
-More about using MCP server tools in VS Code's [agent mode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
+</details>
 
-### Usage with Claude Desktop
+### Install in Other Host Applications
 
-```json
-{
-  "mcpServers": {
-    "github": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "-e",
-        "GITHUB_PERSONAL_ACCESS_TOKEN",
-        "ghcr.io/github/github-mcp-server"
-      ],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
-      }
-    }
-  }
-}
-```
+For other MCP host applications, please refer to our installation guides:
+
+- **[Claude Code & Claude Desktop](docs/installation-guides/install-claude.md)** - Installation guide for Claude Code and Claude Desktop
+- **[Cursor](docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE  
+- **[Windsurf](docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE
+
+For a complete overview of all installation options, see our **[Installation Guides Index](docs/installation-guides/installation-guides.md)**.
+
+> **Note:** Any host application that supports local MCP servers should be able to access the local GitHub MCP server. However, the specific configuration process, syntax and stability of the integration will vary by host application. While many may follow a similar format to the examples above, this is not guaranteed. Please refer to your host application's documentation for the correct MCP configuration syntax and setup process.
 
 ### Build from source
 
@@ -281,153 +295,6 @@ The following sets of tools are available (all are on by default):
 | `users` | GitHub User related tools |
 <!-- END AUTOMATED TOOLSETS -->
 
-#### Specifying Toolsets
-
-To specify toolsets you want available to the LLM, you can pass an allow-list in two ways:
-
-1. **Using Command Line Argument**:
-
-   ```bash
-   github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security
-   ```
-
-2. **Using Environment Variable**:
-   ```bash
-   GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server
-   ```
-
-The environment variable `GITHUB_TOOLSETS` takes precedence over the command line argument if both are provided.
-
-### Using Toolsets With Docker
-
-When using Docker, you can pass the toolsets as environment variables:
-
-```bash
-docker run -i --rm \
-  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-  -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security,experiments" \
-  ghcr.io/github/github-mcp-server
-```
-
-### The "all" Toolset
-
-The special toolset `all` can be provided to enable all available toolsets regardless of any other configuration:
-
-```bash
-./github-mcp-server --toolsets all
-```
-
-Or using the environment variable:
-
-```bash
-GITHUB_TOOLSETS="all" ./github-mcp-server
-```
-
-## Dynamic Tool Discovery
-
-**Note**: This feature is currently in beta and may not be available in all environments. Please test it out and let us know if you encounter any issues.
-
-Instead of starting with all tools enabled, you can turn on dynamic toolset discovery. Dynamic toolsets allow the MCP host to list and enable toolsets in response to a user prompt. This should help to avoid situations where the model gets confused by the sheer number of tools available.
-
-### Using Dynamic Tool Discovery
-
-When using the binary, you can pass the `--dynamic-toolsets` flag.
-
-```bash
-./github-mcp-server --dynamic-toolsets
-```
-
-When using Docker, you can pass the toolsets as environment variables:
-
-```bash
-docker run -i --rm \
-  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-  -e GITHUB_DYNAMIC_TOOLSETS=1 \
-  ghcr.io/github/github-mcp-server
-```
-
-## Read-Only Mode
-
-To run the server in read-only mode, you can use the `--read-only` flag. This will only offer read-only tools, preventing any modifications to repositories, issues, pull requests, etc.
-
-```bash
-./github-mcp-server --read-only
-```
-
-When using Docker, you can pass the read-only mode as an environment variable:
-
-```bash
-docker run -i --rm \
-  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-  -e GITHUB_READ_ONLY=1 \
-  ghcr.io/github/github-mcp-server
-```
-
-## GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com)
-
-The flag `--gh-host` and the environment variable `GITHUB_HOST` can be used to set
-the hostname for GitHub Enterprise Server or GitHub Enterprise Cloud with data residency.
-
-- For GitHub Enterprise Server, prefix the hostname with the `https://` URI scheme, as it otherwise defaults to `http://`, which GitHub Enterprise Server does not support.
-- For GitHub Enterprise Cloud with data residency, use `https://YOURSUBDOMAIN.ghe.com` as the hostname.
-``` json
-"github": {
-    "command": "docker",
-    "args": [
-    "run",
-    "-i",
-    "--rm",
-    "-e",
-    "GITHUB_PERSONAL_ACCESS_TOKEN",
-    "-e",
-    "GITHUB_HOST",
-    "ghcr.io/github/github-mcp-server"
-    ],
-    "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
-        "GITHUB_HOST": "https://<your GHES or ghe.com domain name>"
-    }
-}
-```
-
-## i18n / Overriding Descriptions
-
-The descriptions of the tools can be overridden by creating a
-`github-mcp-server-config.json` file in the same directory as the binary.
-
-The file should contain a JSON object with the tool names as keys and the new
-descriptions as values. For example:
-
-```json
-{
-  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
-  "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
-}
-```
-
-You can create an export of the current translations by running the binary with
-the `--export-translations` flag.
-
-This flag will preserve any translations/overrides you have made, while adding
-any new translations that have been added to the binary since the last time you
-exported.
-
-```sh
-./github-mcp-server --export-translations
-cat github-mcp-server-config.json
-```
-
-You can also use ENV vars to override the descriptions. The environment
-variable names are the same as the keys in the JSON file, prefixed with
-`GITHUB_MCP_` and all uppercase.
-
-For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can
-set the following environment variable:
-
-```sh
-export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"
-```
-
 ## Tools
 
 
@@ -997,6 +864,153 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description
 
 </details>
 
+#### Specifying Toolsets
+
+To specify toolsets you want available to the LLM, you can pass an allow-list in two ways:
+
+1. **Using Command Line Argument**:
+
+   ```bash
+   github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security
+   ```
+
+2. **Using Environment Variable**:
+   ```bash
+   GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server
+   ```
+
+The environment variable `GITHUB_TOOLSETS` takes precedence over the command line argument if both are provided.
+
+### Using Toolsets With Docker
+
+When using Docker, you can pass the toolsets as environment variables:
+
+```bash
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security,experiments" \
+  ghcr.io/github/github-mcp-server
+```
+
+### The "all" Toolset
+
+The special toolset `all` can be provided to enable all available toolsets regardless of any other configuration:
+
+```bash
+./github-mcp-server --toolsets all
+```
+
+Or using the environment variable:
+
+```bash
+GITHUB_TOOLSETS="all" ./github-mcp-server
+```
+
+## Dynamic Tool Discovery
+
+**Note**: This feature is currently in beta and may not be available in all environments. Please test it out and let us know if you encounter any issues.
+
+Instead of starting with all tools enabled, you can turn on dynamic toolset discovery. Dynamic toolsets allow the MCP host to list and enable toolsets in response to a user prompt. This should help to avoid situations where the model gets confused by the sheer number of tools available.
+
+### Using Dynamic Tool Discovery
+
+When using the binary, you can pass the `--dynamic-toolsets` flag.
+
+```bash
+./github-mcp-server --dynamic-toolsets
+```
+
+When using Docker, you can pass the toolsets as environment variables:
+
+```bash
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_DYNAMIC_TOOLSETS=1 \
+  ghcr.io/github/github-mcp-server
+```
+
+## Read-Only Mode
+
+To run the server in read-only mode, you can use the `--read-only` flag. This will only offer read-only tools, preventing any modifications to repositories, issues, pull requests, etc.
+
+```bash
+./github-mcp-server --read-only
+```
+
+When using Docker, you can pass the read-only mode as an environment variable:
+
+```bash
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_READ_ONLY=1 \
+  ghcr.io/github/github-mcp-server
+```
+
+## GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com)
+
+The flag `--gh-host` and the environment variable `GITHUB_HOST` can be used to set
+the hostname for GitHub Enterprise Server or GitHub Enterprise Cloud with data residency.
+
+- For GitHub Enterprise Server, prefix the hostname with the `https://` URI scheme, as it otherwise defaults to `http://`, which GitHub Enterprise Server does not support.
+- For GitHub Enterprise Cloud with data residency, use `https://YOURSUBDOMAIN.ghe.com` as the hostname.
+``` json
+"github": {
+    "command": "docker",
+    "args": [
+    "run",
+    "-i",
+    "--rm",
+    "-e",
+    "GITHUB_PERSONAL_ACCESS_TOKEN",
+    "-e",
+    "GITHUB_HOST",
+    "ghcr.io/github/github-mcp-server"
+    ],
+    "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
+        "GITHUB_HOST": "https://<your GHES or ghe.com domain name>"
+    }
+}
+```
+
+## i18n / Overriding Descriptions
+
+The descriptions of the tools can be overridden by creating a
+`github-mcp-server-config.json` file in the same directory as the binary.
+
+The file should contain a JSON object with the tool names as keys and the new
+descriptions as values. For example:
+
+```json
+{
+  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
+  "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
+}
+```
+
+You can create an export of the current translations by running the binary with
+the `--export-translations` flag.
+
+This flag will preserve any translations/overrides you have made, while adding
+any new translations that have been added to the binary since the last time you
+exported.
+
+```sh
+./github-mcp-server --export-translations
+cat github-mcp-server-config.json
+```
+
+You can also use ENV vars to override the descriptions. The environment
+variable names are the same as the keys in the JSON file, prefixed with
+`GITHUB_MCP_` and all uppercase.
+
+For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can
+set the following environment variable:
+
+```sh
+export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"
+```
+
 ## Library Usage
 
 The exported Go API of this module should currently be considered unstable, and subject to breaking changes. In the future, we may offer stability; please file an issue if there is a use case where this would be valuable.
diff --git a/docs/installation-guides/README.md b/docs/installation-guides/README.md
new file mode 100644
index 000000000..f55cc6bef
--- /dev/null
+++ b/docs/installation-guides/README.md
@@ -0,0 +1,95 @@
+# GitHub MCP Server Installation Guides
+
+This directory contains detailed installation instructions for the GitHub MCP Server across different host applications and IDEs. Choose the guide that matches your development environment.
+
+## Installation Guides by Host Application
+- **[GitHub Copilot in other IDEs](install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
+- **[Claude Applications](install-claude.md)** - Installation guide for Claude Web, Claude Desktop and Claude Code CLI
+- **[Cursor](install-cursor.md)** - Installation guide for Cursor IDE
+- **[Windsurf](install-windsurf.md)** - Installation guide for Windsurf IDE
+
+## Support by Host Application
+
+| Host Application | Local GitHub MCP Support | Remote GitHub MCP Support | Prerequisites | Difficulty |
+|-----------------|---------------|----------------|---------------|------------|
+| Copilot in VS Code | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT<br>Remote: VS Code 1.101+ | Easy |
+| Copilot Coding Agent | ✅ | ✅ Full (on by default; no auth needed) | Any _paid_ copilot license | Default on |
+| Copilot in Visual Studio | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT<br>Remote: Visual Studio 17.14+ | Easy |
+| Copilot in JetBrains | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT<br>Remote: JetBrains Copilot Extension v1.5.35+ | Easy |
+| Claude Code | ✅ | ✅ PAT + ❌ No OAuth| GitHub MCP Server binary or remote URL, GitHub PAT | Easy |
+| Claude Desktop | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Moderate |
+| Cursor | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
+| Windsurf | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy |
+| Copilot in Xcode | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT<br>Remote: Copilot for Xcode latest version | Easy |
+| Copilot in Eclipse | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT<br>Remote: TBD | Easy |
+
+**Legend:**
+- ✅ = Fully supported
+- ❌ = Not yet supported
+
+**Note:** Remote MCP support requires host applications to register a GitHub App or OAuth app for OAuth flow support – even if the new OAuth spec is supported by that host app. Currently, only VS Code has full remote GitHub server support. 
+
+## Installation Methods
+
+The GitHub MCP Server can be installed using several methods. **Docker is the most popular and recommended approach** for most users, but alternatives are available depending on your needs:
+
+### 🐳 Docker (Most Common & Recommended)
+- **Pros**: No local build required, consistent environment, easy updates, works across all platforms
+- **Cons**: Requires Docker installed and running
+- **Best for**: Most users, especially those already using Docker or wanting the simplest setup
+- **Used by**: Claude Desktop, Copilot in VS Code, Cursor, Windsurf, etc.
+
+### 📦 Pre-built Binary (Lightweight Alternative)
+- **Pros**: No Docker required, direct execution via stdio, minimal setup
+- **Cons**: Need to manually download and manage updates, platform-specific binaries
+- **Best for**: Minimal environments, users who prefer not to use Docker
+- **Used by**: Claude Code CLI, lightweight setups
+
+### 🔨 Build from Source (Advanced Users)
+- **Pros**: Latest features, full customization, no external dependencies
+- **Cons**: Requires Go development environment, more complex setup
+- **Prerequisites**: [Go 1.24+](https://go.dev/doc/install)
+- **Build command**: `go build -o github-mcp-server cmd/github-mcp-server/main.go`
+- **Best for**: Developers who want the latest features or need custom modifications
+
+### Important Notes on the GitHub MCP Server
+
+- **Docker Image**: The official Docker image is now `ghcr.io/github/github-mcp-server`
+- **npm Package**: The npm package @modelcontextprotocol/server-github is no longer supported as of April 2025
+- **Remote Server**: The remote server URL is `https://api.githubcopilot.com/mcp/`
+
+## General Prerequisites
+
+All installations with Personal Access Tokens (PAT) require:
+- **GitHub Personal Access Token (PAT)**: [Create one here](https://github.com/settings/personal-access-tokens/new)
+
+Optional (depending on installation method):
+- **Docker** (for Docker-based installations): [Download Docker](https://www.docker.com/)
+- **Go 1.24+** (for building from source): [Install Go](https://go.dev/doc/install)
+
+## Security Best Practices
+
+Regardless of which installation method you choose, follow these security guidelines:
+
+1. **Secure Token Storage**: Never commit your GitHub PAT to version control
+2. **Limit Token Scope**: Only grant necessary permissions to your GitHub PAT
+3. **File Permissions**: Restrict access to configuration files containing tokens
+4. **Regular Rotation**: Periodically rotate your GitHub Personal Access Tokens
+5. **Environment Variables**: Use environment variables when supported by your host
+
+## Getting Help
+
+If you encounter issues:
+1. Check the troubleshooting section in your specific installation guide
+2. Verify your GitHub PAT has the required permissions
+3. Ensure Docker is running (for local installations)
+4. Review your host application's logs for error messages
+5. Consult the main [README.md](README.md) for additional configuration options
+
+## Configuration Options
+
+After installation, you may want to explore:
+- **Toolsets**: Enable/disable specific GitHub API capabilities
+- **Read-Only Mode**: Restrict to read-only operations
+- **Dynamic Tool Discovery**: Enable tools on-demand
+
diff --git a/docs/installation-guides/install-claude.md b/docs/installation-guides/install-claude.md
new file mode 100644
index 000000000..2c50be2f9
--- /dev/null
+++ b/docs/installation-guides/install-claude.md
@@ -0,0 +1,204 @@
+# Install GitHub MCP Server in Claude Applications
+
+This guide covers installation of the GitHub MCP server for Claude Code CLI, Claude Desktop, and Claude Web applications.
+
+## Claude Web (claude.ai)
+
+Claude Web supports remote MCP servers through the Integrations built-in feature.
+
+### Prerequisites
+
+1. Claude Pro, Team, or Enterprise account (Integrations not available on free plan)
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+
+### Installation
+
+**Note**: As of July 2025, the remote GitHub MCP Server has known compatibility issues with Claude Web. While Claude Web supports remote MCP servers from other providers (like Atlassian, Zapier, Notion), the GitHub MCP Server integration may not work reliably.
+
+For other remote MCP servers that do work with Claude Web:
+
+1. Go to [claude.ai](https://claude.ai) and log in
+2. Click your profile icon → **Settings**
+3. Navigate to **Integrations** section
+4. Click **+ Add integration** or **Add More**
+5. Enter the remote server URL
+6. Follow the OAuth authentication flow when prompted
+
+**Alternative**: Use Claude Desktop or Claude Code CLI for reliable GitHub MCP Server integration.
+
+---
+
+## Claude Code CLI
+
+Claude Code CLI provides command-line access to Claude with MCP server integration.
+
+### Prerequisites
+
+1. Claude Code CLI installed
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+3. [Docker](https://www.docker.com/) installed and running
+
+### Installation
+
+Run the following command to add the GitHub MCP server using Docker:
+
+```bash
+claude mcp add github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
+```
+
+Then set the environment variable:
+```bash
+claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=your_github_pat
+```
+
+Or as a single command with the token inline:
+```bash
+claude mcp add-json github '{"command": "docker", "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat"}}'
+```
+
+**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
+
+### Configuration Options
+
+- Use `-s user` to add the server to your user configuration (available across all projects)
+- Use `-s project` to add the server to project-specific configuration (shared via `.mcp.json`)
+- Default scope is `local` (available only to you in the current project)
+
+### Verification
+
+Run the following command to verify the installation:
+```bash
+claude mcp list
+```
+
+---
+
+## Claude Desktop
+
+Claude Desktop provides a graphical interface for interacting with the GitHub MCP Server.
+
+### Prerequisites
+
+1. Claude Desktop installed
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+3. [Docker](https://www.docker.com/) installed and running
+
+### Configuration File Location
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json` (unofficial support)
+
+### Installation
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat"
+      }
+    }
+  }
+}
+```
+
+**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
+
+### Using Environment Variables
+
+Claude Desktop supports environment variable references. You can use:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+Then set the environment variable in your system before starting Claude Desktop.
+
+### Installation Steps
+
+1. Open Claude Desktop
+2. Go to Settings (from the Claude menu) → Developer → Edit Config
+3. Add your chosen configuration
+4. Save the file
+5. Restart Claude Desktop
+
+### Verification
+
+After restarting, you should see:
+- An MCP icon in the Claude Desktop interface
+- The GitHub server listed as "running" in Developer settings
+
+---
+
+## Troubleshooting
+
+### Claude Web
+- Currently experiencing compatibility issues with the GitHub MCP Server
+- Try other remote MCP servers (Atlassian, Zapier, Notion) which work reliably
+- Use Claude Desktop or Claude Code CLI as alternatives for GitHub integration
+
+### Claude Code CLI
+- Verify the command syntax is correct (note the single quotes around the JSON)
+- Ensure Docker is running: `docker --version`
+- Use `/mcp` command within Claude Code to check server status
+
+### Claude Desktop
+- Check logs at:
+  - **macOS**: `~/Library/Logs/Claude/`
+  - **Windows**: `%APPDATA%\Claude\logs\`
+- Look for `mcp-server-github.log` for server-specific errors
+- Ensure configuration file is valid JSON
+- Try running the Docker command manually in terminal to diagnose issues
+
+### Common Issues
+- **Invalid JSON**: Validate your configuration at [jsonlint.com](https://jsonlint.com)
+- **PAT issues**: Ensure your GitHub PAT has required scopes
+- **Docker not found**: Install Docker Desktop and ensure it's running
+- **Docker image pull fails**: Try `docker logout ghcr.io` then retry
+
+---
+
+## Security Best Practices
+
+- **Protect configuration files**: Set appropriate file permissions
+- **Use environment variables** when possible instead of hardcoding tokens
+- **Limit PAT scope** to only necessary permissions
+- **Regularly rotate** your GitHub Personal Access Tokens
+- **Never commit** configuration files containing tokens to version control
+
+---
+
+## Additional Resources
+
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
+- [Claude Code MCP Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)
+- [Claude Web Integrations Support](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp)
diff --git a/docs/installation-guides/install-cursor.md b/docs/installation-guides/install-cursor.md
new file mode 100644
index 000000000..82b36c3e6
--- /dev/null
+++ b/docs/installation-guides/install-cursor.md
@@ -0,0 +1,123 @@
+# Install GitHub MCP Server in Cursor
+
+## Prerequisites
+1. Cursor IDE installed (latest version)
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
+3. For local installation: [Docker](https://www.docker.com/) installed and running
+
+## Remote Server Setup (Recommended)
+
+The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP protocol. Cursor currently supports remote servers with PAT authentication.
+
+### Streamable HTTP Configuration
+As of Cursor v0.48.0, Cursor supports Streamable HTTP servers directly:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+**Note**: You may need to update to the latest version, if the current version doesn't support direct Streamable HTTP
+
+## Local Server Setup
+
+### Docker Installation (Required)
+> **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+## Installation Steps
+
+### Via Cursor Settings UI
+1. Open Cursor
+2. Navigate to **Settings** → **Tools & Integrations** → **MCP**
+3. Click **"+ Add new global MCP server"**
+4. This opens `~/.cursor/mcp.json` in the editor
+5. Add your chosen configuration from above
+6. Save the file
+7. Restart Cursor
+
+### Manual Configuration
+1. Create or edit the configuration file:
+   - **Global (all projects)**: `~/.cursor/mcp.json`
+   - **Project-specific**: `.cursor/mcp.json` in project root
+2. Add your chosen configuration
+3. Save the file
+4. Restart Cursor completely
+
+### Token Security
+- Create PATs with minimum required scopes:
+  - `repo` - For repository operations
+  - `read:packages` - For Docker image pull (local setup)
+  - Additional scopes based on tools you need
+- Use separate PATs for different projects
+- Regularly rotate tokens
+- Never commit configuration files to version control
+
+## Configuration Details
+
+- **File paths**: 
+  - Global: `~/.cursor/mcp.json`
+  - Project: `.cursor/mcp.json`
+- **Scope**: Both global and project-specific configurations supported
+- **Format**: Must be valid JSON (use a linter to verify)
+
+## Verification
+
+After installation:
+1. Restart Cursor completely
+2. Open Settings → Tools & Integrations → MCP
+3. Look for green dot next to your server name
+4. In chat/composer, check "Available Tools"
+5. Test with: "List my GitHub repositories"
+
+## Troubleshooting
+
+### Remote Server Issues
+- **Streamable HTTP not working**: Ensure you're using Cursor v0.48.0 or later
+- **Authentication failures**: Verify PAT has correct scopes
+- **Connection errors**: Check firewall/proxy settings
+
+### Local Server Issues
+- **Docker errors**: Ensure Docker Desktop is running
+- **Image pull failures**: Try `docker logout ghcr.io` then retry
+- **Docker not found**: Install Docker Desktop and ensure it's running
+
+### General Issues
+- **MCP not loading**: Restart Cursor completely after configuration
+- **Invalid JSON**: Validate that json format is correct
+- **Tools not appearing**: Check server shows green dot in MCP settings
+- **Check logs**: Look for MCP-related errors in Cursor logs
+
+## Important Notes
+
+- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported)
+- **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional)
+- **Cursor specifics**: Supports both project and global configurations, uses `mcpServers` key
diff --git a/docs/installation-guides/install-other-copilot-ides.md b/docs/installation-guides/install-other-copilot-ides.md
new file mode 100644
index 000000000..18ffdd84a
--- /dev/null
+++ b/docs/installation-guides/install-other-copilot-ides.md
@@ -0,0 +1,265 @@
+# Install GitHub MCP Server in Copilot IDEs & GitHub.com
+
+Quick setup guide for the GitHub MCP server in GitHub Copilot across different IDEs. For VS Code instructions, refer to the [VS Code install guide in the README](/README.md#installation-in-vs-code)
+
+### Requirements:
+- **GitHub Copilot License**: Any Copilot plan (Free, Pro, Pro+, Business, Enterprise) for Copilot access
+- **GitHub Account**: Individual GitHub account (organization/enterprise membership optional) for GitHub MCP server access
+- **MCP Servers in Copilot Policy**: Organizations assigning Copilot seats must enable this policy for all MCP access in Copilot for VS Code and Copilot Coding Agent – all other Copilot IDEs will migrate to this policy in the coming months
+- **Editor Preview Policy**: Organizations assigning Copilot seats must enable this policy for OAuth access while the Remote GitHub MCP Server is in public preview
+
+> **Note:** All Copilot IDEs now support the remote GitHub MCP server. VS Code offers OAuth authentication, while Visual Studio, JetBrains IDEs, Xcode, and Eclipse currently use PAT authentication with OAuth support coming soon.
+
+## Visual Studio
+
+Requires Visual Studio 2022 version 17.14 or later.
+
+### Remote Server (Recommended)
+
+The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
+
+#### Configuration
+1. Go to **Tools** → **Options** → **GitHub** → **Copilot** → **MCP Servers**
+2. Add this configuration:
+```json
+{
+  "servers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "authorization_token": "Bearer YOUR_GITHUB_PAT"
+    }
+  }
+}
+```
+3. Restart Visual Studio
+
+### Local Server
+
+For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
+
+#### Configuration
+1. Create an `.mcp.json` file in your solution directory
+2. Add this configuration:
+```json
+{
+  "inputs": [
+    {
+      "id": "github_pat",
+      "description": "GitHub personal access token",
+      "type": "promptString",
+      "password": true
+    }
+  ],
+  "servers": {
+    "github": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_pat}"
+      }
+    }
+  }
+}
+```
+3. Save the file and restart Visual Studio
+
+**Documentation:** [Visual Studio MCP Guide](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022)
+
+---
+
+## JetBrains IDEs
+
+Agent mode and MCP support available in public preview across IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs.
+
+### Remote Server (Recommended)
+
+The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
+
+> **Note**: OAuth authentication for the remote GitHub server is not yet supported in JetBrains IDEs. You must use a Personal Access Token (PAT).
+
+#### Configuration Steps
+1. Install/update the GitHub Copilot plugin
+2. Click **GitHub Copilot icon in the status bar** → **Edit Settings** → **Model Context Protocol** → **Configure**
+3. Add configuration:
+```json
+{
+  "servers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "requestInit": {
+        "headers": {
+          "Authorization": "Bearer YOUR_GITHUB_PAT"
+        }
+      }
+    }
+  }
+}
+```
+4. Press `Ctrl + S` or `Command + S` to save, or close the `mcp.json` file. The configuration should take effect immediately and restart all the MCP servers defined. You can restart the IDE if needed.
+
+### Local Server
+
+For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
+
+#### Configuration
+```json
+{
+  "servers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm", 
+        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+**Documentation:** [JetBrains Copilot Guide](https://plugins.jetbrains.com/plugin/17718-github-copilot)
+
+---
+
+## Xcode
+
+Agent mode and MCP support now available in public preview for Xcode.
+
+### Remote Server (Recommended)
+
+The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
+
+> **Note**: OAuth authentication for the remote GitHub server is not yet supported in Xcode. You must use a Personal Access Token (PAT).
+
+#### Configuration Steps
+1. Install/update [GitHub Copilot for Xcode](https://github.com/github/CopilotForXcode)
+2. Open **GitHub Copilot for Xcode app** → **Agent Mode** → **🛠️ Tool Picker** → **Edit Config**
+3. Configure your MCP servers:
+```json
+{
+  "servers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "requestInit": {
+        "headers": {
+          "Authorization": "Bearer YOUR_GITHUB_PAT"
+        }
+      }
+    }
+  }
+}
+```
+
+### Local Server
+
+For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
+
+#### Configuration
+```json
+{
+  "servers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm", 
+        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+**Documentation:** [Xcode Copilot Guide](https://devblogs.microsoft.com/xcode/github-copilot-exploring-agent-mode-and-mcp-support-in-public-preview-for-xcode/)
+
+---
+
+## Eclipse
+
+MCP support available with Eclipse 2024-03+ and latest version of the GitHub Copilot plugin.
+
+### Remote Server (Recommended)
+
+The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required.
+
+> **Note**: OAuth authentication for the remote GitHub server is not yet supported in Eclipse. You must use a Personal Access Token (PAT).
+
+#### Configuration Steps
+1. Install GitHub Copilot extension from Eclipse Marketplace
+2. Click the **GitHub Copilot icon** → **Edit Preferences** → **MCP** (under **GitHub Copilot**)
+3. Add GitHub MCP server configuration:
+```json
+{
+  "servers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "requestInit": {
+        "headers": {
+          "Authorization": "Bearer YOUR_GITHUB_PAT"
+        }
+      }
+    }
+  }
+}
+```
+4. Click the "Apply and Close" button in the preference dialog and the configuration will take effect automatically.
+
+### Local Server
+
+For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running.
+
+#### Configuration
+```json
+{
+  "servers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm", 
+        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+**Documentation:** [Eclipse Copilot plugin](https://marketplace.eclipse.org/content/github-copilot)
+
+---
+
+## GitHub Personal Access Token
+
+For PAT authentication, see our [Personal Access Token documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for setup instructions.
+
+---
+
+## Usage
+
+After setup:
+1. Restart your IDE completely
+2. Open Agent mode in Copilot Chat
+3. Try: *"List recent issues in this repository"*
+4. Copilot can now access GitHub data and perform repository operations
+
+---
+
+## Troubleshooting
+
+- **Connection issues**: Verify GitHub PAT permissions and IDE version compatibility
+- **Authentication errors**: Check if your organization has enabled the MCP policy for Copilot
+- **Tools not appearing**: Restart IDE after configuration changes and check error logs
+- **Local server issues**: Ensure Docker is running for Docker-based setups
diff --git a/docs/installation-guides/install-windsurf.md b/docs/installation-guides/install-windsurf.md
new file mode 100644
index 000000000..8793e2edb
--- /dev/null
+++ b/docs/installation-guides/install-windsurf.md
@@ -0,0 +1,107 @@
+# Install GitHub MCP Server in Windsurf
+
+## Prerequisites
+1. Windsurf IDE installed (latest version)
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes
+3. For local installation: [Docker](https://www.docker.com/) installed and running
+
+## Remote Server Setup (Recommended)
+
+The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP protocol. Windsurf currently supports PAT authentication only.
+
+### Streamable HTTP Configuration
+Windsurf supports Streamable HTTP servers with a `serverUrl` field:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "serverUrl": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+## Local Server Setup
+
+### Docker Installation (Required)
+**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+## Installation Steps
+
+### Via Plugin Store
+1. Open Windsurf and navigate to Cascade
+2. Click the **Plugins** icon or **hammer icon** (🔨)
+3. Search for "GitHub MCP Server"
+4. Click **Install** and enter your PAT when prompted
+5. Click **Refresh** (🔄)
+
+### Manual Configuration
+1. Click the hammer icon (🔨) in Cascade
+2. Click **Configure** to open `~/.codeium/windsurf/mcp_config.json`
+3. Add your chosen configuration from above
+4. Save the file
+5. Click **Refresh** (🔄) in the MCP toolbar
+
+## Configuration Details
+
+- **File path**: `~/.codeium/windsurf/mcp_config.json`
+- **Scope**: Global configuration only (no per-project support)
+- **Format**: Must be valid JSON (use a linter to verify)
+
+## Verification
+
+After installation:
+1. Look for "1 available MCP server" in the MCP toolbar
+2. Click the hammer icon to see available GitHub tools
+3. Test with: "List my GitHub repositories"
+4. Check for green dot next to the server name
+
+## Troubleshooting
+
+### Remote Server Issues
+- **Authentication failures**: Verify PAT has correct scopes and hasn't expired
+- **Connection errors**: Check firewall/proxy settings for HTTPS connections
+- **Streamable HTTP not working**: Ensure you're using the correct `serverUrl` field format
+
+### Local Server Issues
+- **Docker errors**: Ensure Docker Desktop is running
+- **Image pull failures**: Try `docker logout ghcr.io` then retry
+- **Docker not found**: Install Docker Desktop and ensure it's running
+
+### General Issues
+- **Invalid JSON**: Validate with [jsonlint.com](https://jsonlint.com)
+- **Tools not appearing**: Restart Windsurf completely
+- **Check logs**: `~/.codeium/windsurf/logs/`
+
+## Important Notes
+
+- **Official repository**: [github/github-mcp-server](https://github.com/github/github-mcp-server)
+- **Remote server URL**: `https://api.githubcopilot.com/mcp/`
+- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported)
+- **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional)
+- **Windsurf limitations**: No environment variable interpolation, global config only
diff --git a/docs/policies-and-governance.md b/docs/policies-and-governance.md
new file mode 100644
index 000000000..d7f52212a
--- /dev/null
+++ b/docs/policies-and-governance.md
@@ -0,0 +1,216 @@
+# Policies & Governance for the GitHub MCP Server
+
+Organizations and enterprises have several existing control mechanisms for the GitHub MCP server on GitHub.com:
+- MCP servers in Copilot Policy
+- Copilot Editor Preview Policy (temporary)
+- OAuth App Access Policies
+- GitHub App Installation
+- Personal Access Token (PAT) policies
+- SSO Enforcement
+
+This document outlines how these policies apply to different deployment modes, authentication methods, and host applications – while providing guidance for managing GitHub MCP Server access across your organization.
+
+## How the GitHub MCP Server Works
+
+The GitHub MCP Server provides access to GitHub resources and capabilities through a standardized protocol, with flexible deployment and authentication options tailored to different use cases. It supports two deployment modes, both built on the same underlying codebase.
+
+### 1. Local GitHub MCP Server
+* **Runs:** Locally alongside your IDE or application
+* **Authentication & Controls:** Requires Personal Access Tokens (PATs). Users must generate and configure a PAT to connect. Managed via [PAT policies](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens).
+  * Can optionally use GitHub App installation tokens when embedded in a GitHub App-based tool (rare).
+ 
+**Supported SKUs:** Can be used with GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud (GHEC).
+
+### 2. Remote GitHub MCP Server
+* **Runs:** As a hosted service accessed over the internet
+* **Authentication & Controls:** (determined by the chosen authentication method)
+  * **GitHub App Installation Tokens:** Uses a signed JWT to request installation access tokens (similar to the OAuth 2.0 client credentials flow) to operate as the application itself. Provides granular control via [installation](https://docs.github.com/apps/using-github-apps/installing-a-github-app-from-a-third-party#requirements-to-install-a-github-app), [permissions](https://docs.github.com/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app) and [repository access controls](https://docs.github.com/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#modifying-repository-access).
+  * **OAuth Authorization Code Flow:** Uses the standard OAuth 2.0 Authorization Code flow. Controlled via [OAuth App access policies](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) for OAuth apps. For GitHub Apps that sign in ([are authorized by](https://docs.github.com/apps/using-github-apps/authorizing-github-apps)) a user, control access to your organization via [installation](https://docs.github.com/apps/using-github-apps/installing-a-github-app-from-a-third-party#requirements-to-install-a-github-app).
+  * **Personal Access Tokens (PATs):** Managed via [PAT policies](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens).
+  * **SSO enforcement:** Applies when using OAuth Apps, GitHub Apps, and PATs to access resources in organizations and enterprises with SSO enabled. Acts as an overlay control. Users must have a valid SSO session for your organization or enterprise when signing into the app or creating the token in order for the token to access your resources. Learn more in the [SSO documentation](https://docs.github.com/enterprise-cloud@latest/authentication/authenticating-with-single-sign-on/about-authentication-with-single-sign-on#about-oauth-apps-github-apps-and-sso).
+
+**Supported Platforms:** Currently available only on GitHub Enterprise Cloud (GHEC). Remote hosting for GHES is not supported at this time.
+
+> **Note:** This does not apply to the Local GitHub MCP Server, which uses PATs and does not rely on GitHub App installations.
+
+#### Enterprise Install Considerations
+
+- When using the Remote GitHub MCP Server, if authenticating with OAuth instead of PAT, each host application must have a registered GitHub App (or OAuth App) to authenticate on behalf of the user.
+- Enterprises may choose to install these apps in multiple organizations (e.g., per team or department) to scope access narrowly, or at the enterprise level to centralize access control across all child organizations. 
+- Enterprise installation is only supported for GitHub Apps. OAuth Apps can only be installed on a per organization basis in multi-org enterprises.
+
+### Security Principles for Both Modes
+* **Authentication:** Required for all operations, no anonymous access
+* **Authorization:** Access enforced by GitHub's native permission model. Users and apps cannot use an MCP server to access more resources than they could otherwise access normally via the API.
+* **Communication:** All data transmitted over HTTPS with optional SSE for real-time updates
+* **Rate Limiting:** Subject to GitHub API rate limits based on authentication method
+* **Token Storage:** Tokens should be stored securely using platform-appropriate credential storage
+* **Audit Trail:** All underlying API calls are logged in GitHub's audit log when available
+
+For integration architecture and implementation details, see the [Host Integration Guide](https://github.com/github/github-mcp-server/blob/main/docs/host-integration.md).
+
+## Where It's Used
+
+The GitHub MCP server can be accessed in various environments (referred to as "host" applications):
+* **First-party Hosts:** GitHub Copilot in VS Code, Visual Studio, JetBrains, Eclipse, and Xcode with integrated MCP support, as well as Copilot Coding Agent.
+* **Third-party Hosts:** Editors outside the GitHub ecosystem, such as Claude, Cursor, Windsurf, and Cline, that support connecting to MCP servers, as well as AI chat applications like Claude Desktop and other AI assistants that connect to MCP servers to fetch GitHub context or execute write actions.
+
+## What It Can Access
+
+The MCP server accesses GitHub resources based on the permissions granted through the chosen authentication method (PAT, OAuth, or GitHub App). These may include:
+* Repository contents (files, branches, commits)
+* Issues and pull requests
+* Organization and team metadata
+* User profile information
+* Actions workflow runs, logs, and statuses
+* Security and vulnerability alerts (if explicitly granted)
+
+Access is always constrained by GitHub's public API permission model and the authenticated user's privileges.
+
+## Control Mechanisms
+
+### 1. Copilot Editors (first-party) → MCP Servers in Copilot Policy
+
+* **Policy:** MCP servers in Copilot
+* **Location:** Enterprise/Org → Policies → Copilot
+* **What it controls:** When disabled, **completely blocks all GitHub MCP Server access** (both remote and local) for affected Copilot editors. Currently applies to VS Code and Copilot Coding Agent, with more Copilot editors expected to migrate to this policy over time.
+* **Impact when disabled:** Host applications governed by this policy cannot connect to the GitHub MCP Server through any authentication method (OAuth, PAT, or GitHub App).
+* **What it does NOT affect:**
+  * MCP support in Copilot on IDEs that are still in public preview (Visual Studio, JetBrains, Xcode, Eclipse)
+  * Third-party IDE or host apps (like Claude, Cursor, Windsurf) not governed by GitHub's Copilot policies
+  * Community-authored MCP servers using GitHub's public APIs
+
+> **Important:** This policy provides comprehensive control over GitHub MCP Server access in Copilot editors. When disabled, users in affected applications will not be able to use the GitHub MCP Server regardless of deployment mode (remote or local) or authentication method.
+
+#### Temporary: Copilot Editor Preview Policy
+
+* **Policy:** Editor Preview Features  
+* **Status:** Being phased out as editors migrate to the "MCP servers in Copilot" policy above, and once the Remote GitHub MCP server goes GA
+* **What it controls:** When disabled, prevents remaining Copilot editors from using the Remote GitHub MCP Server through OAuth connections in all first-party and third-party host applications (does not affect local deployments or PAT authentication)
+
+> **Note:** As Copilot editors migrate from the "Copilot Editor Preview" policy to the "MCP servers in Copilot" policy, the scope of control becomes more centralized, blocking both remote and local GitHub MCP Server access when disabled. Access in third-party hosts is governed separately by OAuth App, GitHub App, and PAT policies.
+
+### 2. Third-Party Host Apps (e.g., Claude, Cursor, Windsurf) → OAuth App or GitHub App Controls
+
+#### a. OAuth App Access Policies
+* **Control Mechanism:** OAuth App access restrictions
+* **Location:** Org → Settings → Third-party Access → OAuth app policy
+* **How it works:**
+  * Organization admins must approve OAuth App requests before host apps can access organization data
+  * Only applies when the host registers an OAuth App AND the user connects via OAuth 2.0 flow
+
+#### b. GitHub App Installation
+* **Control Mechanism:** GitHub App installation and permissions
+* **Location:** Org → Settings → Third-party Access → GitHub Apps
+* **What it controls:** Organization admins must install the app, select repositories, and grant permissions before the app can access organization-owned data or resources through the Remote GitHub Server.
+* **How it works:**
+  * Organization admins must install the app, specify repositories, and approve permissions
+  * Only applies when the host registers a GitHub App AND the user authenticates through that flow
+
+> **Note:** The authentication methods available depend on what your host application supports. While PATs work with any remote MCP-compatible host, OAuth and GitHub App authentication are only available if the host has registered an app with GitHub. Check your host application's documentation or support for more info.
+
+### 3. PAT Access from Any Host → PAT Restrictions
+
+* **Types:** Fine-grained PATs (recommended) and Classic tokens (legacy)
+* **Location:**
+  * User level: [Personal Settings → Developer Settings → Personal Access Tokens](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens)
+  * Enterprise/Organization level: [Enterprise/Organization → Settings → Personal Access Tokens](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) (to control PAT creation/access policies)
+* **What it controls:** Applies to all host apps and both local & remote GitHub MCP servers when users authenticate via PAT.
+* **How it works:** Access limited to the repositories and scopes selected on the token.
+* **Limitations:** PATs do not adhere to OAuth App policies and GitHub App installation controls. They are user-scoped and not recommended for production automation.
+* **Organization controls:**
+  * Classic PATs: Can be completely disabled organization-wide
+  * Fine-grained PATs: Cannot be disabled but require explicit approval for organization access
+
+> **Recommendation:** We recommend using fine-grained PATs over classic tokens. Classic tokens have broader scopes and can be disabled in organization settings.
+
+### 4. SSO Enforcement (overlay control)
+
+* **Location:** Enterprise/Organization → SSO settings
+* **What it controls:** OAuth tokens and PATs must map to a recent SSO login to access SSO-protected organization data.
+* **How it works:** Applies to ALL host apps when using OAuth or PATs.
+
+> **Exception:** Does NOT apply to GitHub App installation tokens (these are installation-scoped, not user-scoped)
+
+## Current Limitations
+
+While the GitHub MCP Server provides dynamic tooling and capabilities, the following enterprise governance features are not yet available:
+
+### Single Enterprise/Organization-Level Toggle
+
+GitHub does not provide a single toggle that blocks all GitHub MCP server traffic for every user. Admins can achieve equivalent coverage by combining the controls shown here:
+* **First-party Copilot Editors (GitHub Copilot in VS Code, Visual Studio, JetBrains, Eclipse):**
+  * Disable the "MCP servers in Copilot" policy for comprehensive control
+  * Or disable the Editor Preview Features policy (for editors still using the legacy policy)
+* **Third-party Host Applications:**
+  * Configure OAuth app restrictions
+  * Manage GitHub App installations
+* **PAT Access in All Host Applications:**
+  * Implement fine-grained PAT policies (applies to both remote and local deployments)
+
+### MCP-Specific Audit Logging
+
+At present, MCP traffic appears in standard GitHub audit logs as normal API calls. Purpose-built logging for MCP is on the roadmap, but the following views are not yet available:
+* Real-time list of active MCP connections
+* Dashboards showing granular MCP usage data, like tools or host apps
+* Granular, action-by-action audit logs
+
+Until those arrive, teams can continue to monitor MCP activity through existing API log entries and OAuth/GitHub App events.
+
+## Security Best Practices
+
+### For Organizations
+
+**GitHub App Management**
+* Review [GitHub App installations](https://docs.github.com/apps/using-github-apps/reviewing-and-modifying-installed-github-apps) regularly
+* Audit permissions and repository access
+* Monitor installation events in audit logs
+* Document approved GitHub Apps and their business purposes
+
+**OAuth App Governance**
+* Manage [OAuth App access policies](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions)
+* Establish review processes for approved applications
+* Monitor which third-party applications are requesting access
+* Maintain an allowlist of approved OAuth applications
+
+**Token Management**
+* Mandate fine-grained Personal Access Tokens over classic tokens
+* Establish token expiration policies (90 days maximum recommended)
+* Implement automated token rotation reminders
+* Review and enforce [PAT restrictions](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) at the appropriate level
+
+### For Developers and Users
+
+**Authentication Security**
+* Prioritize OAuth 2.0 flows over long-lived tokens
+* Prefer fine-grained PATs to PATs (Classic)
+* Store tokens securely using platform-appropriate credential management
+* Store credentials in secret management systems, not source code
+
+**Scope Minimization**
+* Request only the minimum required scopes for your use case
+* Regularly review and revoke unused token permissions
+* Use repository-specific access instead of organization-wide access
+* Document why each permission is needed for your integration
+
+## Resources
+
+**MCP:**
+* [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/2025-03-26)
+* [Model Context Protocol Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization)
+
+**GitHub Governance & Controls:**
+* [Managing OAuth App Access](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions)
+* [GitHub App Permissions](https://docs.github.com/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)
+* [Updating permissions for a GitHub App](https://docs.github.com/apps/using-github-apps/approving-updated-permissions-for-a-github-app)
+* [PAT Policies](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization)
+* [Fine-grained PATs](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens)
+* [Setting a PAT policy for your organization](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions)
+
+---
+
+**Questions or Feedback?**
+
+Open an [issue in the github-mcp-server repository](https://github.com/github/github-mcp-server/issues) with the label "policies & governance" attached.
+
+This document reflects GitHub MCP Server policies as of July 2025. Policies and capabilities continue to evolve based on customer feedback and security best practices.

From b5e33481793a6dbca5cf688ddf391ad410042d63 Mon Sep 17 00:00:00 2001
From: Lulu <59149422+LuluBeatson@users.noreply.github.com>
Date: Fri, 18 Jul 2025 10:57:05 +0100
Subject: [PATCH 24/32] fix: shorten long tool name for adding pr review
 comments (#697)

* shorten tool name

* update function name to match tool name

* adjust wording of descriptions
---
 README.md                                            |  2 +-
 e2e/e2e_test.go                                      | 12 ++++++------
 ...eview.snap => add_comment_to_pending_review.snap} |  6 +++---
 pkg/github/pullrequests.go                           | 10 +++++-----
 pkg/github/pullrequests_test.go                      |  6 +++---
 pkg/github/tools.go                                  |  2 +-
 6 files changed, 19 insertions(+), 19 deletions(-)
 rename pkg/github/__toolsnaps__/{add_pull_request_review_comment_to_pending_review.snap => add_comment_to_pending_review.snap} (85%)

diff --git a/README.md b/README.md
index 7a6860262..e0ebe0f72 100644
--- a/README.md
+++ b/README.md
@@ -589,7 +589,7 @@ The following sets of tools are available (all are on by default):
 
 <summary>Pull Requests</summary>
 
-- **add_pull_request_review_comment_to_pending_review** - Add comment to the requester's latest pending pull request review
+- **add_comment_to_pending_review** - Add review comment to the requester's latest pending pull request review
   - `body`: The text of the review comment (string, required)
   - `line`: The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range (number, optional)
   - `owner`: Repository owner (string, required)
diff --git a/e2e/e2e_test.go b/e2e/e2e_test.go
index d46e8de8b..64c5729ba 100644
--- a/e2e/e2e_test.go
+++ b/e2e/e2e_test.go
@@ -1338,7 +1338,7 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) {
 
 	// Add a file review comment
 	addFileReviewCommentRequest := mcp.CallToolRequest{}
-	addFileReviewCommentRequest.Params.Name = "add_pull_request_review_comment_to_pending_review"
+	addFileReviewCommentRequest.Params.Name = "add_comment_to_pending_review"
 	addFileReviewCommentRequest.Params.Arguments = map[string]any{
 		"owner":       currentOwner,
 		"repo":        repoName,
@@ -1350,12 +1350,12 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) {
 
 	t.Logf("Adding file review comment to pull request in %s/%s...", currentOwner, repoName)
 	resp, err = mcpClient.CallTool(ctx, addFileReviewCommentRequest)
-	require.NoError(t, err, "expected to call 'add_pull_request_review_comment_to_pending_review' tool successfully")
+	require.NoError(t, err, "expected to call 'add_comment_to_pending_review' tool successfully")
 	require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp))
 
 	// Add a single line review comment
 	addSingleLineReviewCommentRequest := mcp.CallToolRequest{}
-	addSingleLineReviewCommentRequest.Params.Name = "add_pull_request_review_comment_to_pending_review"
+	addSingleLineReviewCommentRequest.Params.Name = "add_comment_to_pending_review"
 	addSingleLineReviewCommentRequest.Params.Arguments = map[string]any{
 		"owner":       currentOwner,
 		"repo":        repoName,
@@ -1370,12 +1370,12 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) {
 
 	t.Logf("Adding single line review comment to pull request in %s/%s...", currentOwner, repoName)
 	resp, err = mcpClient.CallTool(ctx, addSingleLineReviewCommentRequest)
-	require.NoError(t, err, "expected to call 'add_pull_request_review_comment_to_pending_review' tool successfully")
+	require.NoError(t, err, "expected to call 'add_comment_to_pending_review' tool successfully")
 	require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp))
 
 	// Add a multiline review comment
 	addMultilineReviewCommentRequest := mcp.CallToolRequest{}
-	addMultilineReviewCommentRequest.Params.Name = "add_pull_request_review_comment_to_pending_review"
+	addMultilineReviewCommentRequest.Params.Name = "add_comment_to_pending_review"
 	addMultilineReviewCommentRequest.Params.Arguments = map[string]any{
 		"owner":       currentOwner,
 		"repo":        repoName,
@@ -1392,7 +1392,7 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) {
 
 	t.Logf("Adding multi line review comment to pull request in %s/%s...", currentOwner, repoName)
 	resp, err = mcpClient.CallTool(ctx, addMultilineReviewCommentRequest)
-	require.NoError(t, err, "expected to call 'add_pull_request_review_comment_to_pending_review' tool successfully")
+	require.NoError(t, err, "expected to call 'add_comment_to_pending_review' tool successfully")
 	require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp))
 
 	// Submit the review
diff --git a/pkg/github/__toolsnaps__/add_pull_request_review_comment_to_pending_review.snap b/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap
similarity index 85%
rename from pkg/github/__toolsnaps__/add_pull_request_review_comment_to_pending_review.snap
rename to pkg/github/__toolsnaps__/add_comment_to_pending_review.snap
index 454b9d0ba..08fa42df5 100644
--- a/pkg/github/__toolsnaps__/add_pull_request_review_comment_to_pending_review.snap
+++ b/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap
@@ -1,9 +1,9 @@
 {
   "annotations": {
-    "title": "Add comment to the requester's latest pending pull request review",
+    "title": "Add review comment to the requester's latest pending pull request review",
     "readOnlyHint": false
   },
-  "description": "Add a comment to the requester's latest pending pull request review, a pending review needs to already exist to call this (check with the user if not sure).",
+  "description": "Add review comment to the requester's latest pending pull request review. A pending review needs to already exist to call this (check with the user if not sure).",
   "inputSchema": {
     "properties": {
       "body": {
@@ -69,5 +69,5 @@
     ],
     "type": "object"
   },
-  "name": "add_pull_request_review_comment_to_pending_review"
+  "name": "add_comment_to_pending_review"
 }
\ No newline at end of file
diff --git a/pkg/github/pullrequests.go b/pkg/github/pullrequests.go
index aeca650fa..d98dc334d 100644
--- a/pkg/github/pullrequests.go
+++ b/pkg/github/pullrequests.go
@@ -1151,12 +1151,12 @@ func CreatePendingPullRequestReview(getGQLClient GetGQLClientFn, t translations.
 		}
 }
 
-// AddPullRequestReviewCommentToPendingReview creates a tool to add a comment to a pull request review.
-func AddPullRequestReviewCommentToPendingReview(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) {
-	return mcp.NewTool("add_pull_request_review_comment_to_pending_review",
-			mcp.WithDescription(t("TOOL_ADD_PULL_REQUEST_REVIEW_COMMENT_TO_PENDING_REVIEW_DESCRIPTION", "Add a comment to the requester's latest pending pull request review, a pending review needs to already exist to call this (check with the user if not sure).")),
+// AddCommentToPendingReview creates a tool to add a comment to a pull request review.
+func AddCommentToPendingReview(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) {
+	return mcp.NewTool("add_comment_to_pending_review",
+			mcp.WithDescription(t("TOOL_ADD_COMMENT_TO_PENDING_REVIEW_DESCRIPTION", "Add review comment to the requester's latest pending pull request review. A pending review needs to already exist to call this (check with the user if not sure).")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
-				Title:        t("TOOL_ADD_PULL_REQUEST_REVIEW_COMMENT_TO_PENDING_REVIEW_USER_TITLE", "Add comment to the requester's latest pending pull request review"),
+				Title:        t("TOOL_ADD_COMMENT_TO_PENDING_REVIEW_USER_TITLE", "Add review comment to the requester's latest pending pull request review"),
 				ReadOnlyHint: ToBoolPtr(false),
 			}),
 			// Ideally, for performance sake this would just accept the pullRequestReviewID. However, we would need to
diff --git a/pkg/github/pullrequests_test.go b/pkg/github/pullrequests_test.go
index e39315232..42fd5bf03 100644
--- a/pkg/github/pullrequests_test.go
+++ b/pkg/github/pullrequests_test.go
@@ -2137,10 +2137,10 @@ func TestAddPullRequestReviewCommentToPendingReview(t *testing.T) {
 
 	// Verify tool definition once
 	mockClient := githubv4.NewClient(nil)
-	tool, _ := AddPullRequestReviewCommentToPendingReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper)
+	tool, _ := AddCommentToPendingReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper)
 	require.NoError(t, toolsnaps.Test(tool.Name, tool))
 
-	assert.Equal(t, "add_pull_request_review_comment_to_pending_review", tool.Name)
+	assert.Equal(t, "add_comment_to_pending_review", tool.Name)
 	assert.NotEmpty(t, tool.Description)
 	assert.Contains(t, tool.InputSchema.Properties, "owner")
 	assert.Contains(t, tool.InputSchema.Properties, "repo")
@@ -2222,7 +2222,7 @@ func TestAddPullRequestReviewCommentToPendingReview(t *testing.T) {
 
 			// Setup client with mock
 			client := githubv4.NewClient(tc.mockedClient)
-			_, handler := AddPullRequestReviewCommentToPendingReview(stubGetGQLClientFn(client), translations.NullTranslationHelper)
+			_, handler := AddCommentToPendingReview(stubGetGQLClientFn(client), translations.NullTranslationHelper)
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)
diff --git a/pkg/github/tools.go b/pkg/github/tools.go
index 77a1ccd3b..bd349171d 100644
--- a/pkg/github/tools.go
+++ b/pkg/github/tools.go
@@ -89,7 +89,7 @@ func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetG
 			// Reviews
 			toolsets.NewServerTool(CreateAndSubmitPullRequestReview(getGQLClient, t)),
 			toolsets.NewServerTool(CreatePendingPullRequestReview(getGQLClient, t)),
-			toolsets.NewServerTool(AddPullRequestReviewCommentToPendingReview(getGQLClient, t)),
+			toolsets.NewServerTool(AddCommentToPendingReview(getGQLClient, t)),
 			toolsets.NewServerTool(SubmitPendingPullRequestReview(getGQLClient, t)),
 			toolsets.NewServerTool(DeletePendingPullRequestReview(getGQLClient, t)),
 		)

From 2e63e81d515c47fdb2da78654745128b32aa0c88 Mon Sep 17 00:00:00 2001
From: Dimitrios Philliou <d1m1tr10s@github.com>
Date: Sat, 19 Jul 2025 00:17:24 -0700
Subject: [PATCH 25/32] Update installation guide for GitHub MCP Server (#699)

* Update installation guide for GitHub MCP Server

Removed reference to GitHub.com in the installation guide. The GitHub server is available to Coding Agent by default, without installation needed.

* Rename section to 'Install in Other MCP Hosts'

Updating title for consistency and adding a link to the "other Copilot IDEs" install guide.

* Revise installation guide for Cursor MCP setup

Updated installation guide for Cursor with steps clarified, remote server installation, and one-click install deeplinks to open Cursor and add the github server to the config file.
---
 README.md                                     |  3 +-
 docs/installation-guides/install-cursor.md    | 82 ++++++++-----------
 .../install-other-copilot-ides.md             |  2 +-
 3 files changed, 36 insertions(+), 51 deletions(-)

diff --git a/README.md b/README.md
index e0ebe0f72..ae4d3627e 100644
--- a/README.md
+++ b/README.md
@@ -234,10 +234,11 @@ Optionally, you can add a similar example (i.e. without the mcp key) to a file c
 
 </details>
 
-### Install in Other Host Applications
+### Install in Other MCP Hosts
 
 For other MCP host applications, please refer to our installation guides:
 
+- **[GitHub Copilot in other IDEs](/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot
 - **[Claude Code & Claude Desktop](docs/installation-guides/install-claude.md)** - Installation guide for Claude Code and Claude Desktop
 - **[Cursor](docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE  
 - **[Windsurf](docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE
diff --git a/docs/installation-guides/install-cursor.md b/docs/installation-guides/install-cursor.md
index 82b36c3e6..b069addd3 100644
--- a/docs/installation-guides/install-cursor.md
+++ b/docs/installation-guides/install-cursor.md
@@ -7,10 +7,18 @@
 
 ## Remote Server Setup (Recommended)
 
-The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP protocol. Cursor currently supports remote servers with PAT authentication.
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=github&config=eyJ1cmwiOiJodHRwczovL2FwaS5naXRodWJjb3BpbG90LmNvbS9tY3AvIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfR0lUSFVCX1BBVCJ9LCJ0eXBlIjoiaHR0cCJ9)
+
+Uses GitHub's hosted server at https://api.githubcopilot.com/mcp/. Requires Cursor v0.48.0+ for Streamable HTTP support. While Cursor supports OAuth for some MCP servers, the GitHub server currently requires a Personal Access Token.
+
+### Install steps
+1. Click the install button above and follow the flow, or go directly to your global MCP configuration file at `~/.cursor/mcp.json` and enter the code block below
+2. In Tools & Integrations > MCP tools, click the pencil icon next to "github"
+3. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens)
+4. Save the file
+5. Restart Cursor
 
 ### Streamable HTTP Configuration
-As of Cursor v0.48.0, Cursor supports Streamable HTTP servers directly:
 
 ```json
 {
@@ -25,12 +33,20 @@ As of Cursor v0.48.0, Cursor supports Streamable HTTP servers directly:
 }
 ```
 
-**Note**: You may need to update to the latest version, if the current version doesn't support direct Streamable HTTP
-
 ## Local Server Setup
 
-### Docker Installation (Required)
-> **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=github&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCItZSIsIkdJVEhVQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU4iLCJnaGNyLmlvL2dpdGh1Yi9naXRodWItbWNwLXNlcnZlciJdLCJlbnYiOnsiR0lUSFVCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IllPVVJfR0lUSFVCX1BHVCJ9fQ==)
+
+The local GitHub MCP server runs via Docker and requires Docker Desktop to be installed and running.
+
+### Install steps
+1. Click the install button above and follow the flow, or go directly to your global MCP configuration file at `~/.cursor/mcp.json` and enter the code block below
+2. In Tools & Integrations > MCP tools, click the pencil icon next to "github"
+3. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens)
+4. Save the file
+5. Restart Cursor
+
+### Docker Configuration
 
 ```json
 {
@@ -53,50 +69,18 @@ As of Cursor v0.48.0, Cursor supports Streamable HTTP servers directly:
 }
 ```
 
-## Installation Steps
-
-### Via Cursor Settings UI
-1. Open Cursor
-2. Navigate to **Settings** → **Tools & Integrations** → **MCP**
-3. Click **"+ Add new global MCP server"**
-4. This opens `~/.cursor/mcp.json` in the editor
-5. Add your chosen configuration from above
-6. Save the file
-7. Restart Cursor
-
-### Manual Configuration
-1. Create or edit the configuration file:
-   - **Global (all projects)**: `~/.cursor/mcp.json`
-   - **Project-specific**: `.cursor/mcp.json` in project root
-2. Add your chosen configuration
-3. Save the file
-4. Restart Cursor completely
-
-### Token Security
-- Create PATs with minimum required scopes:
-  - `repo` - For repository operations
-  - `read:packages` - For Docker image pull (local setup)
-  - Additional scopes based on tools you need
-- Use separate PATs for different projects
-- Regularly rotate tokens
-- Never commit configuration files to version control
-
-## Configuration Details
-
-- **File paths**: 
-  - Global: `~/.cursor/mcp.json`
-  - Project: `.cursor/mcp.json`
-- **Scope**: Both global and project-specific configurations supported
-- **Format**: Must be valid JSON (use a linter to verify)
-
-## Verification
-
-After installation:
+> **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead.
+
+## Configuration Files
+
+- **Global (all projects)**: `~/.cursor/mcp.json`
+- **Project-specific**: `.cursor/mcp.json` in project root
+
+## Verify Installation
 1. Restart Cursor completely
-2. Open Settings → Tools & Integrations → MCP
-3. Look for green dot next to your server name
-4. In chat/composer, check "Available Tools"
-5. Test with: "List my GitHub repositories"
+2. Check for green dot in Settings → Tools & Integrations → MCP Tools
+3. In chat/composer, check "Available Tools"
+4. Test with: "List my GitHub repositories"
 
 ## Troubleshooting
 
diff --git a/docs/installation-guides/install-other-copilot-ides.md b/docs/installation-guides/install-other-copilot-ides.md
index 18ffdd84a..38b48bbbd 100644
--- a/docs/installation-guides/install-other-copilot-ides.md
+++ b/docs/installation-guides/install-other-copilot-ides.md
@@ -1,4 +1,4 @@
-# Install GitHub MCP Server in Copilot IDEs & GitHub.com
+# Install GitHub MCP Server in Copilot IDEs
 
 Quick setup guide for the GitHub MCP server in GitHub Copilot across different IDEs. For VS Code instructions, refer to the [VS Code install guide in the README](/README.md#installation-in-vs-code)
 

From a031e21503d534a1dddc745c9073e7fe30fb5a62 Mon Sep 17 00:00:00 2001
From: bitsark <54836727+bitsark@users.noreply.github.com>
Date: Mon, 21 Jul 2025 17:20:32 +0800
Subject: [PATCH 26/32] fix: make mcpcurl support "integer" type (#688)

- FYI:https://json-schema.org/understanding-json-schema/reference/numeric#integer
---
 cmd/mcpcurl/main.go | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/cmd/mcpcurl/main.go b/cmd/mcpcurl/main.go
index bc192587a..17b4bc77c 100644
--- a/cmd/mcpcurl/main.go
+++ b/cmd/mcpcurl/main.go
@@ -280,6 +280,8 @@ func addCommandFromTool(toolsCmd *cobra.Command, tool *Tool, prettyPrint bool) {
 			}
 		case "number":
 			cmd.Flags().Float64(name, 0, description)
+		case "integer":
+			cmd.Flags().Int64(name, 0, description)
 		case "boolean":
 			cmd.Flags().Bool(name, false, description)
 		case "array":
@@ -319,6 +321,10 @@ func buildArgumentsMap(cmd *cobra.Command, tool *Tool) (map[string]interface{},
 			if value, _ := cmd.Flags().GetFloat64(name); value != 0 {
 				arguments[name] = value
 			}
+		case "integer":
+			if value, _ := cmd.Flags().GetInt64(name); value != 0 {
+				arguments[name] = value
+			}
 		case "boolean":
 			// For boolean, we need to check if it was explicitly set
 			if cmd.Flags().Changed(name) {

From 74964520cf15aae32400119762a9d4482eda0333 Mon Sep 17 00:00:00 2001
From: Bupal Chowdary <136565586+Bupalchow@users.noreply.github.com>
Date: Mon, 21 Jul 2025 17:09:36 +0530
Subject: [PATCH 27/32] Added installation instructions for mcpcurl (#719)

* Added installation instructions for mcpcurl

* Update cmd/mcpcurl/README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 cmd/mcpcurl/README.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/cmd/mcpcurl/README.md b/cmd/mcpcurl/README.md
index 317c2b8e5..717ea207f 100644
--- a/cmd/mcpcurl/README.md
+++ b/cmd/mcpcurl/README.md
@@ -15,6 +15,26 @@ be executed against the configured MCP server.
 
 ## Installation
 
+### Prerequisites
+- Go 1.21 or later
+- Access to the GitHub MCP Server from either Docker or local build
+
+### Build from Source
+```bash
+cd cmd/mcpcurl
+go build -o mcpcurl
+```
+
+### Using Go Install
+```bash
+go install github.com/github/github-mcp-server/cmd/mcpcurl@latest
+```
+
+### Verify Installation
+```bash
+./mcpcurl --help
+```
+
 ## Usage
 
 ```console

From 7ccc6b6493f184c6fce8620c41ed1ffda12837b8 Mon Sep 17 00:00:00 2001
From: Matt Holloway <mattdholloway@github.com>
Date: Mon, 21 Jul 2025 16:31:29 +0100
Subject: [PATCH 28/32] Add pagination support to GraphQL-based tools (#683)

* initial pagination for `ListDiscussions`

* redo category id var cast

* add GraphQL pagination support for discussion comments and categories

* remove pageinfo returns

* fix out ref for linter

* update docs

* move to unified pagination for consensus on params

* update docs

* refactor pagination handling

* update docs

* linter fix

* conv rest to gql params for safe lint

* add nolint

* add error handling for perPage value in ToGraphQLParams

* refactor pagination error handling

* unified params for rest andn graphql and rennamed to be uniform for golang

* add 'after' for pagination

* update docs

* Update pkg/github/discussions.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update pkg/github/discussions.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update pkg/github/discussions_test.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* update default page size const

* reduce default pagination size from 100 to 30 in discussion tests

* update pagination for reverse and total

* update pagination to remove from discussions

* updated README

* improve the `ToGraphQLParams` function

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 README.md                      |   8 +-
 pkg/github/actions.go          |  16 +--
 pkg/github/discussions.go      | 202 ++++++++++++++++++++++-------
 pkg/github/discussions_test.go | 225 ++++++++++++++++++---------------
 pkg/github/issues.go           |   4 +-
 pkg/github/notifications.go    |   4 +-
 pkg/github/pullrequests.go     |   8 +-
 pkg/github/repositories.go     |  16 +--
 pkg/github/search.go           |  12 +-
 pkg/github/search_utils.go     |   4 +-
 pkg/github/server.go           | 116 +++++++++++++++--
 pkg/github/server_test.go      |  16 +--
 12 files changed, 430 insertions(+), 201 deletions(-)

diff --git a/README.md b/README.md
index ae4d3627e..c06142b76 100644
--- a/README.md
+++ b/README.md
@@ -449,21 +449,21 @@ The following sets of tools are available (all are on by default):
   - `repo`: Repository name (string, required)
 
 - **get_discussion_comments** - Get discussion comments
+  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
   - `discussionNumber`: Discussion Number (number, required)
   - `owner`: Repository owner (string, required)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
 
 - **list_discussion_categories** - List discussion categories
-  - `after`: Cursor for pagination, use the 'after' field from the previous response (string, optional)
-  - `before`: Cursor for pagination, use the 'before' field from the previous response (string, optional)
-  - `first`: Number of categories to return per page (min 1, max 100) (number, optional)
-  - `last`: Number of categories to return from the end (min 1, max 100) (number, optional)
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
 
 - **list_discussions** - List discussions
+  - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
   - `category`: Optional filter by discussion category ID. If provided, only discussions with this category are listed. (string, optional)
   - `owner`: Repository owner (string, required)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
 
 </details>
diff --git a/pkg/github/actions.go b/pkg/github/actions.go
index 3c441d5aa..19b56389c 100644
--- a/pkg/github/actions.go
+++ b/pkg/github/actions.go
@@ -62,8 +62,8 @@ func ListWorkflows(getClient GetClientFn, t translations.TranslationHelperFunc)
 
 			// Set up list options
 			opts := &github.ListOptions{
-				PerPage: pagination.perPage,
-				Page:    pagination.page,
+				PerPage: pagination.PerPage,
+				Page:    pagination.Page,
 			}
 
 			workflows, resp, err := client.Actions.ListWorkflows(ctx, owner, repo, opts)
@@ -200,8 +200,8 @@ func ListWorkflowRuns(getClient GetClientFn, t translations.TranslationHelperFun
 				Event:  event,
 				Status: status,
 				ListOptions: github.ListOptions{
-					PerPage: pagination.perPage,
-					Page:    pagination.page,
+					PerPage: pagination.PerPage,
+					Page:    pagination.Page,
 				},
 			}
 
@@ -503,8 +503,8 @@ func ListWorkflowJobs(getClient GetClientFn, t translations.TranslationHelperFun
 			opts := &github.ListWorkflowJobsOptions{
 				Filter: filter,
 				ListOptions: github.ListOptions{
-					PerPage: pagination.perPage,
-					Page:    pagination.page,
+					PerPage: pagination.PerPage,
+					Page:    pagination.Page,
 				},
 			}
 
@@ -1025,8 +1025,8 @@ func ListWorkflowRunArtifacts(getClient GetClientFn, t translations.TranslationH
 
 			// Set up list options
 			opts := &github.ListOptions{
-				PerPage: pagination.perPage,
-				Page:    pagination.page,
+				PerPage: pagination.PerPage,
+				Page:    pagination.Page,
 			}
 
 			artifacts, resp, err := client.Actions.ListWorkflowRunArtifacts(ctx, owner, repo, runID, opts)
diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go
index 23e2724d4..2b8ccfb0b 100644
--- a/pkg/github/discussions.go
+++ b/pkg/github/discussions.go
@@ -13,6 +13,8 @@ import (
 	"github.com/shurcooL/githubv4"
 )
 
+const DefaultGraphQLPageSize = 30
+
 func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_discussions",
 			mcp.WithDescription(t("TOOL_LIST_DISCUSSIONS_DESCRIPTION", "List discussions for a repository")),
@@ -31,6 +33,7 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 			mcp.WithString("category",
 				mcp.Description("Optional filter by discussion category ID. If provided, only discussions with this category are listed."),
 			),
+			WithCursorPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			// Required params
@@ -49,6 +52,16 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 
+			// Get pagination parameters and convert to GraphQL format
+			pagination, err := OptionalCursorPaginationParams(request)
+			if err != nil {
+				return nil, err
+			}
+			paginationParams, err := pagination.ToGraphQLParams()
+			if err != nil {
+				return nil, err
+			}
+
 			client, err := getGQLClient(ctx)
 			if err != nil {
 				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
@@ -61,7 +74,8 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 				categoryID = &id
 			}
 
-			// Now execute the discussions query
+			var out []byte
+
 			var discussions []*github.Discussion
 			if categoryID != nil {
 				// Query with category filter (server-side filtering)
@@ -77,13 +91,26 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 								} `graphql:"category"`
 								URL githubv4.String `graphql:"url"`
 							}
-						} `graphql:"discussions(first: 100, categoryId: $categoryId)"`
+							PageInfo struct {
+								HasNextPage     bool
+								HasPreviousPage bool
+								StartCursor     string
+								EndCursor       string
+							}
+							TotalCount int
+						} `graphql:"discussions(first: $first, after: $after, categoryId: $categoryId)"`
 					} `graphql:"repository(owner: $owner, name: $repo)"`
 				}
 				vars := map[string]interface{}{
 					"owner":      githubv4.String(owner),
 					"repo":       githubv4.String(repo),
 					"categoryId": *categoryID,
+					"first":      githubv4.Int(*paginationParams.First),
+				}
+				if paginationParams.After != nil {
+					vars["after"] = githubv4.String(*paginationParams.After)
+				} else {
+					vars["after"] = (*githubv4.String)(nil)
 				}
 				if err := client.Query(ctx, &query, vars); err != nil {
 					return mcp.NewToolResultError(err.Error()), nil
@@ -102,6 +129,23 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 					}
 					discussions = append(discussions, di)
 				}
+
+				// Create response with pagination info
+				response := map[string]interface{}{
+					"discussions": discussions,
+					"pageInfo": map[string]interface{}{
+						"hasNextPage":     query.Repository.Discussions.PageInfo.HasNextPage,
+						"hasPreviousPage": query.Repository.Discussions.PageInfo.HasPreviousPage,
+						"startCursor":     query.Repository.Discussions.PageInfo.StartCursor,
+						"endCursor":       query.Repository.Discussions.PageInfo.EndCursor,
+					},
+					"totalCount": query.Repository.Discussions.TotalCount,
+				}
+
+				out, err = json.Marshal(response)
+				if err != nil {
+					return nil, fmt.Errorf("failed to marshal discussions: %w", err)
+				}
 			} else {
 				// Query without category filter
 				var query struct {
@@ -116,12 +160,25 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 								} `graphql:"category"`
 								URL githubv4.String `graphql:"url"`
 							}
-						} `graphql:"discussions(first: 100)"`
+							PageInfo struct {
+								HasNextPage     bool
+								HasPreviousPage bool
+								StartCursor     string
+								EndCursor       string
+							}
+							TotalCount int
+						} `graphql:"discussions(first: $first, after: $after)"`
 					} `graphql:"repository(owner: $owner, name: $repo)"`
 				}
 				vars := map[string]interface{}{
 					"owner": githubv4.String(owner),
 					"repo":  githubv4.String(repo),
+					"first": githubv4.Int(*paginationParams.First),
+				}
+				if paginationParams.After != nil {
+					vars["after"] = githubv4.String(*paginationParams.After)
+				} else {
+					vars["after"] = (*githubv4.String)(nil)
 				}
 				if err := client.Query(ctx, &query, vars); err != nil {
 					return mcp.NewToolResultError(err.Error()), nil
@@ -140,13 +197,25 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 					}
 					discussions = append(discussions, di)
 				}
-			}
 
-			// Marshal and return
-			out, err := json.Marshal(discussions)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal discussions: %w", err)
+				// Create response with pagination info
+				response := map[string]interface{}{
+					"discussions": discussions,
+					"pageInfo": map[string]interface{}{
+						"hasNextPage":     query.Repository.Discussions.PageInfo.HasNextPage,
+						"hasPreviousPage": query.Repository.Discussions.PageInfo.HasPreviousPage,
+						"startCursor":     query.Repository.Discussions.PageInfo.StartCursor,
+						"endCursor":       query.Repository.Discussions.PageInfo.EndCursor,
+					},
+					"totalCount": query.Repository.Discussions.TotalCount,
+				}
+
+				out, err = json.Marshal(response)
+				if err != nil {
+					return nil, fmt.Errorf("failed to marshal discussions: %w", err)
+				}
 			}
+
 			return mcp.NewToolResultText(string(out)), nil
 		}
 }
@@ -236,6 +305,7 @@ func GetDiscussionComments(getGQLClient GetGQLClientFn, t translations.Translati
 			mcp.WithString("owner", mcp.Required(), mcp.Description("Repository owner")),
 			mcp.WithString("repo", mcp.Required(), mcp.Description("Repository name")),
 			mcp.WithNumber("discussionNumber", mcp.Required(), mcp.Description("Discussion Number")),
+			WithCursorPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			// Decode params
@@ -248,6 +318,27 @@ func GetDiscussionComments(getGQLClient GetGQLClientFn, t translations.Translati
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 
+			// Get pagination parameters and convert to GraphQL format
+			pagination, err := OptionalCursorPaginationParams(request)
+			if err != nil {
+				return nil, err
+			}
+
+			// Check if pagination parameters were explicitly provided
+			_, perPageProvided := request.GetArguments()["perPage"]
+			paginationExplicit := perPageProvided
+
+			paginationParams, err := pagination.ToGraphQLParams()
+			if err != nil {
+				return nil, err
+			}
+
+			// Use default of 30 if pagination was not explicitly provided
+			if !paginationExplicit {
+				defaultFirst := int32(DefaultGraphQLPageSize)
+				paginationParams.First = &defaultFirst
+			}
+
 			client, err := getGQLClient(ctx)
 			if err != nil {
 				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
@@ -260,7 +351,14 @@ func GetDiscussionComments(getGQLClient GetGQLClientFn, t translations.Translati
 							Nodes []struct {
 								Body githubv4.String
 							}
-						} `graphql:"comments(first:100)"`
+							PageInfo struct {
+								HasNextPage     githubv4.Boolean
+								HasPreviousPage githubv4.Boolean
+								StartCursor     githubv4.String
+								EndCursor       githubv4.String
+							}
+							TotalCount int
+						} `graphql:"comments(first: $first, after: $after)"`
 					} `graphql:"discussion(number: $discussionNumber)"`
 				} `graphql:"repository(owner: $owner, name: $repo)"`
 			}
@@ -268,16 +366,35 @@ func GetDiscussionComments(getGQLClient GetGQLClientFn, t translations.Translati
 				"owner":            githubv4.String(params.Owner),
 				"repo":             githubv4.String(params.Repo),
 				"discussionNumber": githubv4.Int(params.DiscussionNumber),
+				"first":            githubv4.Int(*paginationParams.First),
+			}
+			if paginationParams.After != nil {
+				vars["after"] = githubv4.String(*paginationParams.After)
+			} else {
+				vars["after"] = (*githubv4.String)(nil)
 			}
 			if err := client.Query(ctx, &q, vars); err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
+
 			var comments []*github.IssueComment
 			for _, c := range q.Repository.Discussion.Comments.Nodes {
 				comments = append(comments, &github.IssueComment{Body: github.Ptr(string(c.Body))})
 			}
 
-			out, err := json.Marshal(comments)
+			// Create response with pagination info
+			response := map[string]interface{}{
+				"comments": comments,
+				"pageInfo": map[string]interface{}{
+					"hasNextPage":     q.Repository.Discussion.Comments.PageInfo.HasNextPage,
+					"hasPreviousPage": q.Repository.Discussion.Comments.PageInfo.HasPreviousPage,
+					"startCursor":     string(q.Repository.Discussion.Comments.PageInfo.StartCursor),
+					"endCursor":       string(q.Repository.Discussion.Comments.PageInfo.EndCursor),
+				},
+				"totalCount": q.Repository.Discussion.Comments.TotalCount,
+			}
+
+			out, err := json.Marshal(response)
 			if err != nil {
 				return nil, fmt.Errorf("failed to marshal comments: %w", err)
 			}
@@ -301,55 +418,22 @@ func ListDiscussionCategories(getGQLClient GetGQLClientFn, t translations.Transl
 				mcp.Required(),
 				mcp.Description("Repository name"),
 			),
-			mcp.WithNumber("first",
-				mcp.Description("Number of categories to return per page (min 1, max 100)"),
-				mcp.Min(1),
-				mcp.Max(100),
-			),
-			mcp.WithNumber("last",
-				mcp.Description("Number of categories to return from the end (min 1, max 100)"),
-				mcp.Min(1),
-				mcp.Max(100),
-			),
-			mcp.WithString("after",
-				mcp.Description("Cursor for pagination, use the 'after' field from the previous response"),
-			),
-			mcp.WithString("before",
-				mcp.Description("Cursor for pagination, use the 'before' field from the previous response"),
-			),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			// Decode params
 			var params struct {
-				Owner  string
-				Repo   string
-				First  int32
-				Last   int32
-				After  string
-				Before string
+				Owner string
+				Repo  string
 			}
 			if err := mapstructure.Decode(request.Params.Arguments, &params); err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 
-			// Validate pagination parameters
-			if params.First != 0 && params.Last != 0 {
-				return mcp.NewToolResultError("only one of 'first' or 'last' may be specified"), nil
-			}
-			if params.After != "" && params.Before != "" {
-				return mcp.NewToolResultError("only one of 'after' or 'before' may be specified"), nil
-			}
-			if params.After != "" && params.Last != 0 {
-				return mcp.NewToolResultError("'after' cannot be used with 'last'. Did you mean to use 'before' instead?"), nil
-			}
-			if params.Before != "" && params.First != 0 {
-				return mcp.NewToolResultError("'before' cannot be used with 'first'. Did you mean to use 'after' instead?"), nil
-			}
-
 			client, err := getGQLClient(ctx)
 			if err != nil {
 				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
 			}
+
 			var q struct {
 				Repository struct {
 					DiscussionCategories struct {
@@ -357,16 +441,25 @@ func ListDiscussionCategories(getGQLClient GetGQLClientFn, t translations.Transl
 							ID   githubv4.ID
 							Name githubv4.String
 						}
-					} `graphql:"discussionCategories(first: 100)"`
+						PageInfo struct {
+							HasNextPage     githubv4.Boolean
+							HasPreviousPage githubv4.Boolean
+							StartCursor     githubv4.String
+							EndCursor       githubv4.String
+						}
+						TotalCount int
+					} `graphql:"discussionCategories(first: $first)"`
 				} `graphql:"repository(owner: $owner, name: $repo)"`
 			}
 			vars := map[string]interface{}{
 				"owner": githubv4.String(params.Owner),
 				"repo":  githubv4.String(params.Repo),
+				"first": githubv4.Int(25),
 			}
 			if err := client.Query(ctx, &q, vars); err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
+
 			var categories []map[string]string
 			for _, c := range q.Repository.DiscussionCategories.Nodes {
 				categories = append(categories, map[string]string{
@@ -374,7 +467,20 @@ func ListDiscussionCategories(getGQLClient GetGQLClientFn, t translations.Transl
 					"name": string(c.Name),
 				})
 			}
-			out, err := json.Marshal(categories)
+
+			// Create response with pagination info
+			response := map[string]interface{}{
+				"categories": categories,
+				"pageInfo": map[string]interface{}{
+					"hasNextPage":     q.Repository.DiscussionCategories.PageInfo.HasNextPage,
+					"hasPreviousPage": q.Repository.DiscussionCategories.PageInfo.HasPreviousPage,
+					"startCursor":     string(q.Repository.DiscussionCategories.PageInfo.StartCursor),
+					"endCursor":       string(q.Repository.DiscussionCategories.PageInfo.EndCursor),
+				},
+				"totalCount": q.Repository.DiscussionCategories.TotalCount,
+			}
+
+			out, err := json.Marshal(response)
 			if err != nil {
 				return nil, fmt.Errorf("failed to marshal discussion categories: %w", err)
 			}
diff --git a/pkg/github/discussions_test.go b/pkg/github/discussions_test.go
index c6688a519..e2e3d99ed 100644
--- a/pkg/github/discussions_test.go
+++ b/pkg/github/discussions_test.go
@@ -27,12 +27,30 @@ var (
 	}
 	mockResponseListAll = githubv4mock.DataResponse(map[string]any{
 		"repository": map[string]any{
-			"discussions": map[string]any{"nodes": discussionsAll},
+			"discussions": map[string]any{
+				"nodes": discussionsAll,
+				"pageInfo": map[string]any{
+					"hasNextPage":     false,
+					"hasPreviousPage": false,
+					"startCursor":     "",
+					"endCursor":       "",
+				},
+				"totalCount": 3,
+			},
 		},
 	})
 	mockResponseListGeneral = githubv4mock.DataResponse(map[string]any{
 		"repository": map[string]any{
-			"discussions": map[string]any{"nodes": discussionsGeneral},
+			"discussions": map[string]any{
+				"nodes": discussionsGeneral,
+				"pageInfo": map[string]any{
+					"hasNextPage":     false,
+					"hasPreviousPage": false,
+					"startCursor":     "",
+					"endCursor":       "",
+				},
+				"totalCount": 2,
+			},
 		},
 	})
 	mockErrorRepoNotFound = githubv4mock.ErrorResponse("repository not found")
@@ -48,54 +66,32 @@ func Test_ListDiscussions(t *testing.T) {
 	assert.Contains(t, toolDef.InputSchema.Properties, "repo")
 	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo"})
 
-	// mock for the call to ListDiscussions without category filter
-	var qDiscussions struct {
-		Repository struct {
-			Discussions struct {
-				Nodes []struct {
-					Number    githubv4.Int
-					Title     githubv4.String
-					CreatedAt githubv4.DateTime
-					Category  struct {
-						Name githubv4.String
-					} `graphql:"category"`
-					URL githubv4.String `graphql:"url"`
-				}
-			} `graphql:"discussions(first: 100)"`
-		} `graphql:"repository(owner: $owner, name: $repo)"`
-	}
+	// Use exact string queries that match implementation output (from error messages)
+	qDiscussions := "query($after:String$first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after){nodes{number,title,createdAt,category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
 
-	// mock for the call to get discussions with category filter
-	var qDiscussionsFiltered struct {
-		Repository struct {
-			Discussions struct {
-				Nodes []struct {
-					Number    githubv4.Int
-					Title     githubv4.String
-					CreatedAt githubv4.DateTime
-					Category  struct {
-						Name githubv4.String
-					} `graphql:"category"`
-					URL githubv4.String `graphql:"url"`
-				}
-			} `graphql:"discussions(first: 100, categoryId: $categoryId)"`
-		} `graphql:"repository(owner: $owner, name: $repo)"`
-	}
+	qDiscussionsFiltered := "query($after:String$categoryId:ID!$first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after, categoryId: $categoryId){nodes{number,title,createdAt,category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
 
+	// Variables matching what GraphQL receives after JSON marshaling/unmarshaling
 	varsListAll := map[string]interface{}{
-		"owner": githubv4.String("owner"),
-		"repo":  githubv4.String("repo"),
+		"owner": "owner",
+		"repo":  "repo",
+		"first": float64(30),
+		"after": (*string)(nil),
 	}
 
 	varsRepoNotFound := map[string]interface{}{
-		"owner": githubv4.String("owner"),
-		"repo":  githubv4.String("nonexistent-repo"),
+		"owner": "owner",
+		"repo":  "nonexistent-repo",
+		"first": float64(30),
+		"after": (*string)(nil),
 	}
 
 	varsDiscussionsFiltered := map[string]interface{}{
-		"owner":      githubv4.String("owner"),
-		"repo":       githubv4.String("repo"),
-		"categoryId": githubv4.ID("DIC_kwDOABC123"),
+		"owner":      "owner",
+		"repo":       "repo",
+		"categoryId": "DIC_kwDOABC123",
+		"first":      float64(30),
+		"after":      (*string)(nil),
 	}
 
 	tests := []struct {
@@ -167,15 +163,25 @@ func Test_ListDiscussions(t *testing.T) {
 			}
 			require.NoError(t, err)
 
-			var returnedDiscussions []*github.Discussion
-			err = json.Unmarshal([]byte(text), &returnedDiscussions)
+			// Parse the structured response with pagination info
+			var response struct {
+				Discussions []*github.Discussion `json:"discussions"`
+				PageInfo    struct {
+					HasNextPage     bool   `json:"hasNextPage"`
+					HasPreviousPage bool   `json:"hasPreviousPage"`
+					StartCursor     string `json:"startCursor"`
+					EndCursor       string `json:"endCursor"`
+				} `json:"pageInfo"`
+				TotalCount int `json:"totalCount"`
+			}
+			err = json.Unmarshal([]byte(text), &response)
 			require.NoError(t, err)
 
-			assert.Len(t, returnedDiscussions, tc.expectedCount, "Expected %d discussions, got %d", tc.expectedCount, len(returnedDiscussions))
+			assert.Len(t, response.Discussions, tc.expectedCount, "Expected %d discussions, got %d", tc.expectedCount, len(response.Discussions))
 
 			// Verify that all returned discussions have a category if filtered
 			if _, hasCategory := tc.reqParams["category"]; hasCategory {
-				for _, discussion := range returnedDiscussions {
+				for _, discussion := range response.Discussions {
 					require.NotNil(t, discussion.DiscussionCategory, "Discussion should have category")
 					assert.NotEmpty(t, *discussion.DiscussionCategory.Name, "Discussion should have category name")
 				}
@@ -194,23 +200,13 @@ func Test_GetDiscussion(t *testing.T) {
 	assert.Contains(t, toolDef.InputSchema.Properties, "discussionNumber")
 	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo", "discussionNumber"})
 
-	var q struct {
-		Repository struct {
-			Discussion struct {
-				Number    githubv4.Int
-				Body      githubv4.String
-				CreatedAt githubv4.DateTime
-				URL       githubv4.String `graphql:"url"`
-				Category  struct {
-					Name githubv4.String
-				} `graphql:"category"`
-			} `graphql:"discussion(number: $discussionNumber)"`
-		} `graphql:"repository(owner: $owner, name: $repo)"`
-	}
+	// Use exact string query that matches implementation output
+	qGetDiscussion := "query($discussionNumber:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussion(number: $discussionNumber){number,body,createdAt,url,category{name}}}}"
+
 	vars := map[string]interface{}{
-		"owner":            githubv4.String("owner"),
-		"repo":             githubv4.String("repo"),
-		"discussionNumber": githubv4.Int(1),
+		"owner":            "owner",
+		"repo":             "repo",
+		"discussionNumber": float64(1),
 	}
 	tests := []struct {
 		name        string
@@ -250,7 +246,7 @@ func Test_GetDiscussion(t *testing.T) {
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			matcher := githubv4mock.NewQueryMatcher(q, vars, tc.response)
+			matcher := githubv4mock.NewQueryMatcher(qGetDiscussion, vars, tc.response)
 			httpClient := githubv4mock.NewMockedHTTPClient(matcher)
 			gqlClient := githubv4.NewClient(httpClient)
 			_, handler := GetDiscussion(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper)
@@ -287,22 +283,18 @@ func Test_GetDiscussionComments(t *testing.T) {
 	assert.Contains(t, toolDef.InputSchema.Properties, "discussionNumber")
 	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo", "discussionNumber"})
 
-	var q struct {
-		Repository struct {
-			Discussion struct {
-				Comments struct {
-					Nodes []struct {
-						Body githubv4.String
-					}
-				} `graphql:"comments(first:100)"`
-			} `graphql:"discussion(number: $discussionNumber)"`
-		} `graphql:"repository(owner: $owner, name: $repo)"`
-	}
+	// Use exact string query that matches implementation output
+	qGetComments := "query($after:String$discussionNumber:Int!$first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussion(number: $discussionNumber){comments(first: $first, after: $after){nodes{body},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}}"
+
+	// Variables matching what GraphQL receives after JSON marshaling/unmarshaling
 	vars := map[string]interface{}{
-		"owner":            githubv4.String("owner"),
-		"repo":             githubv4.String("repo"),
-		"discussionNumber": githubv4.Int(1),
+		"owner":            "owner",
+		"repo":             "repo",
+		"discussionNumber": float64(1),
+		"first":            float64(30),
+		"after":            (*string)(nil),
 	}
+
 	mockResponse := githubv4mock.DataResponse(map[string]any{
 		"repository": map[string]any{
 			"discussion": map[string]any{
@@ -311,11 +303,18 @@ func Test_GetDiscussionComments(t *testing.T) {
 						{"body": "This is the first comment"},
 						{"body": "This is the second comment"},
 					},
+					"pageInfo": map[string]any{
+						"hasNextPage":     false,
+						"hasPreviousPage": false,
+						"startCursor":     "",
+						"endCursor":       "",
+					},
+					"totalCount": 2,
 				},
 			},
 		},
 	})
-	matcher := githubv4mock.NewQueryMatcher(q, vars, mockResponse)
+	matcher := githubv4mock.NewQueryMatcher(qGetComments, vars, mockResponse)
 	httpClient := githubv4mock.NewMockedHTTPClient(matcher)
 	gqlClient := githubv4.NewClient(httpClient)
 	_, handler := GetDiscussionComments(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper)
@@ -331,31 +330,38 @@ func Test_GetDiscussionComments(t *testing.T) {
 
 	textContent := getTextResult(t, result)
 
-	var returnedComments []*github.IssueComment
-	err = json.Unmarshal([]byte(textContent.Text), &returnedComments)
+	// (Lines removed)
+
+	var response struct {
+		Comments []*github.IssueComment `json:"comments"`
+		PageInfo struct {
+			HasNextPage     bool   `json:"hasNextPage"`
+			HasPreviousPage bool   `json:"hasPreviousPage"`
+			StartCursor     string `json:"startCursor"`
+			EndCursor       string `json:"endCursor"`
+		} `json:"pageInfo"`
+		TotalCount int `json:"totalCount"`
+	}
+	err = json.Unmarshal([]byte(textContent.Text), &response)
 	require.NoError(t, err)
-	assert.Len(t, returnedComments, 2)
+	assert.Len(t, response.Comments, 2)
 	expectedBodies := []string{"This is the first comment", "This is the second comment"}
-	for i, comment := range returnedComments {
+	for i, comment := range response.Comments {
 		assert.Equal(t, expectedBodies[i], *comment.Body)
 	}
 }
 
 func Test_ListDiscussionCategories(t *testing.T) {
-	var q struct {
-		Repository struct {
-			DiscussionCategories struct {
-				Nodes []struct {
-					ID   githubv4.ID
-					Name githubv4.String
-				}
-			} `graphql:"discussionCategories(first: 100)"`
-		} `graphql:"repository(owner: $owner, name: $repo)"`
-	}
+	// Use exact string query that matches implementation output
+	qListCategories := "query($first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussionCategories(first: $first){nodes{id,name},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
+
+	// Variables matching what GraphQL receives after JSON marshaling/unmarshaling
 	vars := map[string]interface{}{
-		"owner": githubv4.String("owner"),
-		"repo":  githubv4.String("repo"),
+		"owner": "owner",
+		"repo":  "repo",
+		"first": float64(25),
 	}
+
 	mockResp := githubv4mock.DataResponse(map[string]any{
 		"repository": map[string]any{
 			"discussionCategories": map[string]any{
@@ -363,10 +369,17 @@ func Test_ListDiscussionCategories(t *testing.T) {
 					{"id": "123", "name": "CategoryOne"},
 					{"id": "456", "name": "CategoryTwo"},
 				},
+				"pageInfo": map[string]any{
+					"hasNextPage":     false,
+					"hasPreviousPage": false,
+					"startCursor":     "",
+					"endCursor":       "",
+				},
+				"totalCount": 2,
 			},
 		},
 	})
-	matcher := githubv4mock.NewQueryMatcher(q, vars, mockResp)
+	matcher := githubv4mock.NewQueryMatcher(qListCategories, vars, mockResp)
 	httpClient := githubv4mock.NewMockedHTTPClient(matcher)
 	gqlClient := githubv4.NewClient(httpClient)
 
@@ -382,11 +395,21 @@ func Test_ListDiscussionCategories(t *testing.T) {
 	require.NoError(t, err)
 
 	text := getTextResult(t, result).Text
-	var categories []map[string]string
-	require.NoError(t, json.Unmarshal([]byte(text), &categories))
-	assert.Len(t, categories, 2)
-	assert.Equal(t, "123", categories[0]["id"])
-	assert.Equal(t, "CategoryOne", categories[0]["name"])
-	assert.Equal(t, "456", categories[1]["id"])
-	assert.Equal(t, "CategoryTwo", categories[1]["name"])
+
+	var response struct {
+		Categories []map[string]string `json:"categories"`
+		PageInfo   struct {
+			HasNextPage     bool   `json:"hasNextPage"`
+			HasPreviousPage bool   `json:"hasPreviousPage"`
+			StartCursor     string `json:"startCursor"`
+			EndCursor       string `json:"endCursor"`
+		} `json:"pageInfo"`
+		TotalCount int `json:"totalCount"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(text), &response))
+	assert.Len(t, response.Categories, 2)
+	assert.Equal(t, "123", response.Categories[0]["id"])
+	assert.Equal(t, "CategoryOne", response.Categories[0]["name"])
+	assert.Equal(t, "456", response.Categories[1]["id"])
+	assert.Equal(t, "CategoryTwo", response.Categories[1]["name"])
 }
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
index 29d32bd18..80a150aba 100644
--- a/pkg/github/issues.go
+++ b/pkg/github/issues.go
@@ -630,8 +630,8 @@ func GetIssueComments(getClient GetClientFn, t translations.TranslationHelperFun
 
 			opts := &github.IssueListCommentsOptions{
 				ListOptions: github.ListOptions{
-					Page:    pagination.page,
-					PerPage: pagination.perPage,
+					Page:    pagination.Page,
+					PerPage: pagination.PerPage,
 				},
 			}
 
diff --git a/pkg/github/notifications.go b/pkg/github/notifications.go
index a41edaf42..fdd418098 100644
--- a/pkg/github/notifications.go
+++ b/pkg/github/notifications.go
@@ -88,8 +88,8 @@ func ListNotifications(getClient GetClientFn, t translations.TranslationHelperFu
 				All:           filter == FilterIncludeRead,
 				Participating: filter == FilterOnlyParticipating,
 				ListOptions: github.ListOptions{
-					Page:    paginationParams.page,
-					PerPage: paginationParams.perPage,
+					Page:    paginationParams.Page,
+					PerPage: paginationParams.PerPage,
 				},
 			}
 
diff --git a/pkg/github/pullrequests.go b/pkg/github/pullrequests.go
index d98dc334d..47b7c6bd2 100644
--- a/pkg/github/pullrequests.go
+++ b/pkg/github/pullrequests.go
@@ -403,8 +403,8 @@ func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFun
 				Sort:      sort,
 				Direction: direction,
 				ListOptions: github.ListOptions{
-					PerPage: pagination.perPage,
-					Page:    pagination.page,
+					PerPage: pagination.PerPage,
+					Page:    pagination.Page,
 				},
 			}
 
@@ -622,8 +622,8 @@ func GetPullRequestFiles(getClient GetClientFn, t translations.TranslationHelper
 				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
 			}
 			opts := &github.ListOptions{
-				PerPage: pagination.perPage,
-				Page:    pagination.page,
+				PerPage: pagination.PerPage,
+				Page:    pagination.Page,
 			}
 			files, resp, err := client.PullRequests.ListFiles(ctx, owner, repo, pullNumber, opts)
 			if err != nil {
diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go
index 2e56c8644..ecd36d7e0 100644
--- a/pkg/github/repositories.go
+++ b/pkg/github/repositories.go
@@ -58,8 +58,8 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too
 			}
 
 			opts := &github.ListOptions{
-				Page:    pagination.page,
-				PerPage: pagination.perPage,
+				Page:    pagination.Page,
+				PerPage: pagination.PerPage,
 			}
 
 			client, err := getClient(ctx)
@@ -139,7 +139,7 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 			// Set default perPage to 30 if not provided
-			perPage := pagination.perPage
+			perPage := pagination.PerPage
 			if perPage == 0 {
 				perPage = 30
 			}
@@ -147,7 +147,7 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 				SHA:    sha,
 				Author: author,
 				ListOptions: github.ListOptions{
-					Page:    pagination.page,
+					Page:    pagination.Page,
 					PerPage: perPage,
 				},
 			}
@@ -217,8 +217,8 @@ func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc) (
 
 			opts := &github.BranchListOptions{
 				ListOptions: github.ListOptions{
-					Page:    pagination.page,
-					PerPage: pagination.perPage,
+					Page:    pagination.Page,
+					PerPage: pagination.PerPage,
 				},
 			}
 
@@ -1198,8 +1198,8 @@ func ListTags(getClient GetClientFn, t translations.TranslationHelperFunc) (tool
 			}
 
 			opts := &github.ListOptions{
-				Page:    pagination.page,
-				PerPage: pagination.perPage,
+				Page:    pagination.Page,
+				PerPage: pagination.PerPage,
 			}
 
 			client, err := getClient(ctx)
diff --git a/pkg/github/search.go b/pkg/github/search.go
index 04a1facc0..b11bb3bbc 100644
--- a/pkg/github/search.go
+++ b/pkg/github/search.go
@@ -39,8 +39,8 @@ func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperF
 
 			opts := &github.SearchOptions{
 				ListOptions: github.ListOptions{
-					Page:    pagination.page,
-					PerPage: pagination.perPage,
+					Page:    pagination.Page,
+					PerPage: pagination.PerPage,
 				},
 			}
 
@@ -118,8 +118,8 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to
 				Sort:  sort,
 				Order: order,
 				ListOptions: github.ListOptions{
-					PerPage: pagination.perPage,
-					Page:    pagination.page,
+					PerPage: pagination.PerPage,
+					Page:    pagination.Page,
 				},
 			}
 
@@ -193,8 +193,8 @@ func userOrOrgHandler(accountType string, getClient GetClientFn) server.ToolHand
 			Sort:  sort,
 			Order: order,
 			ListOptions: github.ListOptions{
-				PerPage: pagination.perPage,
-				Page:    pagination.page,
+				PerPage: pagination.PerPage,
+				Page:    pagination.Page,
 			},
 		}
 
diff --git a/pkg/github/search_utils.go b/pkg/github/search_utils.go
index 5dd48040e..a6ff1f782 100644
--- a/pkg/github/search_utils.go
+++ b/pkg/github/search_utils.go
@@ -56,8 +56,8 @@ func searchHandler(
 		Sort:  sort,
 		Order: order,
 		ListOptions: github.ListOptions{
-			Page:    pagination.page,
-			PerPage: pagination.perPage,
+			Page:    pagination.Page,
+			PerPage: pagination.PerPage,
 		},
 	}
 
diff --git a/pkg/github/server.go b/pkg/github/server.go
index ea476e3ac..193336b75 100644
--- a/pkg/github/server.go
+++ b/pkg/github/server.go
@@ -174,9 +174,7 @@ func OptionalStringArrayParam(r mcp.CallToolRequest, p string) ([]string, error)
 	}
 }
 
-// WithPagination returns a ToolOption that adds "page" and "perPage" parameters to the tool.
-// The "page" parameter is optional, min 1.
-// The "perPage" parameter is optional, min 1, max 100. If unset, defaults to 30.
+// WithPagination adds REST API pagination parameters to a tool.
 // https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
 func WithPagination() mcp.ToolOption {
 	return func(tool *mcp.Tool) {
@@ -193,12 +191,49 @@ func WithPagination() mcp.ToolOption {
 	}
 }
 
+// WithUnifiedPagination adds REST API pagination parameters to a tool.
+// GraphQL tools will use this and convert page/perPage to GraphQL cursor parameters internally.
+func WithUnifiedPagination() mcp.ToolOption {
+	return func(tool *mcp.Tool) {
+		mcp.WithNumber("page",
+			mcp.Description("Page number for pagination (min 1)"),
+			mcp.Min(1),
+		)(tool)
+
+		mcp.WithNumber("perPage",
+			mcp.Description("Results per page for pagination (min 1, max 100)"),
+			mcp.Min(1),
+			mcp.Max(100),
+		)(tool)
+
+		mcp.WithString("after",
+			mcp.Description("Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs."),
+		)(tool)
+	}
+}
+
+// WithCursorPagination adds only cursor-based pagination parameters to a tool (no page parameter).
+func WithCursorPagination() mcp.ToolOption {
+	return func(tool *mcp.Tool) {
+		mcp.WithNumber("perPage",
+			mcp.Description("Results per page for pagination (min 1, max 100)"),
+			mcp.Min(1),
+			mcp.Max(100),
+		)(tool)
+
+		mcp.WithString("after",
+			mcp.Description("Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs."),
+		)(tool)
+	}
+}
+
 type PaginationParams struct {
-	page    int
-	perPage int
+	Page    int
+	PerPage int
+	After   string
 }
 
-// OptionalPaginationParams returns the "page" and "perPage" parameters from the request,
+// OptionalPaginationParams returns the "page", "perPage", and "after" parameters from the request,
 // or their default values if not present, "page" default is 1, "perPage" default is 30.
 // In future, we may want to make the default values configurable, or even have this
 // function returned from `withPagination`, where the defaults are provided alongside
@@ -212,12 +247,77 @@ func OptionalPaginationParams(r mcp.CallToolRequest) (PaginationParams, error) {
 	if err != nil {
 		return PaginationParams{}, err
 	}
+	after, err := OptionalParam[string](r, "after")
+	if err != nil {
+		return PaginationParams{}, err
+	}
 	return PaginationParams{
-		page:    page,
-		perPage: perPage,
+		Page:    page,
+		PerPage: perPage,
+		After:   after,
+	}, nil
+}
+
+// OptionalCursorPaginationParams returns the "perPage" and "after" parameters from the request,
+// without the "page" parameter, suitable for cursor-based pagination only.
+func OptionalCursorPaginationParams(r mcp.CallToolRequest) (CursorPaginationParams, error) {
+	perPage, err := OptionalIntParamWithDefault(r, "perPage", 30)
+	if err != nil {
+		return CursorPaginationParams{}, err
+	}
+	after, err := OptionalParam[string](r, "after")
+	if err != nil {
+		return CursorPaginationParams{}, err
+	}
+	return CursorPaginationParams{
+		PerPage: perPage,
+		After:   after,
+	}, nil
+}
+
+type CursorPaginationParams struct {
+	PerPage int
+	After   string
+}
+
+// ToGraphQLParams converts cursor pagination parameters to GraphQL-specific parameters.
+func (p CursorPaginationParams) ToGraphQLParams() (*GraphQLPaginationParams, error) {
+	if p.PerPage > 100 {
+		return nil, fmt.Errorf("perPage value %d exceeds maximum of 100", p.PerPage)
+	}
+	if p.PerPage < 0 {
+		return nil, fmt.Errorf("perPage value %d cannot be negative", p.PerPage)
+	}
+	first := int32(p.PerPage)
+
+	var after *string
+	if p.After != "" {
+		after = &p.After
+	}
+
+	return &GraphQLPaginationParams{
+		First: &first,
+		After: after,
 	}, nil
 }
 
+type GraphQLPaginationParams struct {
+	First *int32
+	After *string
+}
+
+// ToGraphQLParams converts REST API pagination parameters to GraphQL-specific parameters.
+// This converts page/perPage to first parameter for GraphQL queries.
+// If After is provided, it takes precedence over page-based pagination.
+func (p PaginationParams) ToGraphQLParams() (*GraphQLPaginationParams, error) {
+	// Convert to CursorPaginationParams and delegate to avoid duplication
+	cursor := CursorPaginationParams{
+		PerPage: p.PerPage,
+		After:   p.After,
+	}
+	return cursor.ToGraphQLParams()
+}
+
 func MarshalledTextResult(v any) *mcp.CallToolResult {
 	data, err := json.Marshal(v)
 	if err != nil {
diff --git a/pkg/github/server_test.go b/pkg/github/server_test.go
index 6353f254d..7f8f29c0d 100644
--- a/pkg/github/server_test.go
+++ b/pkg/github/server_test.go
@@ -489,8 +489,8 @@ func TestOptionalPaginationParams(t *testing.T) {
 			name:   "no pagination parameters, default values",
 			params: map[string]any{},
 			expected: PaginationParams{
-				page:    1,
-				perPage: 30,
+				Page:    1,
+				PerPage: 30,
 			},
 			expectError: false,
 		},
@@ -500,8 +500,8 @@ func TestOptionalPaginationParams(t *testing.T) {
 				"page": float64(2),
 			},
 			expected: PaginationParams{
-				page:    2,
-				perPage: 30,
+				Page:    2,
+				PerPage: 30,
 			},
 			expectError: false,
 		},
@@ -511,8 +511,8 @@ func TestOptionalPaginationParams(t *testing.T) {
 				"perPage": float64(50),
 			},
 			expected: PaginationParams{
-				page:    1,
-				perPage: 50,
+				Page:    1,
+				PerPage: 50,
 			},
 			expectError: false,
 		},
@@ -523,8 +523,8 @@ func TestOptionalPaginationParams(t *testing.T) {
 				"perPage": float64(50),
 			},
 			expected: PaginationParams{
-				page:    2,
-				perPage: 50,
+				Page:    2,
+				PerPage: 50,
 			},
 			expectError: false,
 		},

From 60a5391d67543ca4ef53370cbb48a01f3702fc66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20H=C3=B8st=20Normark?= <m@martinnormark.com>
Date: Tue, 22 Jul 2025 10:24:46 +0200
Subject: [PATCH 29/32] Add tools for sub-issue endpoint (#470)

* Create 'add sub-issue' tool

* Fix hardcoded API host

* Create 'list sub-issues' tool

* Create 'remove sub-issue' tool

* Fix Test_GetIssue mock data - add missing User field

The assertion was already checking User.Login but the mock was incomplete

* Create 'reprioritize sub-issue' tool

* fixes

* use go github pck to add sub-issues

* Update to use go github package

* update description

* update to use go github v73

* lint, docs

* refactor: tests to use go-github-mock

* add toolsnaps

* make RemoveSubIssue use NewGitHubAPIErrorResponse, update docstring

* Always include SHA in get_file_contents responses (#676)

* fix: Add SHA to get_file_contents while preserving MCP behavior (#595)

Enhance get_file_contents to include SHA information without changing
the existing MCP server response format.

Changes:
- Add Contents API call to retrieve SHA before fetching raw content
- Include SHA in resourceURI (repo://owner/repo/sha/{SHA}/contents/path)
- Add SHA to success messages
- Update tests to verify SHA inclusion
- Maintain original behavior: text files return raw text, binaries return base64

This preserves backward compatibility while providing SHA information
for better file versioning support.

Closes #595

* fix: Improve error handling for Contents API response

Ensure response body is properly closed even when an error occurs by moving
the defer statement before the error check. This prevents potential resource
leaks when the Contents API returns an error with a non-nil response.

Changes:
- Move defer respContents.Body.Close() before error checking
- Rename errContents to err for consistency
- Add nil check for respContents before attempting to close body

This follows Go best practices for handling HTTP responses and prevents
potential goroutine/memory leaks.

* revert changes to resource URI

* use GraphQL API to get file SHA

* refactor: mock GQL client instead of getFileSHA function to follow conventions

* lint

* revert GraphQL

---------

Co-authored-by: LuluBeatson <lulubeatson@github.com>

* Reorganize README, add dedicated install guides, include policies and governance info for the github server (#695)

* Refactor README and add host installation guides, governance docs

- Reorganized README for clarity and navigation
- Added dedicated installation guides for Claude, Cursor, Windsurf, JetBrains, and more
- Clarified contribution guidelines and approval criteria
- Added policies and governance documentation

* Update README.md

* Update README with configuration section for remote GitHub MCP Server

* Update MCP access policy description in README

Removing coding agent from the policy note, as the GitHub server is unaffected by this policy

* Update configuration steps for GitHub Copilot in JetBrains IDEs...

...to reflect changes in accessing settings and configuring MCP.

* Update install-other-copilot-ides.md

* Update Eclipse MCP support version and configuration steps...

...for GitHub Copilot plugin in installation guide.

* Update docs/installation-guides/install-cursor.md

* Update docs/installation-guides/install-windsurf.md

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

* Apply suggestion from @tonytrg

---------

Co-authored-by: Tony Truong <tonytrg@github.com>

* fix: shorten long tool name for adding pr review comments (#697)

* shorten tool name

* update function name to match tool name

* adjust wording of descriptions

* Update installation guide for GitHub MCP Server (#699)

* Update installation guide for GitHub MCP Server

Removed reference to GitHub.com in the installation guide. The GitHub server is available to Coding Agent by default, without installation needed.

* Rename section to 'Install in Other MCP Hosts'

Updating title for consistency and adding a link to the "other Copilot IDEs" install guide.

* Revise installation guide for Cursor MCP setup

Updated installation guide for Cursor with steps clarified, remote server installation, and one-click install deeplinks to open Cursor and add the github server to the config file.

* fix: make mcpcurl support "integer" type (#688)

- FYI:https://json-schema.org/understanding-json-schema/reference/numeric#integer

* Added installation instructions for mcpcurl (#719)

* Added installation instructions for mcpcurl

* Update cmd/mcpcurl/README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add pagination support to GraphQL-based tools (#683)

* initial pagination for `ListDiscussions`

* redo category id var cast

* add GraphQL pagination support for discussion comments and categories

* remove pageinfo returns

* fix out ref for linter

* update docs

* move to unified pagination for consensus on params

* update docs

* refactor pagination handling

* update docs

* linter fix

* conv rest to gql params for safe lint

* add nolint

* add error handling for perPage value in ToGraphQLParams

* refactor pagination error handling

* unified params for rest andn graphql and rennamed to be uniform for golang

* add 'after' for pagination

* update docs

* Update pkg/github/discussions.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update pkg/github/discussions.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update pkg/github/discussions_test.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* update default page size const

* reduce default pagination size from 100 to 30 in discussion tests

* update pagination for reverse and total

* update pagination to remove from discussions

* updated README

* improve the `ToGraphQLParams` function

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* shorten param descriptions

* fix: resp nil check in error handling in RemoveSubIssue function

---------

Co-authored-by: LuluBeatson <lulubeatson@github.com>
Co-authored-by: tommaso-moro <tommaso-moro@github.com>
---
 README.md                                     |  28 +
 pkg/github/__toolsnaps__/add_sub_issue.snap   |  39 +
 pkg/github/__toolsnaps__/list_sub_issues.snap |  38 +
 .../__toolsnaps__/remove_sub_issue.snap       |  35 +
 .../__toolsnaps__/reprioritize_sub_issue.snap |  43 +
 pkg/github/issues.go                          | 403 ++++++++
 pkg/github/issues_test.go                     | 972 ++++++++++++++++++
 pkg/github/tools.go                           |   4 +
 8 files changed, 1562 insertions(+)
 create mode 100644 pkg/github/__toolsnaps__/add_sub_issue.snap
 create mode 100644 pkg/github/__toolsnaps__/list_sub_issues.snap
 create mode 100644 pkg/github/__toolsnaps__/remove_sub_issue.snap
 create mode 100644 pkg/github/__toolsnaps__/reprioritize_sub_issue.snap

diff --git a/README.md b/README.md
index c06142b76..39aa0157b 100644
--- a/README.md
+++ b/README.md
@@ -478,6 +478,13 @@ The following sets of tools are available (all are on by default):
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
 
+- **add_sub_issue** - Add sub-issue
+  - `issue_number`: The number of the parent issue (number, required)
+  - `owner`: Repository owner (string, required)
+  - `replace_parent`: When true, replaces the sub-issue's current parent issue (boolean, optional)
+  - `repo`: Repository name (string, required)
+  - `sub_issue_id`: The ID of the sub-issue to add. ID is not the same as issue number (number, required)
+
 - **assign_copilot_to_issue** - Assign Copilot to issue
   - `issueNumber`: Issue number (number, required)
   - `owner`: Repository owner (string, required)
@@ -515,6 +522,27 @@ The following sets of tools are available (all are on by default):
   - `sort`: Sort order (string, optional)
   - `state`: Filter by state (string, optional)
 
+- **list_sub_issues** - List sub-issues
+  - `issue_number`: Issue number (number, required)
+  - `owner`: Repository owner (string, required)
+  - `page`: Page number for pagination (default: 1) (number, optional)
+  - `per_page`: Number of results per page (max 100, default: 30) (number, optional)
+  - `repo`: Repository name (string, required)
+
+- **remove_sub_issue** - Remove sub-issue
+  - `issue_number`: The number of the parent issue (number, required)
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+  - `sub_issue_id`: The ID of the sub-issue to remove. ID is not the same as issue number (number, required)
+
+- **reprioritize_sub_issue** - Reprioritize sub-issue
+  - `after_id`: The ID of the sub-issue to be prioritized after (either after_id OR before_id should be specified) (number, optional)
+  - `before_id`: The ID of the sub-issue to be prioritized before (either after_id OR before_id should be specified) (number, optional)
+  - `issue_number`: The number of the parent issue (number, required)
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+  - `sub_issue_id`: The ID of the sub-issue to reprioritize. ID is not the same as issue number (number, required)
+
 - **search_issues** - Search issues
   - `order`: Sort order (string, optional)
   - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional)
diff --git a/pkg/github/__toolsnaps__/add_sub_issue.snap b/pkg/github/__toolsnaps__/add_sub_issue.snap
new file mode 100644
index 000000000..2d462bcaf
--- /dev/null
+++ b/pkg/github/__toolsnaps__/add_sub_issue.snap
@@ -0,0 +1,39 @@
+{
+  "annotations": {
+    "title": "Add sub-issue",
+    "readOnlyHint": false
+  },
+  "description": "Add a sub-issue to a parent issue in a GitHub repository.",
+  "inputSchema": {
+    "properties": {
+      "issue_number": {
+        "description": "The number of the parent issue",
+        "type": "number"
+      },
+      "owner": {
+        "description": "Repository owner",
+        "type": "string"
+      },
+      "replace_parent": {
+        "description": "When true, replaces the sub-issue's current parent issue",
+        "type": "boolean"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string"
+      },
+      "sub_issue_id": {
+        "description": "The ID of the sub-issue to add. ID is not the same as issue number",
+        "type": "number"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "issue_number",
+      "sub_issue_id"
+    ],
+    "type": "object"
+  },
+  "name": "add_sub_issue"
+}
\ No newline at end of file
diff --git a/pkg/github/__toolsnaps__/list_sub_issues.snap b/pkg/github/__toolsnaps__/list_sub_issues.snap
new file mode 100644
index 000000000..70640e270
--- /dev/null
+++ b/pkg/github/__toolsnaps__/list_sub_issues.snap
@@ -0,0 +1,38 @@
+{
+  "annotations": {
+    "title": "List sub-issues",
+    "readOnlyHint": true
+  },
+  "description": "List sub-issues for a specific issue in a GitHub repository.",
+  "inputSchema": {
+    "properties": {
+      "issue_number": {
+        "description": "Issue number",
+        "type": "number"
+      },
+      "owner": {
+        "description": "Repository owner",
+        "type": "string"
+      },
+      "page": {
+        "description": "Page number for pagination (default: 1)",
+        "type": "number"
+      },
+      "per_page": {
+        "description": "Number of results per page (max 100, default: 30)",
+        "type": "number"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "issue_number"
+    ],
+    "type": "object"
+  },
+  "name": "list_sub_issues"
+}
\ No newline at end of file
diff --git a/pkg/github/__toolsnaps__/remove_sub_issue.snap b/pkg/github/__toolsnaps__/remove_sub_issue.snap
new file mode 100644
index 000000000..a29020099
--- /dev/null
+++ b/pkg/github/__toolsnaps__/remove_sub_issue.snap
@@ -0,0 +1,35 @@
+{
+  "annotations": {
+    "title": "Remove sub-issue",
+    "readOnlyHint": false
+  },
+  "description": "Remove a sub-issue from a parent issue in a GitHub repository.",
+  "inputSchema": {
+    "properties": {
+      "issue_number": {
+        "description": "The number of the parent issue",
+        "type": "number"
+      },
+      "owner": {
+        "description": "Repository owner",
+        "type": "string"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string"
+      },
+      "sub_issue_id": {
+        "description": "The ID of the sub-issue to remove. ID is not the same as issue number",
+        "type": "number"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "issue_number",
+      "sub_issue_id"
+    ],
+    "type": "object"
+  },
+  "name": "remove_sub_issue"
+}
\ No newline at end of file
diff --git a/pkg/github/__toolsnaps__/reprioritize_sub_issue.snap b/pkg/github/__toolsnaps__/reprioritize_sub_issue.snap
new file mode 100644
index 000000000..43c258b33
--- /dev/null
+++ b/pkg/github/__toolsnaps__/reprioritize_sub_issue.snap
@@ -0,0 +1,43 @@
+{
+  "annotations": {
+    "title": "Reprioritize sub-issue",
+    "readOnlyHint": false
+  },
+  "description": "Reprioritize a sub-issue to a different position in the parent issue's sub-issue list.",
+  "inputSchema": {
+    "properties": {
+      "after_id": {
+        "description": "The ID of the sub-issue to be prioritized after (either after_id OR before_id should be specified)",
+        "type": "number"
+      },
+      "before_id": {
+        "description": "The ID of the sub-issue to be prioritized before (either after_id OR before_id should be specified)",
+        "type": "number"
+      },
+      "issue_number": {
+        "description": "The number of the parent issue",
+        "type": "number"
+      },
+      "owner": {
+        "description": "Repository owner",
+        "type": "string"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string"
+      },
+      "sub_issue_id": {
+        "description": "The ID of the sub-issue to reprioritize. ID is not the same as issue number",
+        "type": "number"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "issue_number",
+      "sub_issue_id"
+    ],
+    "type": "object"
+  },
+  "name": "reprioritize_sub_issue"
+}
\ No newline at end of file
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
index 80a150aba..f718c37cb 100644
--- a/pkg/github/issues.go
+++ b/pkg/github/issues.go
@@ -9,6 +9,7 @@ import (
 	"strings"
 	"time"
 
+	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/go-viper/mapstructure/v2"
 	"github.com/google/go-github/v73/github"
@@ -153,6 +154,408 @@ func AddIssueComment(getClient GetClientFn, t translations.TranslationHelperFunc
 		}
 }
 
+// AddSubIssue creates a tool to add a sub-issue to a parent issue.
+func AddSubIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("add_sub_issue",
+			mcp.WithDescription(t("TOOL_ADD_SUB_ISSUE_DESCRIPTION", "Add a sub-issue to a parent issue in a GitHub repository.")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_ADD_SUB_ISSUE_USER_TITLE", "Add sub-issue"),
+				ReadOnlyHint: ToBoolPtr(false),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithNumber("issue_number",
+				mcp.Required(),
+				mcp.Description("The number of the parent issue"),
+			),
+			mcp.WithNumber("sub_issue_id",
+				mcp.Required(),
+				mcp.Description("The ID of the sub-issue to add. ID is not the same as issue number"),
+			),
+			mcp.WithBoolean("replace_parent",
+				mcp.Description("When true, replaces the sub-issue's current parent issue"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			issueNumber, err := RequiredInt(request, "issue_number")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			subIssueID, err := RequiredInt(request, "sub_issue_id")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			replaceParent, err := OptionalParam[bool](request, "replace_parent")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			subIssueRequest := github.SubIssueRequest{
+				SubIssueID:    int64(subIssueID),
+				ReplaceParent: ToBoolPtr(replaceParent),
+			}
+
+			subIssue, resp, err := client.SubIssue.Add(ctx, owner, repo, int64(issueNumber), subIssueRequest)
+			if err != nil {
+				return ghErrors.NewGitHubAPIErrorResponse(ctx,
+					"failed to add sub-issue",
+					resp,
+					err,
+				), nil
+			}
+
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != http.StatusCreated {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to add sub-issue: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(subIssue)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal response: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}
+
+// ListSubIssues creates a tool to list sub-issues for a GitHub issue.
+func ListSubIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("list_sub_issues",
+			mcp.WithDescription(t("TOOL_LIST_SUB_ISSUES_DESCRIPTION", "List sub-issues for a specific issue in a GitHub repository.")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_LIST_SUB_ISSUES_USER_TITLE", "List sub-issues"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithNumber("issue_number",
+				mcp.Required(),
+				mcp.Description("Issue number"),
+			),
+			mcp.WithNumber("page",
+				mcp.Description("Page number for pagination (default: 1)"),
+			),
+			mcp.WithNumber("per_page",
+				mcp.Description("Number of results per page (max 100, default: 30)"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			issueNumber, err := RequiredInt(request, "issue_number")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			page, err := OptionalIntParamWithDefault(request, "page", 1)
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			perPage, err := OptionalIntParamWithDefault(request, "per_page", 30)
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			opts := &github.IssueListOptions{
+				ListOptions: github.ListOptions{
+					Page:    page,
+					PerPage: perPage,
+				},
+			}
+
+			subIssues, resp, err := client.SubIssue.ListByIssue(ctx, owner, repo, int64(issueNumber), opts)
+			if err != nil {
+				return ghErrors.NewGitHubAPIErrorResponse(ctx,
+					"failed to list sub-issues",
+					resp,
+					err,
+				), nil
+			}
+
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != http.StatusOK {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to list sub-issues: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(subIssues)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal response: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+
+}
+
+// RemoveSubIssue creates a tool to remove a sub-issue from a parent issue.
+// Unlike other sub-issue tools, this currently uses a direct HTTP DELETE request
+// because of a bug in the go-github library.
+// Once the fix is released, this can be updated to use the library method.
+// See: https://github.com/google/go-github/pull/3613
+func RemoveSubIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("remove_sub_issue",
+			mcp.WithDescription(t("TOOL_REMOVE_SUB_ISSUE_DESCRIPTION", "Remove a sub-issue from a parent issue in a GitHub repository.")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_REMOVE_SUB_ISSUE_USER_TITLE", "Remove sub-issue"),
+				ReadOnlyHint: ToBoolPtr(false),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithNumber("issue_number",
+				mcp.Required(),
+				mcp.Description("The number of the parent issue"),
+			),
+			mcp.WithNumber("sub_issue_id",
+				mcp.Required(),
+				mcp.Description("The ID of the sub-issue to remove. ID is not the same as issue number"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			issueNumber, err := RequiredInt(request, "issue_number")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			subIssueID, err := RequiredInt(request, "sub_issue_id")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			// Create the request body
+			requestBody := map[string]interface{}{
+				"sub_issue_id": subIssueID,
+			}
+			reqBodyBytes, err := json.Marshal(requestBody)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal request body: %w", err)
+			}
+
+			// Create the HTTP request
+			url := fmt.Sprintf("%srepos/%s/%s/issues/%d/sub_issue",
+				client.BaseURL.String(), owner, repo, issueNumber)
+			req, err := http.NewRequestWithContext(ctx, "DELETE", url, strings.NewReader(string(reqBodyBytes)))
+			if err != nil {
+				return nil, fmt.Errorf("failed to create request: %w", err)
+			}
+			req.Header.Set("Accept", "application/vnd.github+json")
+			req.Header.Set("Content-Type", "application/json")
+			req.Header.Set("X-GitHub-Api-Version", "2022-11-28")
+
+			httpClient := client.Client() // Use authenticated GitHub client
+			resp, err := httpClient.Do(req)
+			if err != nil {
+				var ghResp *github.Response
+				if resp != nil {
+					ghResp = &github.Response{Response: resp}
+				}
+				return ghErrors.NewGitHubAPIErrorResponse(ctx,
+					"failed to remove sub-issue",
+					ghResp,
+					err,
+				), nil
+			}
+			defer func() { _ = resp.Body.Close() }()
+
+			body, err := io.ReadAll(resp.Body)
+			if err != nil {
+				return nil, fmt.Errorf("failed to read response body: %w", err)
+			}
+
+			if resp.StatusCode != http.StatusOK {
+				return mcp.NewToolResultError(fmt.Sprintf("failed to remove sub-issue: %s", string(body))), nil
+			}
+
+			// Parse and re-marshal to ensure consistent formatting
+			var result interface{}
+			if err := json.Unmarshal(body, &result); err != nil {
+				return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+			}
+
+			r, err := json.Marshal(result)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal response: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}
+
+// ReprioritizeSubIssue creates a tool to reprioritize a sub-issue to a different position in the parent list.
+func ReprioritizeSubIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("reprioritize_sub_issue",
+			mcp.WithDescription(t("TOOL_REPRIORITIZE_SUB_ISSUE_DESCRIPTION", "Reprioritize a sub-issue to a different position in the parent issue's sub-issue list.")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_REPRIORITIZE_SUB_ISSUE_USER_TITLE", "Reprioritize sub-issue"),
+				ReadOnlyHint: ToBoolPtr(false),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithNumber("issue_number",
+				mcp.Required(),
+				mcp.Description("The number of the parent issue"),
+			),
+			mcp.WithNumber("sub_issue_id",
+				mcp.Required(),
+				mcp.Description("The ID of the sub-issue to reprioritize. ID is not the same as issue number"),
+			),
+			mcp.WithNumber("after_id",
+				mcp.Description("The ID of the sub-issue to be prioritized after (either after_id OR before_id should be specified)"),
+			),
+			mcp.WithNumber("before_id",
+				mcp.Description("The ID of the sub-issue to be prioritized before (either after_id OR before_id should be specified)"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			issueNumber, err := RequiredInt(request, "issue_number")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			subIssueID, err := RequiredInt(request, "sub_issue_id")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			// Handle optional positioning parameters
+			afterID, err := OptionalIntParam(request, "after_id")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			beforeID, err := OptionalIntParam(request, "before_id")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			// Validate that either after_id or before_id is specified, but not both
+			if afterID == 0 && beforeID == 0 {
+				return mcp.NewToolResultError("either after_id or before_id must be specified"), nil
+			}
+			if afterID != 0 && beforeID != 0 {
+				return mcp.NewToolResultError("only one of after_id or before_id should be specified, not both"), nil
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			subIssueRequest := github.SubIssueRequest{
+				SubIssueID: int64(subIssueID),
+			}
+
+			if afterID != 0 {
+				afterIDInt64 := int64(afterID)
+				subIssueRequest.AfterID = &afterIDInt64
+			}
+			if beforeID != 0 {
+				beforeIDInt64 := int64(beforeID)
+				subIssueRequest.BeforeID = &beforeIDInt64
+			}
+
+			subIssue, resp, err := client.SubIssue.Reprioritize(ctx, owner, repo, int64(issueNumber), subIssueRequest)
+			if err != nil {
+				return ghErrors.NewGitHubAPIErrorResponse(ctx,
+					"failed to reprioritize sub-issue",
+					resp,
+					err,
+				), nil
+			}
+
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != http.StatusOK {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to reprioritize sub-issue: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(subIssue)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal response: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}
+
 // SearchIssues creates a tool to search for issues.
 func SearchIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("search_issues",
diff --git a/pkg/github/issues_test.go b/pkg/github/issues_test.go
index 146259477..2bdb89b06 100644
--- a/pkg/github/issues_test.go
+++ b/pkg/github/issues_test.go
@@ -38,6 +38,9 @@ func Test_GetIssue(t *testing.T) {
 		Body:    github.Ptr("This is a test issue"),
 		State:   github.Ptr("open"),
 		HTMLURL: github.Ptr("https://github.com/owner/repo/issues/42"),
+		User: &github.User{
+			Login: github.Ptr("testuser"),
+		},
 	}
 
 	tests := []struct {
@@ -111,6 +114,9 @@ func Test_GetIssue(t *testing.T) {
 			assert.Equal(t, *tc.expectedIssue.Number, *returnedIssue.Number)
 			assert.Equal(t, *tc.expectedIssue.Title, *returnedIssue.Title)
 			assert.Equal(t, *tc.expectedIssue.Body, *returnedIssue.Body)
+			assert.Equal(t, *tc.expectedIssue.State, *returnedIssue.State)
+			assert.Equal(t, *tc.expectedIssue.HTMLURL, *returnedIssue.HTMLURL)
+			assert.Equal(t, *tc.expectedIssue.User.Login, *returnedIssue.User.Login)
 		})
 	}
 }
@@ -1629,3 +1635,969 @@ func TestAssignCopilotToIssue(t *testing.T) {
 		})
 	}
 }
+
+func Test_AddSubIssue(t *testing.T) {
+	// Verify tool definition once
+	mockClient := github.NewClient(nil)
+	tool, _ := AddSubIssue(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	require.NoError(t, toolsnaps.Test(tool.Name, tool))
+
+	assert.Equal(t, "add_sub_issue", tool.Name)
+	assert.NotEmpty(t, tool.Description)
+	assert.Contains(t, tool.InputSchema.Properties, "owner")
+	assert.Contains(t, tool.InputSchema.Properties, "repo")
+	assert.Contains(t, tool.InputSchema.Properties, "issue_number")
+	assert.Contains(t, tool.InputSchema.Properties, "sub_issue_id")
+	assert.Contains(t, tool.InputSchema.Properties, "replace_parent")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "issue_number", "sub_issue_id"})
+
+	// Setup mock issue for success case (matches GitHub API response format)
+	mockIssue := &github.Issue{
+		Number:  github.Ptr(42),
+		Title:   github.Ptr("Parent Issue"),
+		Body:    github.Ptr("This is the parent issue with a sub-issue"),
+		State:   github.Ptr("open"),
+		HTMLURL: github.Ptr("https://github.com/owner/repo/issues/42"),
+		User: &github.User{
+			Login: github.Ptr("testuser"),
+		},
+		Labels: []*github.Label{
+			{
+				Name:        github.Ptr("enhancement"),
+				Color:       github.Ptr("84b6eb"),
+				Description: github.Ptr("New feature or request"),
+			},
+		},
+	}
+
+	tests := []struct {
+		name           string
+		mockedClient   *http.Client
+		requestArgs    map[string]interface{}
+		expectError    bool
+		expectedIssue  *github.Issue
+		expectedErrMsg string
+	}{
+		{
+			name: "successful sub-issue addition with all parameters",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PostReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusCreated, mockIssue),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":          "owner",
+				"repo":           "repo",
+				"issue_number":   float64(42),
+				"sub_issue_id":   float64(123),
+				"replace_parent": true,
+			},
+			expectError:   false,
+			expectedIssue: mockIssue,
+		},
+		{
+			name: "successful sub-issue addition with minimal parameters",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PostReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusCreated, mockIssue),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(456),
+			},
+			expectError:   false,
+			expectedIssue: mockIssue,
+		},
+		{
+			name: "successful sub-issue addition with replace_parent false",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PostReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusCreated, mockIssue),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":          "owner",
+				"repo":           "repo",
+				"issue_number":   float64(42),
+				"sub_issue_id":   float64(789),
+				"replace_parent": false,
+			},
+			expectError:   false,
+			expectedIssue: mockIssue,
+		},
+		{
+			name: "parent issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PostReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Parent issue not found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(999),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to add sub-issue",
+		},
+		{
+			name: "sub-issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PostReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Sub-issue not found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(999),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to add sub-issue",
+		},
+		{
+			name: "validation failed - sub-issue cannot be parent of itself",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PostReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusUnprocessableEntity, `{"message": "Validation failed", "errors": [{"message": "Sub-issue cannot be a parent of itself"}]}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(42),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to add sub-issue",
+		},
+		{
+			name: "insufficient permissions",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PostReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusForbidden, `{"message": "Must have write access to repository"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to add sub-issue",
+		},
+		{
+			name:         "missing required parameter owner",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: owner",
+		},
+		{
+			name:         "missing required parameter sub_issue_id",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: sub_issue_id",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Setup client with mock
+			client := github.NewClient(tc.mockedClient)
+			_, handler := AddSubIssue(stubGetClientFn(client), translations.NullTranslationHelper)
+
+			// Create call request
+			request := createMCPRequest(tc.requestArgs)
+
+			// Call handler
+			result, err := handler(context.Background(), request)
+
+			// Verify results
+			if tc.expectError {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.expectedErrMsg)
+				return
+			}
+
+			if tc.expectedErrMsg != "" {
+				require.NotNil(t, result)
+				textContent := getTextResult(t, result)
+				assert.Contains(t, textContent.Text, tc.expectedErrMsg)
+				return
+			}
+
+			require.NoError(t, err)
+
+			// Parse the result and get the text content if no error
+			textContent := getTextResult(t, result)
+
+			// Unmarshal and verify the result
+			var returnedIssue github.Issue
+			err = json.Unmarshal([]byte(textContent.Text), &returnedIssue)
+			require.NoError(t, err)
+			assert.Equal(t, *tc.expectedIssue.Number, *returnedIssue.Number)
+			assert.Equal(t, *tc.expectedIssue.Title, *returnedIssue.Title)
+			assert.Equal(t, *tc.expectedIssue.Body, *returnedIssue.Body)
+			assert.Equal(t, *tc.expectedIssue.State, *returnedIssue.State)
+			assert.Equal(t, *tc.expectedIssue.HTMLURL, *returnedIssue.HTMLURL)
+			assert.Equal(t, *tc.expectedIssue.User.Login, *returnedIssue.User.Login)
+		})
+	}
+}
+
+func Test_ListSubIssues(t *testing.T) {
+	// Verify tool definition once
+	mockClient := github.NewClient(nil)
+	tool, _ := ListSubIssues(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	require.NoError(t, toolsnaps.Test(tool.Name, tool))
+
+	assert.Equal(t, "list_sub_issues", tool.Name)
+	assert.NotEmpty(t, tool.Description)
+	assert.Contains(t, tool.InputSchema.Properties, "owner")
+	assert.Contains(t, tool.InputSchema.Properties, "repo")
+	assert.Contains(t, tool.InputSchema.Properties, "issue_number")
+	assert.Contains(t, tool.InputSchema.Properties, "page")
+	assert.Contains(t, tool.InputSchema.Properties, "per_page")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "issue_number"})
+
+	// Setup mock sub-issues for success case
+	mockSubIssues := []*github.Issue{
+		{
+			Number:  github.Ptr(123),
+			Title:   github.Ptr("Sub-issue 1"),
+			Body:    github.Ptr("This is the first sub-issue"),
+			State:   github.Ptr("open"),
+			HTMLURL: github.Ptr("https://github.com/owner/repo/issues/123"),
+			User: &github.User{
+				Login: github.Ptr("user1"),
+			},
+			Labels: []*github.Label{
+				{
+					Name:        github.Ptr("bug"),
+					Color:       github.Ptr("d73a4a"),
+					Description: github.Ptr("Something isn't working"),
+				},
+			},
+		},
+		{
+			Number:  github.Ptr(124),
+			Title:   github.Ptr("Sub-issue 2"),
+			Body:    github.Ptr("This is the second sub-issue"),
+			State:   github.Ptr("closed"),
+			HTMLURL: github.Ptr("https://github.com/owner/repo/issues/124"),
+			User: &github.User{
+				Login: github.Ptr("user2"),
+			},
+			Assignees: []*github.User{
+				{Login: github.Ptr("assignee1")},
+			},
+		},
+	}
+
+	tests := []struct {
+		name              string
+		mockedClient      *http.Client
+		requestArgs       map[string]interface{}
+		expectError       bool
+		expectedSubIssues []*github.Issue
+		expectedErrMsg    string
+	}{
+		{
+			name: "successful sub-issues listing with minimal parameters",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatch(
+					mock.GetReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockSubIssues,
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+			},
+			expectError:       false,
+			expectedSubIssues: mockSubIssues,
+		},
+		{
+			name: "successful sub-issues listing with pagination",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					expectQueryParams(t, map[string]string{
+						"page":     "2",
+						"per_page": "10",
+					}).andThen(
+						mockResponse(t, http.StatusOK, mockSubIssues),
+					),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"page":         float64(2),
+				"per_page":     float64(10),
+			},
+			expectError:       false,
+			expectedSubIssues: mockSubIssues,
+		},
+		{
+			name: "successful sub-issues listing with empty result",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatch(
+					mock.GetReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					[]*github.Issue{},
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+			},
+			expectError:       false,
+			expectedSubIssues: []*github.Issue{},
+		},
+		{
+			name: "parent issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Not Found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(999),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to list sub-issues",
+		},
+		{
+			name: "repository not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Not Found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "nonexistent",
+				"repo":         "repo",
+				"issue_number": float64(42),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to list sub-issues",
+		},
+		{
+			name: "sub-issues feature gone/deprecated",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposIssuesSubIssuesByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusGone, `{"message": "This feature has been deprecated"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to list sub-issues",
+		},
+		{
+			name:         "missing required parameter owner",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"repo":         "repo",
+				"issue_number": float64(42),
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: owner",
+		},
+		{
+			name:         "missing required parameter issue_number",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: issue_number",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Setup client with mock
+			client := github.NewClient(tc.mockedClient)
+			_, handler := ListSubIssues(stubGetClientFn(client), translations.NullTranslationHelper)
+
+			// Create call request
+			request := createMCPRequest(tc.requestArgs)
+
+			// Call handler
+			result, err := handler(context.Background(), request)
+
+			// Verify results
+			if tc.expectError {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.expectedErrMsg)
+				return
+			}
+
+			if tc.expectedErrMsg != "" {
+				require.NotNil(t, result)
+				textContent := getTextResult(t, result)
+				assert.Contains(t, textContent.Text, tc.expectedErrMsg)
+				return
+			}
+
+			require.NoError(t, err)
+
+			// Parse the result and get the text content if no error
+			textContent := getTextResult(t, result)
+
+			// Unmarshal and verify the result
+			var returnedSubIssues []*github.Issue
+			err = json.Unmarshal([]byte(textContent.Text), &returnedSubIssues)
+			require.NoError(t, err)
+
+			assert.Len(t, returnedSubIssues, len(tc.expectedSubIssues))
+			for i, subIssue := range returnedSubIssues {
+				if i < len(tc.expectedSubIssues) {
+					assert.Equal(t, *tc.expectedSubIssues[i].Number, *subIssue.Number)
+					assert.Equal(t, *tc.expectedSubIssues[i].Title, *subIssue.Title)
+					assert.Equal(t, *tc.expectedSubIssues[i].State, *subIssue.State)
+					assert.Equal(t, *tc.expectedSubIssues[i].HTMLURL, *subIssue.HTMLURL)
+					assert.Equal(t, *tc.expectedSubIssues[i].User.Login, *subIssue.User.Login)
+
+					if tc.expectedSubIssues[i].Body != nil {
+						assert.Equal(t, *tc.expectedSubIssues[i].Body, *subIssue.Body)
+					}
+				}
+			}
+		})
+	}
+}
+
+func Test_RemoveSubIssue(t *testing.T) {
+	// Verify tool definition once
+	mockClient := github.NewClient(nil)
+	tool, _ := RemoveSubIssue(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	require.NoError(t, toolsnaps.Test(tool.Name, tool))
+
+	assert.Equal(t, "remove_sub_issue", tool.Name)
+	assert.NotEmpty(t, tool.Description)
+	assert.Contains(t, tool.InputSchema.Properties, "owner")
+	assert.Contains(t, tool.InputSchema.Properties, "repo")
+	assert.Contains(t, tool.InputSchema.Properties, "issue_number")
+	assert.Contains(t, tool.InputSchema.Properties, "sub_issue_id")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "issue_number", "sub_issue_id"})
+
+	// Setup mock issue for success case (matches GitHub API response format - the updated parent issue)
+	mockIssue := &github.Issue{
+		Number:  github.Ptr(42),
+		Title:   github.Ptr("Parent Issue"),
+		Body:    github.Ptr("This is the parent issue after sub-issue removal"),
+		State:   github.Ptr("open"),
+		HTMLURL: github.Ptr("https://github.com/owner/repo/issues/42"),
+		User: &github.User{
+			Login: github.Ptr("testuser"),
+		},
+		Labels: []*github.Label{
+			{
+				Name:        github.Ptr("enhancement"),
+				Color:       github.Ptr("84b6eb"),
+				Description: github.Ptr("New feature or request"),
+			},
+		},
+	}
+
+	tests := []struct {
+		name           string
+		mockedClient   *http.Client
+		requestArgs    map[string]interface{}
+		expectError    bool
+		expectedIssue  *github.Issue
+		expectedErrMsg string
+	}{
+		{
+			name: "successful sub-issue removal",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.DeleteReposIssuesSubIssueByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusOK, mockIssue),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+			},
+			expectError:   false,
+			expectedIssue: mockIssue,
+		},
+		{
+			name: "parent issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.DeleteReposIssuesSubIssueByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Not Found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(999),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to remove sub-issue",
+		},
+		{
+			name: "sub-issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.DeleteReposIssuesSubIssueByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Sub-issue not found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(999),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to remove sub-issue",
+		},
+		{
+			name: "bad request - invalid sub_issue_id",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.DeleteReposIssuesSubIssueByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusBadRequest, `{"message": "Invalid sub_issue_id"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(-1),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to remove sub-issue",
+		},
+		{
+			name: "repository not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.DeleteReposIssuesSubIssueByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Not Found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "nonexistent",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to remove sub-issue",
+		},
+		{
+			name: "insufficient permissions",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.DeleteReposIssuesSubIssueByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusForbidden, `{"message": "Must have write access to repository"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to remove sub-issue",
+		},
+		{
+			name:         "missing required parameter owner",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: owner",
+		},
+		{
+			name:         "missing required parameter sub_issue_id",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: sub_issue_id",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Setup client with mock
+			client := github.NewClient(tc.mockedClient)
+			_, handler := RemoveSubIssue(stubGetClientFn(client), translations.NullTranslationHelper)
+
+			// Create call request
+			request := createMCPRequest(tc.requestArgs)
+
+			// Call handler
+			result, err := handler(context.Background(), request)
+
+			// Verify results
+			if tc.expectError {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.expectedErrMsg)
+				return
+			}
+
+			if tc.expectedErrMsg != "" {
+				require.NotNil(t, result)
+				textContent := getTextResult(t, result)
+				assert.Contains(t, textContent.Text, tc.expectedErrMsg)
+				return
+			}
+
+			require.NoError(t, err)
+
+			// Parse the result and get the text content if no error
+			textContent := getTextResult(t, result)
+
+			// Unmarshal and verify the result
+			var returnedIssue github.Issue
+			err = json.Unmarshal([]byte(textContent.Text), &returnedIssue)
+			require.NoError(t, err)
+			assert.Equal(t, *tc.expectedIssue.Number, *returnedIssue.Number)
+			assert.Equal(t, *tc.expectedIssue.Title, *returnedIssue.Title)
+			assert.Equal(t, *tc.expectedIssue.Body, *returnedIssue.Body)
+			assert.Equal(t, *tc.expectedIssue.State, *returnedIssue.State)
+			assert.Equal(t, *tc.expectedIssue.HTMLURL, *returnedIssue.HTMLURL)
+			assert.Equal(t, *tc.expectedIssue.User.Login, *returnedIssue.User.Login)
+		})
+	}
+}
+
+func Test_ReprioritizeSubIssue(t *testing.T) {
+	// Verify tool definition once
+	mockClient := github.NewClient(nil)
+	tool, _ := ReprioritizeSubIssue(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	require.NoError(t, toolsnaps.Test(tool.Name, tool))
+
+	assert.Equal(t, "reprioritize_sub_issue", tool.Name)
+	assert.NotEmpty(t, tool.Description)
+	assert.Contains(t, tool.InputSchema.Properties, "owner")
+	assert.Contains(t, tool.InputSchema.Properties, "repo")
+	assert.Contains(t, tool.InputSchema.Properties, "issue_number")
+	assert.Contains(t, tool.InputSchema.Properties, "sub_issue_id")
+	assert.Contains(t, tool.InputSchema.Properties, "after_id")
+	assert.Contains(t, tool.InputSchema.Properties, "before_id")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "issue_number", "sub_issue_id"})
+
+	// Setup mock issue for success case (matches GitHub API response format - the updated parent issue)
+	mockIssue := &github.Issue{
+		Number:  github.Ptr(42),
+		Title:   github.Ptr("Parent Issue"),
+		Body:    github.Ptr("This is the parent issue with reprioritized sub-issues"),
+		State:   github.Ptr("open"),
+		HTMLURL: github.Ptr("https://github.com/owner/repo/issues/42"),
+		User: &github.User{
+			Login: github.Ptr("testuser"),
+		},
+		Labels: []*github.Label{
+			{
+				Name:        github.Ptr("enhancement"),
+				Color:       github.Ptr("84b6eb"),
+				Description: github.Ptr("New feature or request"),
+			},
+		},
+	}
+
+	tests := []struct {
+		name           string
+		mockedClient   *http.Client
+		requestArgs    map[string]interface{}
+		expectError    bool
+		expectedIssue  *github.Issue
+		expectedErrMsg string
+	}{
+		{
+			name: "successful reprioritization with after_id",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PatchReposIssuesSubIssuesPriorityByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusOK, mockIssue),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+				"after_id":     float64(456),
+			},
+			expectError:   false,
+			expectedIssue: mockIssue,
+		},
+		{
+			name: "successful reprioritization with before_id",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PatchReposIssuesSubIssuesPriorityByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusOK, mockIssue),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+				"before_id":    float64(789),
+			},
+			expectError:   false,
+			expectedIssue: mockIssue,
+		},
+		{
+			name:         "validation error - neither after_id nor before_id specified",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+			},
+			expectError:    false,
+			expectedErrMsg: "either after_id or before_id must be specified",
+		},
+		{
+			name:         "validation error - both after_id and before_id specified",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+				"after_id":     float64(456),
+				"before_id":    float64(789),
+			},
+			expectError:    false,
+			expectedErrMsg: "only one of after_id or before_id should be specified, not both",
+		},
+		{
+			name: "parent issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PatchReposIssuesSubIssuesPriorityByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Not Found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(999),
+				"sub_issue_id": float64(123),
+				"after_id":     float64(456),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to reprioritize sub-issue",
+		},
+		{
+			name: "sub-issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PatchReposIssuesSubIssuesPriorityByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusNotFound, `{"message": "Sub-issue not found"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(999),
+				"after_id":     float64(456),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to reprioritize sub-issue",
+		},
+		{
+			name: "validation failed - positioning sub-issue not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PatchReposIssuesSubIssuesPriorityByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusUnprocessableEntity, `{"message": "Validation failed", "errors": [{"message": "Positioning sub-issue not found"}]}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+				"after_id":     float64(999),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to reprioritize sub-issue",
+		},
+		{
+			name: "insufficient permissions",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PatchReposIssuesSubIssuesPriorityByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusForbidden, `{"message": "Must have write access to repository"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+				"after_id":     float64(456),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to reprioritize sub-issue",
+		},
+		{
+			name: "service unavailable",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.PatchReposIssuesSubIssuesPriorityByOwnerByRepoByIssueNumber,
+					mockResponse(t, http.StatusServiceUnavailable, `{"message": "Service Unavailable"}`),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+				"before_id":    float64(456),
+			},
+			expectError:    false,
+			expectedErrMsg: "failed to reprioritize sub-issue",
+		},
+		{
+			name:         "missing required parameter owner",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"sub_issue_id": float64(123),
+				"after_id":     float64(456),
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: owner",
+		},
+		{
+			name:         "missing required parameter sub_issue_id",
+			mockedClient: mock.NewMockedHTTPClient(
+			// No mocked requests needed since validation fails before HTTP call
+			),
+			requestArgs: map[string]interface{}{
+				"owner":        "owner",
+				"repo":         "repo",
+				"issue_number": float64(42),
+				"after_id":     float64(456),
+			},
+			expectError:    false,
+			expectedErrMsg: "missing required parameter: sub_issue_id",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			// Setup client with mock
+			client := github.NewClient(tc.mockedClient)
+			_, handler := ReprioritizeSubIssue(stubGetClientFn(client), translations.NullTranslationHelper)
+
+			// Create call request
+			request := createMCPRequest(tc.requestArgs)
+
+			// Call handler
+			result, err := handler(context.Background(), request)
+
+			// Verify results
+			if tc.expectError {
+				require.Error(t, err)
+				assert.Contains(t, err.Error(), tc.expectedErrMsg)
+				return
+			}
+
+			if tc.expectedErrMsg != "" {
+				require.NotNil(t, result)
+				textContent := getTextResult(t, result)
+				assert.Contains(t, textContent.Text, tc.expectedErrMsg)
+				return
+			}
+
+			require.NoError(t, err)
+
+			// Parse the result and get the text content if no error
+			textContent := getTextResult(t, result)
+
+			// Unmarshal and verify the result
+			var returnedIssue github.Issue
+			err = json.Unmarshal([]byte(textContent.Text), &returnedIssue)
+			require.NoError(t, err)
+			assert.Equal(t, *tc.expectedIssue.Number, *returnedIssue.Number)
+			assert.Equal(t, *tc.expectedIssue.Title, *returnedIssue.Title)
+			assert.Equal(t, *tc.expectedIssue.Body, *returnedIssue.Body)
+			assert.Equal(t, *tc.expectedIssue.State, *returnedIssue.State)
+			assert.Equal(t, *tc.expectedIssue.HTMLURL, *returnedIssue.HTMLURL)
+			assert.Equal(t, *tc.expectedIssue.User.Login, *returnedIssue.User.Login)
+		})
+	}
+}
diff --git a/pkg/github/tools.go b/pkg/github/tools.go
index bd349171d..e01b7cc40 100644
--- a/pkg/github/tools.go
+++ b/pkg/github/tools.go
@@ -53,12 +53,16 @@ func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetG
 			toolsets.NewServerTool(SearchIssues(getClient, t)),
 			toolsets.NewServerTool(ListIssues(getClient, t)),
 			toolsets.NewServerTool(GetIssueComments(getClient, t)),
+			toolsets.NewServerTool(ListSubIssues(getClient, t)),
 		).
 		AddWriteTools(
 			toolsets.NewServerTool(CreateIssue(getClient, t)),
 			toolsets.NewServerTool(AddIssueComment(getClient, t)),
 			toolsets.NewServerTool(UpdateIssue(getClient, t)),
 			toolsets.NewServerTool(AssignCopilotToIssue(getGQLClient, t)),
+			toolsets.NewServerTool(AddSubIssue(getClient, t)),
+			toolsets.NewServerTool(RemoveSubIssue(getClient, t)),
+			toolsets.NewServerTool(ReprioritizeSubIssue(getClient, t)),
 		).AddPrompts(toolsets.NewServerPrompt(AssignCodingAgentPrompt(t)))
 	users := toolsets.NewToolset("users", "GitHub User related tools").
 		AddReadTools(

From 7a9bc91185c8552336b95a7fbbb2d37d63e0ce0a Mon Sep 17 00:00:00 2001
From: vladislav doster <mvdoster@gmail.com>
Date: Wed, 23 Jul 2025 03:19:51 -0500
Subject: [PATCH 30/32] docs: fix spacing in testing.md (#734)

- remove extraneous space
---
 docs/testing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/testing.md b/docs/testing.md
index dbdc3e080..226660e9d 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -22,7 +22,7 @@ This project uses a combination of unit tests and end-to-end (e2e) tests to ensu
 ## toolsnaps: Tool Schema Snapshots
 
 - The `toolsnaps` utility ensures that the JSON schema for each tool does not change unexpectedly.
-- Snapshots are stored in `__toolsnaps__/*.snap` files , where `*` represents the name of the tool
+- Snapshots are stored in `__toolsnaps__/*.snap` files, where `*` represents the name of the tool
 - When running tests, the current tool schema is compared to the snapshot. If there is a difference, the test will fail and show a diff.
 - If you intentionally change a tool's schema, update the snapshots by running tests with the environment variable: `UPDATE_TOOLSNAPS=true go test ./...`
 - In CI (when `GITHUB_ACTIONS=true`), missing snapshots will cause a test failure to ensure snapshots are always

From a9395651605765afe1f667516911901f13843ace Mon Sep 17 00:00:00 2001
From: Tommaso Moro <37270480+tommaso-moro@users.noreply.github.com>
Date: Thu, 24 Jul 2025 12:26:00 +0200
Subject: [PATCH 31/32] feat: list_discussions sort by updatedAt & createdAt,
 return updatedAt and author (#690)

* added updatedAt and Author (aka User) login to query and payload

* added initial support for orderby and direction

* sort by created at instead of updated at by default

* remove unused code

* refactor to map to most suitable query based on user inputs at runtime

* updated readme with new description

* restore original categoryID code, simplify vars management

* quick fix

* update tests to account for recent changes (author login, updated at date)

* use switch statement for better readability

* remove comment

* linting

* refactored logic, simplified switch statement

* linting

* use original queries from discussions list tool for testing

* linting

* remove logging

* Complete merge by re-introducing pagination to ListDiscussions

* fix unit tests

* refactor: less repetitive interface

---------

Co-authored-by: LuluBeatson <lulubeatson@github.com>
Co-authored-by: Lulu <59149422+LuluBeatson@users.noreply.github.com>
---
 README.md                      |   2 +
 pkg/github/discussions.go      | 306 ++++++++++++++++++---------------
 pkg/github/discussions_test.go | 241 ++++++++++++++++++++++++--
 3 files changed, 396 insertions(+), 153 deletions(-)

diff --git a/README.md b/README.md
index 39aa0157b..58f0e897e 100644
--- a/README.md
+++ b/README.md
@@ -462,6 +462,8 @@ The following sets of tools are available (all are on by default):
 - **list_discussions** - List discussions
   - `after`: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
   - `category`: Optional filter by discussion category ID. If provided, only discussions with this category are listed. (string, optional)
+  - `direction`: Order direction. (string, optional)
+  - `orderBy`: Order discussions by field. If provided, the 'direction' also needs to be provided. (string, optional)
   - `owner`: Repository owner (string, required)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
   - `repo`: Repository name (string, required)
diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go
index 2b8ccfb0b..fce07ecdb 100644
--- a/pkg/github/discussions.go
+++ b/pkg/github/discussions.go
@@ -15,6 +15,108 @@ import (
 
 const DefaultGraphQLPageSize = 30
 
+// Common interface for all discussion query types
+type DiscussionQueryResult interface {
+	GetDiscussionFragment() DiscussionFragment
+}
+
+// Implement the interface for all query types
+func (q *BasicNoOrder) GetDiscussionFragment() DiscussionFragment {
+	return q.Repository.Discussions
+}
+
+func (q *BasicWithOrder) GetDiscussionFragment() DiscussionFragment {
+	return q.Repository.Discussions
+}
+
+func (q *WithCategoryAndOrder) GetDiscussionFragment() DiscussionFragment {
+	return q.Repository.Discussions
+}
+
+func (q *WithCategoryNoOrder) GetDiscussionFragment() DiscussionFragment {
+	return q.Repository.Discussions
+}
+
+type DiscussionFragment struct {
+	Nodes      []NodeFragment
+	PageInfo   PageInfoFragment
+	TotalCount githubv4.Int
+}
+
+type NodeFragment struct {
+	Number    githubv4.Int
+	Title     githubv4.String
+	CreatedAt githubv4.DateTime
+	UpdatedAt githubv4.DateTime
+	Author    struct {
+		Login githubv4.String
+	}
+	Category struct {
+		Name githubv4.String
+	} `graphql:"category"`
+	URL githubv4.String `graphql:"url"`
+}
+
+type PageInfoFragment struct {
+	HasNextPage     bool
+	HasPreviousPage bool
+	StartCursor     githubv4.String
+	EndCursor       githubv4.String
+}
+
+type BasicNoOrder struct {
+	Repository struct {
+		Discussions DiscussionFragment `graphql:"discussions(first: $first, after: $after)"`
+	} `graphql:"repository(owner: $owner, name: $repo)"`
+}
+
+type BasicWithOrder struct {
+	Repository struct {
+		Discussions DiscussionFragment `graphql:"discussions(first: $first, after: $after, orderBy: { field: $orderByField, direction: $orderByDirection })"`
+	} `graphql:"repository(owner: $owner, name: $repo)"`
+}
+
+type WithCategoryAndOrder struct {
+	Repository struct {
+		Discussions DiscussionFragment `graphql:"discussions(first: $first, after: $after, categoryId: $categoryId, orderBy: { field: $orderByField, direction: $orderByDirection })"`
+	} `graphql:"repository(owner: $owner, name: $repo)"`
+}
+
+type WithCategoryNoOrder struct {
+	Repository struct {
+		Discussions DiscussionFragment `graphql:"discussions(first: $first, after: $after, categoryId: $categoryId)"`
+	} `graphql:"repository(owner: $owner, name: $repo)"`
+}
+
+func fragmentToDiscussion(fragment NodeFragment) *github.Discussion {
+	return &github.Discussion{
+		Number:    github.Ptr(int(fragment.Number)),
+		Title:     github.Ptr(string(fragment.Title)),
+		HTMLURL:   github.Ptr(string(fragment.URL)),
+		CreatedAt: &github.Timestamp{Time: fragment.CreatedAt.Time},
+		UpdatedAt: &github.Timestamp{Time: fragment.UpdatedAt.Time},
+		User: &github.User{
+			Login: github.Ptr(string(fragment.Author.Login)),
+		},
+		DiscussionCategory: &github.DiscussionCategory{
+			Name: github.Ptr(string(fragment.Category.Name)),
+		},
+	}
+}
+
+func getQueryType(useOrdering bool, categoryID *githubv4.ID) any {
+	if categoryID != nil && useOrdering {
+		return &WithCategoryAndOrder{}
+	}
+	if categoryID != nil && !useOrdering {
+		return &WithCategoryNoOrder{}
+	}
+	if categoryID == nil && useOrdering {
+		return &BasicWithOrder{}
+	}
+	return &BasicNoOrder{}
+}
+
 func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_discussions",
 			mcp.WithDescription(t("TOOL_LIST_DISCUSSIONS_DESCRIPTION", "List discussions for a repository")),
@@ -33,10 +135,17 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 			mcp.WithString("category",
 				mcp.Description("Optional filter by discussion category ID. If provided, only discussions with this category are listed."),
 			),
+			mcp.WithString("orderBy",
+				mcp.Description("Order discussions by field. If provided, the 'direction' also needs to be provided."),
+				mcp.Enum("CREATED_AT", "UPDATED_AT"),
+			),
+			mcp.WithString("direction",
+				mcp.Description("Order direction."),
+				mcp.Enum("ASC", "DESC"),
+			),
 			WithCursorPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-			// Required params
 			owner, err := RequiredParam[string](request, "owner")
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
@@ -46,12 +155,21 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 
-			// Optional params
 			category, err := OptionalParam[string](request, "category")
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 
+			orderBy, err := OptionalParam[string](request, "orderBy")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			direction, err := OptionalParam[string](request, "direction")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
 			// Get pagination parameters and convert to GraphQL format
 			pagination, err := OptionalCursorPaginationParams(request)
 			if err != nil {
@@ -67,155 +185,69 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 				return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil
 			}
 
-			// If category filter is specified, use it as the category ID for server-side filtering
 			var categoryID *githubv4.ID
 			if category != "" {
 				id := githubv4.ID(category)
 				categoryID = &id
 			}
 
-			var out []byte
-
-			var discussions []*github.Discussion
-			if categoryID != nil {
-				// Query with category filter (server-side filtering)
-				var query struct {
-					Repository struct {
-						Discussions struct {
-							Nodes []struct {
-								Number    githubv4.Int
-								Title     githubv4.String
-								CreatedAt githubv4.DateTime
-								Category  struct {
-									Name githubv4.String
-								} `graphql:"category"`
-								URL githubv4.String `graphql:"url"`
-							}
-							PageInfo struct {
-								HasNextPage     bool
-								HasPreviousPage bool
-								StartCursor     string
-								EndCursor       string
-							}
-							TotalCount int
-						} `graphql:"discussions(first: $first, after: $after, categoryId: $categoryId)"`
-					} `graphql:"repository(owner: $owner, name: $repo)"`
-				}
-				vars := map[string]interface{}{
-					"owner":      githubv4.String(owner),
-					"repo":       githubv4.String(repo),
-					"categoryId": *categoryID,
-					"first":      githubv4.Int(*paginationParams.First),
-				}
-				if paginationParams.After != nil {
-					vars["after"] = githubv4.String(*paginationParams.After)
-				} else {
-					vars["after"] = (*githubv4.String)(nil)
-				}
-				if err := client.Query(ctx, &query, vars); err != nil {
-					return mcp.NewToolResultError(err.Error()), nil
-				}
-
-				// Map nodes to GitHub Discussion objects
-				for _, n := range query.Repository.Discussions.Nodes {
-					di := &github.Discussion{
-						Number:    github.Ptr(int(n.Number)),
-						Title:     github.Ptr(string(n.Title)),
-						HTMLURL:   github.Ptr(string(n.URL)),
-						CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time},
-						DiscussionCategory: &github.DiscussionCategory{
-							Name: github.Ptr(string(n.Category.Name)),
-						},
-					}
-					discussions = append(discussions, di)
-				}
+			vars := map[string]interface{}{
+				"owner": githubv4.String(owner),
+				"repo":  githubv4.String(repo),
+				"first": githubv4.Int(*paginationParams.First),
+			}
+			if paginationParams.After != nil {
+				vars["after"] = githubv4.String(*paginationParams.After)
+			} else {
+				vars["after"] = (*githubv4.String)(nil)
+			}
 
-				// Create response with pagination info
-				response := map[string]interface{}{
-					"discussions": discussions,
-					"pageInfo": map[string]interface{}{
-						"hasNextPage":     query.Repository.Discussions.PageInfo.HasNextPage,
-						"hasPreviousPage": query.Repository.Discussions.PageInfo.HasPreviousPage,
-						"startCursor":     query.Repository.Discussions.PageInfo.StartCursor,
-						"endCursor":       query.Repository.Discussions.PageInfo.EndCursor,
-					},
-					"totalCount": query.Repository.Discussions.TotalCount,
-				}
+			// this is an extra check in case the tool description is misinterpreted, because
+			// we shouldn't use ordering unless both a 'field' and 'direction' are provided
+			useOrdering := orderBy != "" && direction != ""
+			if useOrdering {
+				vars["orderByField"] = githubv4.DiscussionOrderField(orderBy)
+				vars["orderByDirection"] = githubv4.OrderDirection(direction)
+			}
 
-				out, err = json.Marshal(response)
-				if err != nil {
-					return nil, fmt.Errorf("failed to marshal discussions: %w", err)
-				}
-			} else {
-				// Query without category filter
-				var query struct {
-					Repository struct {
-						Discussions struct {
-							Nodes []struct {
-								Number    githubv4.Int
-								Title     githubv4.String
-								CreatedAt githubv4.DateTime
-								Category  struct {
-									Name githubv4.String
-								} `graphql:"category"`
-								URL githubv4.String `graphql:"url"`
-							}
-							PageInfo struct {
-								HasNextPage     bool
-								HasPreviousPage bool
-								StartCursor     string
-								EndCursor       string
-							}
-							TotalCount int
-						} `graphql:"discussions(first: $first, after: $after)"`
-					} `graphql:"repository(owner: $owner, name: $repo)"`
-				}
-				vars := map[string]interface{}{
-					"owner": githubv4.String(owner),
-					"repo":  githubv4.String(repo),
-					"first": githubv4.Int(*paginationParams.First),
-				}
-				if paginationParams.After != nil {
-					vars["after"] = githubv4.String(*paginationParams.After)
-				} else {
-					vars["after"] = (*githubv4.String)(nil)
-				}
-				if err := client.Query(ctx, &query, vars); err != nil {
-					return mcp.NewToolResultError(err.Error()), nil
-				}
+			if categoryID != nil {
+				vars["categoryId"] = *categoryID
+			}
 
-				// Map nodes to GitHub Discussion objects
-				for _, n := range query.Repository.Discussions.Nodes {
-					di := &github.Discussion{
-						Number:    github.Ptr(int(n.Number)),
-						Title:     github.Ptr(string(n.Title)),
-						HTMLURL:   github.Ptr(string(n.URL)),
-						CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time},
-						DiscussionCategory: &github.DiscussionCategory{
-							Name: github.Ptr(string(n.Category.Name)),
-						},
-					}
-					discussions = append(discussions, di)
-				}
+			discussionQuery := getQueryType(useOrdering, categoryID)
+			if err := client.Query(ctx, discussionQuery, vars); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
 
-				// Create response with pagination info
-				response := map[string]interface{}{
-					"discussions": discussions,
-					"pageInfo": map[string]interface{}{
-						"hasNextPage":     query.Repository.Discussions.PageInfo.HasNextPage,
-						"hasPreviousPage": query.Repository.Discussions.PageInfo.HasPreviousPage,
-						"startCursor":     query.Repository.Discussions.PageInfo.StartCursor,
-						"endCursor":       query.Repository.Discussions.PageInfo.EndCursor,
-					},
-					"totalCount": query.Repository.Discussions.TotalCount,
+			// Extract and convert all discussion nodes using the common interface
+			var discussions []*github.Discussion
+			var pageInfo PageInfoFragment
+			var totalCount githubv4.Int
+			if queryResult, ok := discussionQuery.(DiscussionQueryResult); ok {
+				fragment := queryResult.GetDiscussionFragment()
+				for _, node := range fragment.Nodes {
+					discussions = append(discussions, fragmentToDiscussion(node))
 				}
+				pageInfo = fragment.PageInfo
+				totalCount = fragment.TotalCount
+			}
 
-				out, err = json.Marshal(response)
-				if err != nil {
-					return nil, fmt.Errorf("failed to marshal discussions: %w", err)
-				}
+			// Create response with pagination info
+			response := map[string]interface{}{
+				"discussions": discussions,
+				"pageInfo": map[string]interface{}{
+					"hasNextPage":     pageInfo.HasNextPage,
+					"hasPreviousPage": pageInfo.HasPreviousPage,
+					"startCursor":     string(pageInfo.StartCursor),
+					"endCursor":       string(pageInfo.EndCursor),
+				},
+				"totalCount": totalCount,
 			}
 
+			out, err := json.Marshal(response)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal discussions: %w", err)
+			}
 			return mcp.NewToolResultText(string(out)), nil
 		}
 }
diff --git a/pkg/github/discussions_test.go b/pkg/github/discussions_test.go
index e2e3d99ed..aefaf2f8c 100644
--- a/pkg/github/discussions_test.go
+++ b/pkg/github/discussions_test.go
@@ -17,14 +17,58 @@ import (
 
 var (
 	discussionsGeneral = []map[string]any{
-		{"number": 1, "title": "Discussion 1 title", "createdAt": "2023-01-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/1", "category": map[string]any{"name": "General"}},
-		{"number": 3, "title": "Discussion 3 title", "createdAt": "2023-03-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/3", "category": map[string]any{"name": "General"}},
+		{"number": 1, "title": "Discussion 1 title", "createdAt": "2023-01-01T00:00:00Z", "updatedAt": "2023-01-01T00:00:00Z", "author": map[string]any{"login": "user1"}, "url": "https://github.com/owner/repo/discussions/1", "category": map[string]any{"name": "General"}},
+		{"number": 3, "title": "Discussion 3 title", "createdAt": "2023-03-01T00:00:00Z", "updatedAt": "2023-02-01T00:00:00Z", "author": map[string]any{"login": "user1"}, "url": "https://github.com/owner/repo/discussions/3", "category": map[string]any{"name": "General"}},
 	}
 	discussionsAll = []map[string]any{
-		{"number": 1, "title": "Discussion 1 title", "createdAt": "2023-01-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/1", "category": map[string]any{"name": "General"}},
-		{"number": 2, "title": "Discussion 2 title", "createdAt": "2023-02-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/2", "category": map[string]any{"name": "Questions"}},
-		{"number": 3, "title": "Discussion 3 title", "createdAt": "2023-03-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/3", "category": map[string]any{"name": "General"}},
+		{
+			"number":    1,
+			"title":     "Discussion 1 title",
+			"createdAt": "2023-01-01T00:00:00Z",
+			"updatedAt": "2023-01-01T00:00:00Z",
+			"author":    map[string]any{"login": "user1"},
+			"url":       "https://github.com/owner/repo/discussions/1",
+			"category":  map[string]any{"name": "General"},
+		},
+		{
+			"number":    2,
+			"title":     "Discussion 2 title",
+			"createdAt": "2023-02-01T00:00:00Z",
+			"updatedAt": "2023-02-01T00:00:00Z",
+			"author":    map[string]any{"login": "user2"},
+			"url":       "https://github.com/owner/repo/discussions/2",
+			"category":  map[string]any{"name": "Questions"},
+		},
+		{
+			"number":    3,
+			"title":     "Discussion 3 title",
+			"createdAt": "2023-03-01T00:00:00Z",
+			"updatedAt": "2023-03-01T00:00:00Z",
+			"author":    map[string]any{"login": "user3"},
+			"url":       "https://github.com/owner/repo/discussions/3",
+			"category":  map[string]any{"name": "General"},
+		},
+	}
+
+	// Ordered mock responses
+	discussionsOrderedCreatedAsc = []map[string]any{
+		discussionsAll[0], // Discussion 1 (created 2023-01-01)
+		discussionsAll[1], // Discussion 2 (created 2023-02-01)
+		discussionsAll[2], // Discussion 3 (created 2023-03-01)
+	}
+
+	discussionsOrderedUpdatedDesc = []map[string]any{
+		discussionsAll[2], // Discussion 3 (updated 2023-03-01)
+		discussionsAll[1], // Discussion 2 (updated 2023-02-01)
+		discussionsAll[0], // Discussion 1 (updated 2023-01-01)
 	}
+
+	// only 'General' category discussions ordered by created date descending
+	discussionsGeneralOrderedDesc = []map[string]any{
+		discussionsGeneral[1], // Discussion 3 (created 2023-03-01)
+		discussionsGeneral[0], // Discussion 1 (created 2023-01-01)
+	}
+
 	mockResponseListAll = githubv4mock.DataResponse(map[string]any{
 		"repository": map[string]any{
 			"discussions": map[string]any{
@@ -53,24 +97,62 @@ var (
 			},
 		},
 	})
+	mockResponseOrderedCreatedAsc = githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussions": map[string]any{
+				"nodes": discussionsOrderedCreatedAsc,
+				"pageInfo": map[string]any{
+					"hasNextPage":     false,
+					"hasPreviousPage": false,
+					"startCursor":     "",
+					"endCursor":       "",
+				},
+				"totalCount": 3,
+			},
+		},
+	})
+	mockResponseOrderedUpdatedDesc = githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussions": map[string]any{
+				"nodes": discussionsOrderedUpdatedDesc,
+				"pageInfo": map[string]any{
+					"hasNextPage":     false,
+					"hasPreviousPage": false,
+					"startCursor":     "",
+					"endCursor":       "",
+				},
+				"totalCount": 3,
+			},
+		},
+	})
+	mockResponseGeneralOrderedDesc = githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussions": map[string]any{
+				"nodes": discussionsGeneralOrderedDesc,
+				"pageInfo": map[string]any{
+					"hasNextPage":     false,
+					"hasPreviousPage": false,
+					"startCursor":     "",
+					"endCursor":       "",
+				},
+				"totalCount": 2,
+			},
+		},
+	})
 	mockErrorRepoNotFound = githubv4mock.ErrorResponse("repository not found")
 )
 
 func Test_ListDiscussions(t *testing.T) {
 	mockClient := githubv4.NewClient(nil)
-	// Verify tool definition and schema
 	toolDef, _ := ListDiscussions(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper)
 	assert.Equal(t, "list_discussions", toolDef.Name)
 	assert.NotEmpty(t, toolDef.Description)
 	assert.Contains(t, toolDef.InputSchema.Properties, "owner")
 	assert.Contains(t, toolDef.InputSchema.Properties, "repo")
+	assert.Contains(t, toolDef.InputSchema.Properties, "orderBy")
+	assert.Contains(t, toolDef.InputSchema.Properties, "direction")
 	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo"})
 
-	// Use exact string queries that match implementation output (from error messages)
-	qDiscussions := "query($after:String$first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after){nodes{number,title,createdAt,category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
-
-	qDiscussionsFiltered := "query($after:String$categoryId:ID!$first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after, categoryId: $categoryId){nodes{number,title,createdAt,category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
-
 	// Variables matching what GraphQL receives after JSON marshaling/unmarshaling
 	varsListAll := map[string]interface{}{
 		"owner": "owner",
@@ -94,12 +176,41 @@ func Test_ListDiscussions(t *testing.T) {
 		"after":      (*string)(nil),
 	}
 
+	varsOrderByCreatedAsc := map[string]interface{}{
+		"owner":            "owner",
+		"repo":             "repo",
+		"orderByField":     "CREATED_AT",
+		"orderByDirection": "ASC",
+		"first":            float64(30),
+		"after":            (*string)(nil),
+	}
+
+	varsOrderByUpdatedDesc := map[string]interface{}{
+		"owner":            "owner",
+		"repo":             "repo",
+		"orderByField":     "UPDATED_AT",
+		"orderByDirection": "DESC",
+		"first":            float64(30),
+		"after":            (*string)(nil),
+	}
+
+	varsCategoryWithOrder := map[string]interface{}{
+		"owner":            "owner",
+		"repo":             "repo",
+		"categoryId":       "DIC_kwDOABC123",
+		"orderByField":     "CREATED_AT",
+		"orderByDirection": "DESC",
+		"first":            float64(30),
+		"after":            (*string)(nil),
+	}
+
 	tests := []struct {
 		name          string
 		reqParams     map[string]interface{}
 		expectError   bool
 		errContains   string
 		expectedCount int
+		verifyOrder   func(t *testing.T, discussions []*github.Discussion)
 	}{
 		{
 			name: "list all discussions without category filter",
@@ -120,6 +231,80 @@ func Test_ListDiscussions(t *testing.T) {
 			expectError:   false,
 			expectedCount: 2, // Only General discussions (matching the category ID)
 		},
+		{
+			name: "order by created at ascending",
+			reqParams: map[string]interface{}{
+				"owner":     "owner",
+				"repo":      "repo",
+				"orderBy":   "CREATED_AT",
+				"direction": "ASC",
+			},
+			expectError:   false,
+			expectedCount: 3,
+			verifyOrder: func(t *testing.T, discussions []*github.Discussion) {
+				// Verify discussions are ordered by created date ascending
+				require.Len(t, discussions, 3)
+				assert.Equal(t, 1, *discussions[0].Number, "First should be discussion 1 (created 2023-01-01)")
+				assert.Equal(t, 2, *discussions[1].Number, "Second should be discussion 2 (created 2023-02-01)")
+				assert.Equal(t, 3, *discussions[2].Number, "Third should be discussion 3 (created 2023-03-01)")
+			},
+		},
+		{
+			name: "order by updated at descending",
+			reqParams: map[string]interface{}{
+				"owner":     "owner",
+				"repo":      "repo",
+				"orderBy":   "UPDATED_AT",
+				"direction": "DESC",
+			},
+			expectError:   false,
+			expectedCount: 3,
+			verifyOrder: func(t *testing.T, discussions []*github.Discussion) {
+				// Verify discussions are ordered by updated date descending
+				require.Len(t, discussions, 3)
+				assert.Equal(t, 3, *discussions[0].Number, "First should be discussion 3 (updated 2023-03-01)")
+				assert.Equal(t, 2, *discussions[1].Number, "Second should be discussion 2 (updated 2023-02-01)")
+				assert.Equal(t, 1, *discussions[2].Number, "Third should be discussion 1 (updated 2023-01-01)")
+			},
+		},
+		{
+			name: "filter by category with order",
+			reqParams: map[string]interface{}{
+				"owner":     "owner",
+				"repo":      "repo",
+				"category":  "DIC_kwDOABC123",
+				"orderBy":   "CREATED_AT",
+				"direction": "DESC",
+			},
+			expectError:   false,
+			expectedCount: 2,
+			verifyOrder: func(t *testing.T, discussions []*github.Discussion) {
+				// Verify only General discussions, ordered by created date descending
+				require.Len(t, discussions, 2)
+				assert.Equal(t, 3, *discussions[0].Number, "First should be discussion 3 (created 2023-03-01)")
+				assert.Equal(t, 1, *discussions[1].Number, "Second should be discussion 1 (created 2023-01-01)")
+			},
+		},
+		{
+			name: "order by without direction (should not use ordering)",
+			reqParams: map[string]interface{}{
+				"owner":   "owner",
+				"repo":    "repo",
+				"orderBy": "CREATED_AT",
+			},
+			expectError:   false,
+			expectedCount: 3,
+		},
+		{
+			name: "direction without order by (should not use ordering)",
+			reqParams: map[string]interface{}{
+				"owner":     "owner",
+				"repo":      "repo",
+				"direction": "DESC",
+			},
+			expectError:   false,
+			expectedCount: 3,
+		},
 		{
 			name: "repository not found error",
 			reqParams: map[string]interface{}{
@@ -131,21 +316,40 @@ func Test_ListDiscussions(t *testing.T) {
 		},
 	}
 
+	// Define the actual query strings that match the implementation
+	qBasicNoOrder := "query($after:String$first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after){nodes{number,title,createdAt,updatedAt,author{login},category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
+	qWithCategoryNoOrder := "query($after:String$categoryId:ID!$first:Int!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after, categoryId: $categoryId){nodes{number,title,createdAt,updatedAt,author{login},category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
+	qBasicWithOrder := "query($after:String$first:Int!$orderByDirection:OrderDirection!$orderByField:DiscussionOrderField!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after, orderBy: { field: $orderByField, direction: $orderByDirection }){nodes{number,title,createdAt,updatedAt,author{login},category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
+	qWithCategoryAndOrder := "query($after:String$categoryId:ID!$first:Int!$orderByDirection:OrderDirection!$orderByField:DiscussionOrderField!$owner:String!$repo:String!){repository(owner: $owner, name: $repo){discussions(first: $first, after: $after, categoryId: $categoryId, orderBy: { field: $orderByField, direction: $orderByDirection }){nodes{number,title,createdAt,updatedAt,author{login},category{name},url},pageInfo{hasNextPage,hasPreviousPage,startCursor,endCursor},totalCount}}}"
+
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			var httpClient *http.Client
 
 			switch tc.name {
 			case "list all discussions without category filter":
-				// Simple case - no category filter
-				matcher := githubv4mock.NewQueryMatcher(qDiscussions, varsListAll, mockResponseListAll)
+				matcher := githubv4mock.NewQueryMatcher(qBasicNoOrder, varsListAll, mockResponseListAll)
 				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
 			case "filter by category ID":
-				// Simple case - category filter using category ID directly
-				matcher := githubv4mock.NewQueryMatcher(qDiscussionsFiltered, varsDiscussionsFiltered, mockResponseListGeneral)
+				matcher := githubv4mock.NewQueryMatcher(qWithCategoryNoOrder, varsDiscussionsFiltered, mockResponseListGeneral)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "order by created at ascending":
+				matcher := githubv4mock.NewQueryMatcher(qBasicWithOrder, varsOrderByCreatedAsc, mockResponseOrderedCreatedAsc)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "order by updated at descending":
+				matcher := githubv4mock.NewQueryMatcher(qBasicWithOrder, varsOrderByUpdatedDesc, mockResponseOrderedUpdatedDesc)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "filter by category with order":
+				matcher := githubv4mock.NewQueryMatcher(qWithCategoryAndOrder, varsCategoryWithOrder, mockResponseGeneralOrderedDesc)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "order by without direction (should not use ordering)":
+				matcher := githubv4mock.NewQueryMatcher(qBasicNoOrder, varsListAll, mockResponseListAll)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "direction without order by (should not use ordering)":
+				matcher := githubv4mock.NewQueryMatcher(qBasicNoOrder, varsListAll, mockResponseListAll)
 				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
 			case "repository not found error":
-				matcher := githubv4mock.NewQueryMatcher(qDiscussions, varsRepoNotFound, mockErrorRepoNotFound)
+				matcher := githubv4mock.NewQueryMatcher(qBasicNoOrder, varsRepoNotFound, mockErrorRepoNotFound)
 				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
 			}
 
@@ -179,6 +383,11 @@ func Test_ListDiscussions(t *testing.T) {
 
 			assert.Len(t, response.Discussions, tc.expectedCount, "Expected %d discussions, got %d", tc.expectedCount, len(response.Discussions))
 
+			// Verify order if verifyOrder function is provided
+			if tc.verifyOrder != nil {
+				tc.verifyOrder(t, response.Discussions)
+			}
+
 			// Verify that all returned discussions have a category if filtered
 			if _, hasCategory := tc.reqParams["category"]; hasCategory {
 				for _, discussion := range response.Discussions {

From efef8ae27a1d62c38c8f760ca38a65845efd3576 Mon Sep 17 00:00:00 2001
From: JoannaaKL <joannaakl@github.com>
Date: Thu, 24 Jul 2025 12:35:35 +0200
Subject: [PATCH 32/32] Changed q to query in search (#740)

---
 README.md                                 |  2 +-
 pkg/github/__toolsnaps__/search_code.snap |  4 ++--
 pkg/github/search.go                      |  4 ++--
 pkg/github/search_test.go                 | 10 +++++-----
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 58f0e897e..be9288e40 100644
--- a/README.md
+++ b/README.md
@@ -838,7 +838,7 @@ The following sets of tools are available (all are on by default):
   - `order`: Sort order (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `q`: Search query using GitHub code search syntax (string, required)
+  - `query`: Search query using GitHub code search syntax (string, required)
   - `sort`: Sort field ('indexed' only) (string, optional)
 
 - **search_repositories** - Search repositories
diff --git a/pkg/github/__toolsnaps__/search_code.snap b/pkg/github/__toolsnaps__/search_code.snap
index c85d6674d..e341f3e38 100644
--- a/pkg/github/__toolsnaps__/search_code.snap
+++ b/pkg/github/__toolsnaps__/search_code.snap
@@ -25,7 +25,7 @@
         "minimum": 1,
         "type": "number"
       },
-      "q": {
+      "query": {
         "description": "Search query using GitHub code search syntax",
         "type": "string"
       },
@@ -35,7 +35,7 @@
       }
     },
     "required": [
-      "q"
+      "query"
     ],
     "type": "object"
   },
diff --git a/pkg/github/search.go b/pkg/github/search.go
index b11bb3bbc..476ac0151 100644
--- a/pkg/github/search.go
+++ b/pkg/github/search.go
@@ -83,7 +83,7 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to
 				Title:        t("TOOL_SEARCH_CODE_USER_TITLE", "Search code"),
 				ReadOnlyHint: ToBoolPtr(true),
 			}),
-			mcp.WithString("q",
+			mcp.WithString("query",
 				mcp.Required(),
 				mcp.Description("Search query using GitHub code search syntax"),
 			),
@@ -97,7 +97,7 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to
 			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-			query, err := RequiredParam[string](request, "q")
+			query, err := RequiredParam[string](request, "query")
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
diff --git a/pkg/github/search_test.go b/pkg/github/search_test.go
index 21f7a0ca2..9ea8e71ec 100644
--- a/pkg/github/search_test.go
+++ b/pkg/github/search_test.go
@@ -173,12 +173,12 @@ func Test_SearchCode(t *testing.T) {
 
 	assert.Equal(t, "search_code", tool.Name)
 	assert.NotEmpty(t, tool.Description)
-	assert.Contains(t, tool.InputSchema.Properties, "q")
+	assert.Contains(t, tool.InputSchema.Properties, "query")
 	assert.Contains(t, tool.InputSchema.Properties, "sort")
 	assert.Contains(t, tool.InputSchema.Properties, "order")
 	assert.Contains(t, tool.InputSchema.Properties, "perPage")
 	assert.Contains(t, tool.InputSchema.Properties, "page")
-	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"q"})
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"query"})
 
 	// Setup mock search results
 	mockSearchResult := &github.CodeSearchResult{
@@ -227,7 +227,7 @@ func Test_SearchCode(t *testing.T) {
 				),
 			),
 			requestArgs: map[string]interface{}{
-				"q":       "fmt.Println language:go",
+				"query":   "fmt.Println language:go",
 				"sort":    "indexed",
 				"order":   "desc",
 				"page":    float64(1),
@@ -251,7 +251,7 @@ func Test_SearchCode(t *testing.T) {
 				),
 			),
 			requestArgs: map[string]interface{}{
-				"q": "fmt.Println language:go",
+				"query": "fmt.Println language:go",
 			},
 			expectError:    false,
 			expectedResult: mockSearchResult,
@@ -268,7 +268,7 @@ func Test_SearchCode(t *testing.T) {
 				),
 			),
 			requestArgs: map[string]interface{}{
-				"q": "invalid:query",
+				"query": "invalid:query",
 			},
 			expectError:    true,
 			expectedErrMsg: "failed to search code",

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://rainy.clevelandohioweatherforecast.com/php-proxy/index.php?q=https://github.com/github/github-mcp-server/compare/github:721fd3e...github:efef8ae.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/index.php?u=https://github.com/github/github-mcp-server/compare/github:721fd3e...github:efef8ae.patch" target="_blank">pFad Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v3index.php?u=https://github.com/github/github-mcp-server/compare/github:721fd3e...github:efef8ae.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v4index.php?u=https://github.com/github/github-mcp-server/compare/github:721fd3e...github:efef8ae.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>