Merge branch 'main' into feat/259/assign-reviewers

Author: MayorFaj

CONTRIBUTING.md

@@ -14,20 +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
 
-> **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. 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:
 

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>
 
@@ -871,7 +871,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)
@@ -903,7 +903,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)
@@ -917,12 +917,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)

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

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"
       }
     },

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"
       }
     },

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"

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"
       }
     },

pkg/github/context_tools.go

@@ -2,24 +2,44 @@ package github
 
 import (
 	"context"
+	"time"
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/mark3labs/mcp-go/mcp"
 	"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",
-		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{}
@@ -38,7 +58,34 @@ func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Too
 			), nil
 		}
 
-		return MarshalledTextResult(user), nil
+		// Create minimal user representation instead of returning full user object
+		minimalUser := MinimalUser{
+			Login:      user.GetLogin(),
+			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
 	})
 
 	return tool, handler

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"),
 		},
@@ -117,17 +119,23 @@ 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 minimal user details
+			assert.Equal(t, *tc.expectedUser.Login, returnedUser.Login)
+			assert.Equal(t, *tc.expectedUser.HTMLURL, returnedUser.ProfileURL)
+
 			// 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)
+			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)
 		})
 	}
 }

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)