feat: add line range support to get_file_contents tool

README.md

@@ -15,6 +15,66 @@ 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.
+
+## 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.
+
 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)).
@@ -519,14 +579,16 @@ 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)
   - `path`: Only commits containing this file path (string, optional)
   - `page`: Page number (number, optional)
   - `perPage`: Results per page (number, optional)
 
+### Search
+
 - **get_commit** - Get details for a commit from a repository
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
@@ -641,3 +703,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.
+

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"
@@ -411,7 +414,7 @@ func CreateRepository(getClient GetClientFn, t translations.TranslationHelperFun
 // GetFileContents creates a tool to get the contents of a file or directory from a GitHub repository.
 func GetFileContents(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("get_file_contents",
-			mcp.WithDescription(t("TOOL_GET_FILE_CONTENTS_DESCRIPTION", "Get the contents of a file or directory from a GitHub repository")),
+			mcp.WithDescription(t("TOOL_GET_FILE_CONTENTS_DESCRIPTION", "Get the contents of a file or directory from a GitHub repository. If 'begin' and/or 'end' are provided, only those lines will be returned (1-indexed, inclusive). If the path is a directory, line ranges are ignored and directory listing is returned. If 'begin'/'end' are provided but the path is a directory, an error is returned. If the file content is not base64 encoded, it will not be re-encoded.")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
 				Title:        t("TOOL_GET_FILE_CONTENTS_USER_TITLE", "Get file or directory contents"),
 				ReadOnlyHint: toBoolPtr(true),
@@ -431,6 +434,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")
@@ -449,6 +458,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 {
@@ -471,7 +488,73 @@ func GetFileContents(getClient GetClientFn, t translations.TranslationHelperFunc
 
 			var result interface{}
 			if fileContent != nil {
-				result = fileContent
+				if fileContent.Content != nil && (begin > 0 || end > 0) {
+					// Only process line ranges for files, not directories
+					if fileContent.Encoding != nil && *fileContent.Encoding == "base64" {
+						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)
+						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))),
+							Encoding: github.Ptr("base64"),
+						}
+					} else {
+						// If not base64, just return the ranged lines as plain text
+						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)
+						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 = joined
+					}
+				} else {
+					result = fileContent
+				}
+			} else if (begin > 0 || end > 0) && dirContent != nil {
+				// If begin/end are provided but path is a directory, return an error
+				return mcp.NewToolResultError("Cannot use 'begin' or 'end' with a directory path. These parameters are only valid for files."), nil
 			} else {
 				result = dirContent
 			}

pkg/github/repositories_test.go

@@ -126,6 +126,81 @@ func Test_GetFileContents(t *testing.T) {
 			expectError:    true,
 			expectedErrMsg: "failed to get file contents",
 		},
+		{
+			name: "begin/end with file (base64)",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposContentsByOwnerByRepoByPath,
+					expectQueryParams(t, map[string]string{}).andThen(
+						mockResponse(t, http.StatusOK, &github.RepositoryContent{
+							Type:     github.Ptr("file"),
+							Name:     github.Ptr("test.txt"),
+							Path:     github.Ptr("test.txt"),
+							Content:  github.Ptr("SGVsbG8KQmFyCkJheg=="), // Base64 for "Hello\nBar\nBaz"
+							Encoding: github.Ptr("base64"),
+						}),
+					),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+				"path":  "test.txt",
+				"begin": 2,
+				"end":   3,
+			},
+			expectError: false,
+			expectedResult: &github.RepositoryContent{
+				Content:  github.Ptr("QmFyCkJheg=="), // Base64 for "Bar\nBaz"
+				Encoding: github.Ptr("base64"),
+			},
+		},
+		{
+			name: "begin/end with directory (should error)",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposContentsByOwnerByRepoByPath,
+					expectQueryParams(t, map[string]string{}).andThen(
+						mockResponse(t, http.StatusOK, []*github.RepositoryContent{{Type: github.Ptr("file"), Name: github.Ptr("foo.txt"), Path: github.Ptr("foo.txt")}}),
+					),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+				"path":  "src",
+				"begin": 1,
+				"end":   2,
+			},
+			expectError:    true,
+			expectedErrMsg: "Cannot use 'begin' or 'end' with a directory path",
+		},
+		{
+			name: "file with non-base64 encoding",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposContentsByOwnerByRepoByPath,
+					expectQueryParams(t, map[string]string{}).andThen(
+						mockResponse(t, http.StatusOK, &github.RepositoryContent{
+							Type:     github.Ptr("file"),
+							Name:     github.Ptr("plain.txt"),
+							Path:     github.Ptr("plain.txt"),
+							Content:  github.Ptr("Hello\nWorld\nTest"),
+							Encoding: github.Ptr("utf-8"),
+						}),
+					),
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+				"path":  "plain.txt",
+				"begin": 2,
+				"end":   3,
+			},
+			expectError:    false,
+			expectedResult: "World\nTest",
+		},
 	}
 
 	for _, tc := range tests {