feat: Add list_branches tool to view repository branches (#141)

Author: aryasoni98

pkg/github/repositories.go

@@ -610,3 +610,70 @@ func pushFiles(client *github.Client, t translations.TranslationHelperFunc) (too
 			return mcp.NewToolResultText(string(r)), nil
 		}
 }
+
+// listBranches creates a tool to list branches in a repository.
+func listBranches(client *github.Client, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("list_branches",
+			mcp.WithDescription(t("TOOL_LIST_BRANCHES_DESCRIPTION", "List branches in a GitHub repository")),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithNumber("page",
+				mcp.Description("Page number"),
+			),
+			mcp.WithNumber("perPage",
+				mcp.Description("Results per page"),
+			),
+		),
+		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
+			}
+			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
+			}
+
+			opts := &github.BranchListOptions{
+				ListOptions: github.ListOptions{
+					Page:    page,
+					PerPage: perPage,
+				},
+			}
+
+			branches, resp, err := client.Repositories.ListBranches(ctx, owner, repo, opts)
+			if err != nil {
+				return nil, fmt.Errorf("failed to list branches: %w", err)
+			}
+			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 branches: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(branches)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal response: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}

pkg/github/repositories_test.go

@@ -1293,3 +1293,118 @@ func Test_PushFiles(t *testing.T) {
 		})
 	}
 }
+
+func Test_ListBranches(t *testing.T) {
+	// Verify tool definition once
+	mockClient := github.NewClient(nil)
+	tool, _ := listBranches(mockClient, translations.NullTranslationHelper)
+
+	assert.Equal(t, "list_branches", 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, "page")
+	assert.Contains(t, tool.InputSchema.Properties, "perPage")
+	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"})
+
+	// Setup mock branches for success case
+	mockBranches := []*github.Branch{
+		{
+			Name:   github.Ptr("main"),
+			Commit: &github.RepositoryCommit{SHA: github.Ptr("abc123")},
+		},
+		{
+			Name:   github.Ptr("develop"),
+			Commit: &github.RepositoryCommit{SHA: github.Ptr("def456")},
+		},
+	}
+
+	// Define test cases
+	tests := []struct {
+		name           string
+		mockedClient   *http.Client
+		requestArgs    map[string]interface{}
+		expectError    bool
+		expectedErrMsg string
+	}{
+		{
+			name: "success",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatch(
+					mock.GetReposBranchesByOwnerByRepo,
+					mockBranches,
+				),
+			),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+				"repo":  "repo",
+			},
+			expectError: false,
+		},
+		{
+			name:         "missing owner",
+			mockedClient: mock.NewMockedHTTPClient(),
+			requestArgs: map[string]interface{}{
+				"repo": "repo",
+			},
+			expectError:    false,
+			expectedErrMsg: "owner is required",
+		},
+		{
+			name:         "missing repo",
+			mockedClient: mock.NewMockedHTTPClient(),
+			requestArgs: map[string]interface{}{
+				"owner": "owner",
+			},
+			expectError:    false,
+			expectedErrMsg: "repo is required",
+		},
+		{
+			name: "repository not found",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.GetReposBranchesByOwnerByRepo,
+					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":  "nonexistent-repo",
+			},
+			expectError:    true,
+			expectedErrMsg: "failed to list branches",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			client := github.NewClient(tt.mockedClient)
+			_, handler := listBranches(client, translations.NullTranslationHelper)
+
+			// Create call request using helper function
+			request := createMCPRequest(tt.requestArgs)
+
+			// Call handler
+			result, err := handler(context.Background(), request)
+
+			if tt.expectError {
+				assert.Error(t, err)
+				assert.Contains(t, err.Error(), tt.expectedErrMsg)
+			} else {
+				if tt.expectedErrMsg != "" {
+					assert.NotNil(t, result)
+					textContent := getTextResult(t, result)
+					assert.Contains(t, textContent.Text, tt.expectedErrMsg)
+				} else {
+					assert.NoError(t, err)
+					assert.NotNil(t, result)
+					textContent := getTextResult(t, result)
+					assert.NotEmpty(t, textContent.Text)
+				}
+			}
+		})
+	}
+}

pkg/github/server.go

@@ -59,6 +59,7 @@ func NewServer(client *github.Client, readOnly bool, t translations.TranslationH
 	s.AddTool(searchRepositories(client, t))
 	s.AddTool(getFileContents(client, t))
 	s.AddTool(listCommits(client, t))
+	s.AddTool(listBranches(client, t))
 	if !readOnly {
 		s.AddTool(createOrUpdateFile(client, t))
 		s.AddTool(createRepository(client, t))