feat: Add ToolsetRegistry with scope-aware NewToolsetGroup

Add ToolsetRegistry struct that holds toolset definitions and tools,
with a NewToolsetGroup method that accepts ToolsetGroupConfig:

- ReadOnly: restricts to read-only tools
- ActiveToolsets: which toolsets to enable
- AvailableScopes: filter tools by OAuth scope requirements
  - nil: no scope checking (all tools available)
  - []: empty means no scopes (only tools with no requirements)
  - [...]: tools must have required scopes in the list

This enables dynamic tool filtering based on the user's actual
OAuth token scopes, ensuring only authorized tools are exposed.

Author: SamMorrowDrums

pkg/toolsets/toolsets.go

@@ -213,22 +213,58 @@ type ToolsetMetadata struct {
 	Description string
 }
 
-// NewToolsetGroupFromTools creates a ToolsetGroup from a list of ServerTools.
+// ToolsetRegistry holds a collection of toolset definitions and their tools.
+// It provides a NewToolsetGroup method to create configured ToolsetGroups.
+type ToolsetRegistry struct {
+	toolsetMetadatas []ToolsetMetadata
+	tools            []ServerTool
+}
+
+// NewToolsetRegistry creates a new ToolsetRegistry with the given toolset metadata and tools.
+func NewToolsetRegistry(toolsetMetadatas []ToolsetMetadata, tools []ServerTool) *ToolsetRegistry {
+	return &ToolsetRegistry{
+		toolsetMetadatas: toolsetMetadatas,
+		tools:            tools,
+	}
+}
+
+// ToolsetGroupConfig specifies the configuration for creating a ToolsetGroup.
+type ToolsetGroupConfig struct {
+	// ReadOnly when true restricts the group to read-only tools
+	ReadOnly bool
+	// ActiveToolsets specifies which toolsets should be enabled.
+	// If nil, no toolsets are enabled by default.
+	ActiveToolsets []string
+	// AvailableScopes specifies the OAuth scopes available to the user.
+	// - nil means scopes are not checked (all tools available)
+	// - empty slice means no scopes (only tools requiring no scopes are available)
+	// - non-empty slice means only tools whose required scopes are satisfied are available
+	AvailableScopes []string
+}
+
+// NewToolsetGroup creates a ToolsetGroup from the registry with the given configuration.
 // Tools are automatically categorized as read or write based on their ReadOnlyHint annotation.
 // Tools are grouped into toolsets based on the "toolset" field in their Meta.
-// The toolsetMetadatas slice provides IDs and descriptions for each toolset.
-func NewToolsetGroupFromTools(readOnly bool, toolsetMetadatas []ToolsetMetadata, tools ...ServerTool) *ToolsetGroup {
-	tsg := NewToolsetGroup(readOnly)
+// If AvailableScopes is non-nil, tools are filtered based on scope requirements.
+func (r *ToolsetRegistry) NewToolsetGroup(config ToolsetGroupConfig) *ToolsetGroup {
+	tsg := NewToolsetGroup(config.ReadOnly)
 
 	// Build a map for quick lookup of toolset metadata by ID
 	metadataByID := make(map[string]ToolsetMetadata)
-	for _, meta := range toolsetMetadatas {
+	for _, meta := range r.toolsetMetadatas {
 		metadataByID[meta.ID] = meta
 	}
 
-	// Group tools by toolset name
+	// Group tools by toolset name, filtering by scopes if specified
 	toolsByToolset := make(map[string][]ServerTool)
-	for _, tool := range tools {
+	for _, tool := range r.tools {
+		// Check scope requirements if AvailableScopes is specified
+		if config.AvailableScopes != nil {
+			if !toolScopeSatisfied(tool, config.AvailableScopes) {
+				continue // Skip tools that don't have required scopes
+			}
+		}
+
 		toolsetID := getToolsetFromMeta(tool.Tool.Meta)
 		if toolsetID == "" {
 			panic(fmt.Sprintf("tool %q has no toolset in Meta", tool.Tool.Name))
@@ -257,9 +293,80 @@ func NewToolsetGroupFromTools(readOnly bool, toolsetMetadatas []ToolsetMetadata,
 		tsg.AddToolset(ts)
 	}
 
+	// Enable active toolsets
+	if len(config.ActiveToolsets) > 0 {
+		// Ignore errors for non-existent toolsets (they may have been filtered out by scopes)
+		_ = tsg.EnableToolsets(config.ActiveToolsets, nil)
+	}
+
 	return tsg
 }
 
+// toolScopeSatisfied checks if the tool's required scopes are satisfied by available scopes.
+// Returns true if the tool has no scope requirements or if all requirements are met.
+func toolScopeSatisfied(tool ServerTool, availableScopes []string) bool {
+	if tool.Tool.Meta == nil {
+		return true // No meta means no scope requirements
+	}
+
+	requiredScopes, ok := tool.Tool.Meta[scopeMetaKey]
+	if !ok {
+		return true // No scope requirements
+	}
+
+	// Handle both []string and []any (from JSON unmarshaling)
+	var required []string
+	switch v := requiredScopes.(type) {
+	case []string:
+		required = v
+	case []any:
+		required = make([]string, 0, len(v))
+		for _, s := range v {
+			if str, ok := s.(string); ok {
+				required = append(required, str)
+			}
+		}
+	default:
+		return true // Unknown format, allow
+	}
+
+	if len(required) == 0 {
+		return true // Empty requirements
+	}
+
+	// Check if any available scope satisfies the requirements
+	// For now, simple string matching - scope hierarchy should be handled by caller
+	availableSet := make(map[string]bool)
+	for _, s := range availableScopes {
+		availableSet[s] = true
+	}
+
+	for _, req := range required {
+		if !availableSet[req] {
+			return false
+		}
+	}
+
+	return true
+}
+
+// scopeMetaKey is the key used to store OAuth scopes in the mcp.Tool.Meta field.
+const scopeMetaKey = "requiredOAuthScopes"
+
+// NewToolsetGroupFromTools creates a ToolsetGroup from a list of ServerTools.
+// Tools are automatically categorized as read or write based on their ReadOnlyHint annotation.
+// Tools are grouped into toolsets based on the "toolset" field in their Meta.
+// The toolsetMetadatas slice provides IDs and descriptions for each toolset.
+//
+// Deprecated: Use NewToolsetRegistry and ToolsetRegistry.NewToolsetGroup instead.
+func NewToolsetGroupFromTools(readOnly bool, toolsetMetadatas []ToolsetMetadata, tools ...ServerTool) *ToolsetGroup {
+	registry := NewToolsetRegistry(toolsetMetadatas, tools)
+	return registry.NewToolsetGroup(ToolsetGroupConfig{
+		ReadOnly:        readOnly,
+		AvailableScopes: nil, // No scope filtering
+	})
+}
+
 // getToolsetFromMeta extracts the toolset name from tool metadata
 func getToolsetFromMeta(meta mcp.Meta) string {
 	if meta == nil {

pkg/toolsets/toolsets_test.go

@@ -408,6 +408,24 @@ func mockToolWithMeta(name string, toolsetName string, readOnly bool) ServerTool
 	}
 }
 
+// mockToolWithScopes creates a ServerTool with metadata including required scopes
+func mockToolWithScopes(name string, toolsetName string, readOnly bool, requiredScopes []string) ServerTool {
+	meta := mcp.Meta{"toolset": toolsetName}
+	if requiredScopes != nil {
+		meta["requiredOAuthScopes"] = requiredScopes
+	}
+	return ServerTool{
+		Tool: mcp.Tool{
+			Name: name,
+			Meta: meta,
+			Annotations: &mcp.ToolAnnotations{
+				ReadOnlyHint: readOnly,
+			},
+		},
+		RegisterFunc: func(_ *mcp.Server) {},
+	}
+}
+
 func TestNewToolsetGroupFromTools(t *testing.T) {
 	toolsetMetadatas := []ToolsetMetadata{
 		{ID: "repos", Description: "Repository tools"},
@@ -599,3 +617,196 @@ func TestGetToolsetFromMeta(t *testing.T) {
 		})
 	}
 }
+
+func TestToolsetRegistry_NewToolsetGroup(t *testing.T) {
+	toolsetMetadatas := []ToolsetMetadata{
+		{ID: "repos", Description: "Repository tools"},
+		{ID: "issues", Description: "Issue tools"},
+	}
+
+	tools := []ServerTool{
+		mockToolWithMeta("get_repo", "repos", true),
+		mockToolWithMeta("create_repo", "repos", false),
+		mockToolWithMeta("get_issue", "issues", true),
+		mockToolWithMeta("create_issue", "issues", false),
+	}
+
+	registry := NewToolsetRegistry(toolsetMetadatas, tools)
+
+	t.Run("basic creation", func(t *testing.T) {
+		tsg := registry.NewToolsetGroup(ToolsetGroupConfig{})
+
+		if len(tsg.Toolsets) != 2 {
+			t.Fatalf("expected 2 toolsets, got %d", len(tsg.Toolsets))
+		}
+
+		// Verify toolsets are not enabled by default
+		if tsg.IsEnabled("repos") {
+			t.Error("expected repos to be disabled by default")
+		}
+	})
+
+	t.Run("with active toolsets", func(t *testing.T) {
+		tsg := registry.NewToolsetGroup(ToolsetGroupConfig{
+			ActiveToolsets: []string{"repos"},
+		})
+
+		if !tsg.IsEnabled("repos") {
+			t.Error("expected repos to be enabled")
+		}
+		if tsg.IsEnabled("issues") {
+			t.Error("expected issues to be disabled")
+		}
+	})
+
+	t.Run("with read-only mode", func(t *testing.T) {
+		tsg := registry.NewToolsetGroup(ToolsetGroupConfig{
+			ReadOnly:       true,
+			ActiveToolsets: []string{"repos"},
+		})
+
+		reposToolset := tsg.Toolsets["repos"]
+		if !reposToolset.readOnly {
+			t.Error("expected toolset to be in read-only mode")
+		}
+
+		activeTools := reposToolset.GetActiveTools()
+		if len(activeTools) != 1 {
+			t.Errorf("expected 1 active tool in read-only mode, got %d", len(activeTools))
+		}
+	})
+}
+
+func TestToolsetRegistry_NewToolsetGroup_WithScopes(t *testing.T) {
+	toolsetMetadatas := []ToolsetMetadata{
+		{ID: "repos", Description: "Repository tools"},
+		{ID: "issues", Description: "Issue tools"},
+	}
+
+	tools := []ServerTool{
+		mockToolWithScopes("get_repo", "repos", true, nil),                  // No scope required
+		mockToolWithScopes("create_repo", "repos", false, []string{"repo"}), // Requires repo scope
+		mockToolWithScopes("get_issue", "issues", true, []string{"repo"}),   // Requires repo scope
+		mockToolWithScopes("public_issue", "issues", true, []string{}),      // Empty scopes (no requirement)
+	}
+
+	registry := NewToolsetRegistry(toolsetMetadatas, tools)
+
+	t.Run("nil scopes allows all tools", func(t *testing.T) {
+		tsg := registry.NewToolsetGroup(ToolsetGroupConfig{
+			AvailableScopes: nil,
+		})
+
+		reposToolset := tsg.Toolsets["repos"]
+		if len(reposToolset.readTools)+len(reposToolset.writeTools) != 2 {
+			t.Errorf("expected 2 tools in repos, got %d", len(reposToolset.readTools)+len(reposToolset.writeTools))
+		}
+	})
+
+	t.Run("empty scopes filters tools requiring scopes", func(t *testing.T) {
+		tsg := registry.NewToolsetGroup(ToolsetGroupConfig{
+			AvailableScopes: []string{}, // No scopes available
+		})
+
+		// repos should only have get_repo (no scope required)
+		reposToolset, exists := tsg.Toolsets["repos"]
+		if !exists {
+			t.Fatal("expected repos toolset to exist")
+		}
+		if len(reposToolset.readTools) != 1 {
+			t.Errorf("expected 1 read tool in repos (no scope required), got %d", len(reposToolset.readTools))
+		}
+		if len(reposToolset.writeTools) != 0 {
+			t.Errorf("expected 0 write tools in repos (scope required), got %d", len(reposToolset.writeTools))
+		}
+
+		// issues should only have public_issue (empty scopes)
+		issuesToolset, exists := tsg.Toolsets["issues"]
+		if !exists {
+			t.Fatal("expected issues toolset to exist")
+		}
+		if len(issuesToolset.readTools) != 1 {
+			t.Errorf("expected 1 read tool in issues, got %d", len(issuesToolset.readTools))
+		}
+	})
+
+	t.Run("with repo scope allows repo-scoped tools", func(t *testing.T) {
+		tsg := registry.NewToolsetGroup(ToolsetGroupConfig{
+			AvailableScopes: []string{"repo"},
+		})
+
+		reposToolset := tsg.Toolsets["repos"]
+		if len(reposToolset.readTools) != 1 {
+			t.Errorf("expected 1 read tool, got %d", len(reposToolset.readTools))
+		}
+		if len(reposToolset.writeTools) != 1 {
+			t.Errorf("expected 1 write tool, got %d", len(reposToolset.writeTools))
+		}
+
+		issuesToolset := tsg.Toolsets["issues"]
+		if len(issuesToolset.readTools) != 2 {
+			t.Errorf("expected 2 read tools in issues, got %d", len(issuesToolset.readTools))
+		}
+	})
+}
+
+func TestToolScopeSatisfied(t *testing.T) {
+	tests := []struct {
+		name            string
+		tool            ServerTool
+		availableScopes []string
+		expected        bool
+	}{
+		{
+			name:            "no meta",
+			tool:            ServerTool{Tool: mcp.Tool{Meta: nil}},
+			availableScopes: []string{},
+			expected:        true,
+		},
+		{
+			name:            "no scope requirement",
+			tool:            mockToolWithScopes("test", "repos", true, nil),
+			availableScopes: []string{},
+			expected:        true,
+		},
+		{
+			name:            "empty scope requirement",
+			tool:            mockToolWithScopes("test", "repos", true, []string{}),
+			availableScopes: []string{},
+			expected:        true,
+		},
+		{
+			name:            "scope required and available",
+			tool:            mockToolWithScopes("test", "repos", true, []string{"repo"}),
+			availableScopes: []string{"repo"},
+			expected:        true,
+		},
+		{
+			name:            "scope required but not available",
+			tool:            mockToolWithScopes("test", "repos", true, []string{"repo"}),
+			availableScopes: []string{"gist"},
+			expected:        false,
+		},
+		{
+			name:            "multiple scopes required all available",
+			tool:            mockToolWithScopes("test", "repos", true, []string{"repo", "gist"}),
+			availableScopes: []string{"repo", "gist", "user"},
+			expected:        true,
+		},
+		{
+			name:            "multiple scopes required one missing",
+			tool:            mockToolWithScopes("test", "repos", true, []string{"repo", "admin:org"}),
+			availableScopes: []string{"repo"},
+			expected:        false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := toolScopeSatisfied(tt.tool, tt.availableScopes)
+			if result != tt.expected {
+				t.Errorf("expected %v, got %v", tt.expected, result)
+			}
+		})
+	}
+}