update: getOrgMembers

Author: cointem

pkg/github/__toolsnaps__/get_org_members.snap

@@ -0,0 +1,32 @@
+{
+  "annotations": {
+    "title": "Get organization members",
+    "readOnlyHint": true
+  },
+  "description": "Get member users of a specific organization. Returns a list of user objects with fields: login, id, avatar_url, type. Limited to organizations accessible with current credentials",
+  "inputSchema": {
+    "properties": {
+      "org": {
+        "description": "Organization login (owner) to get members for.",
+        "type": "string"
+      }
+      ,"role": {
+        "description": "Filter by role: all, admin, member",
+        "type": "string"
+      },
+      "per_page": {
+        "description": "Results per page (max 100)",
+        "type": "number"
+      },
+      "page": {
+        "description": "Page number for pagination",
+        "type": "number"
+      }
+    },
+    "required": [
+      "org"
+    ],
+    "type": "object"
+  },
+  "name": "get_org_members"
+}

pkg/github/context_tools.go

@@ -2,10 +2,14 @@ package github
 
 import (
 	"context"
+	"fmt"
+	"strings"
 	"time"
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/go-viper/mapstructure/v2"
+	"github.com/google/go-github/v79/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 	"github.com/shurcooL/githubv4"
@@ -249,3 +253,99 @@ func GetTeamMembers(getGQLClient GetGQLClientFn, t translations.TranslationHelpe
 			return MarshalledTextResult(members), nil
 		}
 }
+
+func getOrgMembers(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) {
+	return mcp.NewTool("get_org_members",
+			mcp.WithDescription(t("TOOL_GET_ORG_MEMBERS_DESCRIPTION", "Get member users of a specific organization. Returns a list of user objects with fields: login, id, avatar_url, type. Limited to organizations accessible with current credentials")),
+			mcp.WithString("org",
+				mcp.Description(t("TOOL_GET_ORG_MEMBERS_ORG_DESCRIPTION", "Organization login (owner) to get members for.")),
+				mcp.Required(),
+			),
+			mcp.WithString("role",
+				mcp.Description("Filter by role: all, admin, member"),
+			),
+			mcp.WithNumber("per_page",
+				mcp.Description("Results per page (max 100)"),
+			),
+			mcp.WithNumber("page",
+				mcp.Description("Page number for pagination"),
+			),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_GET_ORG_MEMBERS_TITLE", "Get organization members"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			// Decode params into struct to support optional numbers
+			var params struct {
+				Org     string `mapstructure:"org"`
+				Role    string `mapstructure:"role"`
+				PerPage int32  `mapstructure:"per_page"`
+				Page    int32  `mapstructure:"page"`
+			}
+			if err := mapstructure.Decode(request.Params.Arguments, &params); err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			org := params.Org
+			role := params.Role
+			perPage := params.PerPage
+			page := params.Page
+			if org == "" {
+				return mcp.NewToolResultError("org is required"), nil
+			}
+
+			// Defaults
+			if perPage <= 0 {
+				perPage = 30
+			}
+			if perPage > 100 {
+				perPage = 100
+			}
+			if page <= 0 {
+				page = 1
+			}
+			client, err := getClient(ctx)
+			if err != nil {
+				return mcp.NewToolResultErrorFromErr("failed to get GitHub client", err), nil
+			}
+
+			// Map role string to REST role filter expected by GitHub API ("all","admin","member").
+			roleFilter := ""
+			if role != "" && strings.ToLower(role) != "all" {
+				roleFilter = strings.ToLower(role)
+			}
+
+			// Use Organizations.ListMembers with pagination (page/per_page)
+			opts := &github.ListMembersOptions{
+				Role: roleFilter,
+				ListOptions: github.ListOptions{
+					PerPage: int(perPage),
+					Page:    int(page),
+				},
+			}
+
+			users, resp, err := client.Organizations.ListMembers(ctx, org, opts)
+			if err != nil {
+				return ghErrors.NewGitHubAPIErrorResponse(ctx, "Failed to get organization members", resp, err), nil
+			}
+
+			type outUser struct {
+				Login     string `json:"login"`
+				ID        string `json:"id"`
+				AvatarURL string `json:"avatar_url"`
+				Type      string `json:"type"`
+			}
+
+			var members []outUser
+			for _, u := range users {
+				members = append(members, outUser{
+					Login:     u.GetLogin(),
+					ID:        fmt.Sprintf("%v", u.GetID()),
+					AvatarURL: u.GetAvatarURL(),
+					Type:      u.GetType(),
+				})
+			}
+
+			return MarshalledTextResult(members), nil
+		}
+}

pkg/github/context_tools_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
 	"testing"
 	"time"
 
@@ -497,3 +498,115 @@ func Test_GetTeamMembers(t *testing.T) {
 		})
 	}
 }
+
+func Test_GetOrgMembers(t *testing.T) {
+	t.Parallel()
+
+	tool, _ := getOrgMembers(nil, translations.NullTranslationHelper)
+	require.NoError(t, toolsnaps.Test(tool.Name, tool))
+
+	assert.Equal(t, "get_org_members", tool.Name)
+	assert.True(t, *tool.Annotations.ReadOnlyHint, "get_org_members tool should be read-only")
+
+	// Mocked REST users as returned by GitHub REST API
+	mockUsers := []map[string]any{
+		{"login": "user1", "id": 11, "avatar_url": "https://example.com/avatars/1", "type": "User"},
+		{"login": "user2", "id": 22, "avatar_url": "https://example.com/avatars/2", "type": "User"},
+	}
+
+	tests := []struct {
+		name          string
+		mockedClient  *http.Client
+		stubGetClient GetClientFn
+		requestArgs   map[string]any
+		expectToolErr bool
+		expectErrMsg  string
+		expectCount   int
+	}{
+		{
+			name: "successful get org members",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.EndpointPattern{Pattern: "/orgs/{org}/members", Method: http.MethodGet},
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						_, _ = w.Write(mock.MustMarshal(mockUsers))
+					}),
+				),
+			),
+			requestArgs: map[string]any{"org": "testorg", "role": "all", "per_page": 30, "page": 1},
+			expectCount: 2,
+		},
+		{
+			name: "org with no members",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.EndpointPattern{Pattern: "/orgs/{org}/members", Method: http.MethodGet},
+					http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+						w.WriteHeader(http.StatusOK)
+						_, _ = w.Write(mock.MustMarshal([]map[string]any{}))
+					}),
+				),
+			),
+			requestArgs: map[string]any{"org": "testorg", "role": "all", "per_page": 30, "page": 1},
+			expectCount: 0,
+		},
+		{
+			name:          "getting client fails",
+			mockedClient:  nil,
+			stubGetClient: stubGetClientFnErr("expected test error"),
+			requestArgs:   map[string]any{"org": "testorg"},
+			expectToolErr: true,
+			expectErrMsg:  "failed to get GitHub client: expected test error",
+		},
+		{
+			name: "api error",
+			mockedClient: mock.NewMockedHTTPClient(
+				mock.WithRequestMatchHandler(
+					mock.EndpointPattern{Pattern: "/orgs/{org}/members", Method: http.MethodGet},
+					mockResponse(t, http.StatusInternalServerError, map[string]string{"message": "boom"}),
+				),
+			),
+			requestArgs:   map[string]any{"org": "testorg"},
+			expectToolErr: true,
+			expectErrMsg:  "Failed to get organization members",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var stubFn GetClientFn
+			if tc.stubGetClient != nil {
+				stubFn = tc.stubGetClient
+			} else if tc.mockedClient != nil {
+				stubFn = stubGetClientFromHTTPFn(tc.mockedClient)
+			} else {
+				stubFn = nil
+			}
+
+			_, handler := getOrgMembers(stubFn, translations.NullTranslationHelper)
+
+			request := createMCPRequest(tc.requestArgs)
+			result, err := handler(context.Background(), request)
+			require.NoError(t, err)
+			textContent := getTextResult(t, result)
+
+			if tc.expectToolErr {
+				assert.True(t, result.IsError)
+				assert.Contains(t, textContent.Text, tc.expectErrMsg)
+				return
+			}
+
+			var members []struct {
+				Login     string `json:"login"`
+				ID        string `json:"id"`
+				AvatarURL string `json:"avatar_url"`
+				Type      string `json:"type"`
+			}
+			err = json.Unmarshal([]byte(textContent.Text), &members)
+			require.NoError(t, err)
+
+			assert.Len(t, members, tc.expectCount)
+		})
+	}
+}

pkg/github/tools.go

@@ -14,8 +14,10 @@ import (
 	"github.com/shurcooL/githubv4"
 )
 
-type GetClientFn func(context.Context) (*github.Client, error)
-type GetGQLClientFn func(context.Context) (*githubv4.Client, error)
+type (
+	GetClientFn    func(context.Context) (*github.Client, error)
+	GetGQLClientFn func(context.Context) (*githubv4.Client, error)
+)
 
 // ToolsetMetadata holds metadata for a toolset including its ID and description
 type ToolsetMetadata struct {
@@ -312,6 +314,7 @@ func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetG
 			toolsets.NewServerTool(GetMe(getClient, t)),
 			toolsets.NewServerTool(GetTeams(getClient, getGQLClient, t)),
 			toolsets.NewServerTool(GetTeamMembers(getGQLClient, t)),
+			toolsets.NewServerTool(getOrgMembers(getClient, t)),
 		)
 
 	gists := toolsets.NewToolset(ToolsetMetadataGists.ID, ToolsetMetadataGists.Description).