Merge branch 'main' into feat/go-github-v73

Author: tommaso-moro

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:
 

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>
 
@@ -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)
@@ -899,10 +899,10 @@ 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 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)
@@ -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.

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

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.

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

@@ -11,6 +11,7 @@
         "type": "string"
       },
       "path": {
+        "default": "/",
         "description": "Path to file/directory (directories must end with a slash '/')",
         "type": "string"
       },
@@ -23,14 +24,13 @@
         "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"
       }
     },
     "required": [
       "owner",
-      "repo",
-      "path"
+      "repo"
     ],
     "type": "object"
   },

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/__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": {

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{}