From 275d31525a3bf410b21374f8c5ab3e172bf2d485 Mon Sep 17 00:00:00 2001 From: Arya Soni Date: Fri, 11 Apr 2025 23:02:42 +0530 Subject: [PATCH 1/2] docs: add required GitHub token permissions per action (#128) --- README.md | 79 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 00f49b64..f423c869 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,67 @@ automation and interaction capabilities for developers and tools. ## 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. -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)). +2. [Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new). + Each tool requires specific permissions to function. See the [Required Token Permissions](#required-token-permissions) section below for details. +## Required Token Permissions +Each tool requires specific GitHub Personal Access Token permissions to function. Below are the required permissions for each tool category: + +### Users +- **get_me** + - Required permissions: + - `read:user` - Read access to profile info + +### Issues +- **get_issue**, **get_issue_comments**, **list_issues** + - Required permissions: + - `repo` - Full control of private repositories (for private repos) + - `public_repo` - Access public repositories (for public repos) + +- **create_issue**, **add_issue_comment**, **update_issue** + - Required permissions: + - `repo` - Full control of private repositories (for private repos) + - `public_repo` - Access public repositories (for public repos) + - `write:discussion` - Write access to repository discussions (if using discussions) + +### Pull Requests +- **get_pull_request**, **list_pull_requests**, **get_pull_request_files**, **get_pull_request_status** + - Required permissions: + - `repo` - Full control of private repositories (for private repos) + - `public_repo` - Access public repositories (for public repos) + +- **merge_pull_request**, **update_pull_request_branch**, **create_pull_request**, **update_pull_request** + - Required permissions: + - `repo` - Full control of private repositories (for private repos) + - `public_repo` - Access public repositories (for public repos) + - `write:discussion` - Write access to repository discussions (if using discussions) + +### Repositories +- **get_file_contents**, **search_repositories**, **list_commits** + - Required permissions: + - `repo` - Full control of private repositories (for private repos) + - `public_repo` - Access public repositories (for public repos) + +- **create_or_update_file**, **push_files**, **create_repository**, **fork_repository**, **create_branch** + - Required permissions: + - `repo` - Full control of private repositories (for private repos) + - `public_repo` - Access public repositories (for public repos) + - `delete_repo` - Delete repositories (if needed) + +### Search +- **search_code**, **search_users** + - Required permissions: + - No special permissions required for public data + - `repo` - Required for searching private repositories + +### Code Scanning +- **get_code_scanning_alert**, **list_code_scanning_alerts** + - Required permissions: + - `security_events` - Read and write security events + - `repo` - Full control of private repositories (for private repos) + +Note: For organization repositories, additional organization-specific permissions may be required. ## Installation @@ -311,13 +367,6 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description - `branch`: Branch name (string, optional) - `sha`: File SHA if updating (string, optional) -- **list_branches** - List branches in a GitHub repository - - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - - **push_files** - Push multiple files in a single commit - `owner`: Repository owner (string, required) @@ -361,7 +410,7 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description - `branch`: New branch name (string, required) - `sha`: SHA to create branch from (string, required) -- **list_commits** - Get a list of commits of a branch in a repository +- **list_commits** - Gets commits of a branch in a repository - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - `sha`: Branch name, tag, or commit SHA (string, optional) @@ -369,13 +418,6 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description - `page`: Page number (number, optional) - `perPage`: Results per page (number, optional) -- **get_commit** - Get details for a commit from a repository - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `sha`: Commit SHA, branch name, or tag name (string, required) - - `page`: Page number, for files in the commit (number, optional) - - `perPage`: Results per page, for files in the commit (number, optional) - ### Search - **search_code** - Search for code across GitHub repositories @@ -468,3 +510,4 @@ The exported Go API of this module should currently be considered unstable, and ## License This project is licensed under the terms of the MIT open source license. Please refer to [MIT](./LICENSE) for the full terms. + From 2e797d8801960781d87588db4b124b0fe55b6d93 Mon Sep 17 00:00:00 2001 From: Arya Soni Date: Sat, 26 Apr 2025 21:31:35 +0530 Subject: [PATCH 2/2] feat: add line range support to get_file_contents tool --- pkg/github/repositories.go | 51 +++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go index 51948730..65308b9e 100644 --- a/pkg/github/repositories.go +++ b/pkg/github/repositories.go @@ -6,6 +6,9 @@ import ( "fmt" "io" "net/http" + "strings" + + "encoding/base64" "github.com/github/github-mcp-server/pkg/translations" "github.com/google/go-github/v69/github" @@ -407,6 +410,12 @@ func GetFileContents(getClient GetClientFn, t translations.TranslationHelperFunc mcp.WithString("branch", mcp.Description("Branch to get contents from"), ), + mcp.WithNumber("begin", + mcp.Description("Begin line number (1-indexed, optional)"), + ), + mcp.WithNumber("end", + mcp.Description("End line number (1-indexed, optional)"), + ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { owner, err := requiredParam[string](request, "owner") @@ -425,6 +434,14 @@ func GetFileContents(getClient GetClientFn, t translations.TranslationHelperFunc if err != nil { return mcp.NewToolResultError(err.Error()), nil } + begin, err := OptionalIntParam(request, "begin") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + end, err := OptionalIntParam(request, "end") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } client, err := getClient(ctx) if err != nil { @@ -447,7 +464,39 @@ func GetFileContents(getClient GetClientFn, t translations.TranslationHelperFunc var result interface{} if fileContent != nil { - result = fileContent + if fileContent.Content != nil && (begin > 0 || end > 0) { + decoded, err := fileContent.GetContent() + if err != nil { + return nil, fmt.Errorf("failed to decode file content: %w", err) + } + lines := strings.Split(decoded, "\n") + totalLines := len(lines) + // Adjust indices for 1-based input + startIdx := begin - 1 + if startIdx < 0 { + startIdx = 0 + } + endIdx := end + if endIdx <= 0 || endIdx > totalLines { + endIdx = totalLines + } + if startIdx >= totalLines { + startIdx = totalLines - 1 + } + if startIdx < 0 { + startIdx = 0 + } + if endIdx < startIdx { + endIdx = startIdx + } + ranged := lines[startIdx:endIdx] + joined := strings.Join(ranged, "\n") + result = &github.RepositoryContent{ + Content: github.Ptr(base64.StdEncoding.EncodeToString([]byte(joined))), + } + } else { + result = fileContent + } } else { result = dirContent }