feat(groups): add ttlMs and cacheScope customization to config (#3805)

## Description

This PR allows users to configure time-to-live and cache scope
parameters for groups through Toolbox's config file. Previously, these
values were hardcoded to `300000ms` and `public`, which Toolbox will
still default to if not directly set.

---------

Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com>

Author: AlexTalreja

cmd/root.go

@@ -383,7 +383,7 @@ func watchChanges(ctx context.Context, watchDirs map[string]bool, watchedFiles m
 
 			err = handleDynamicReload(ctx, reloadedConfig, s)
 			if err != nil {
-				errMsg := fmt.Errorf("unable to parse reloaded config at %q: %w", reloadedConfig, err)
+				errMsg := fmt.Errorf("unable to parse reloaded config at %+v: %w", reloadedConfig, err)
 				logger.WarnContext(ctx, errMsg.Error())
 				continue
 			}

internal/group/group.go

@@ -22,6 +22,11 @@ import (
 	"github.com/googleapis/mcp-toolbox/internal/tools"
 )
 
+const (
+	DefaultTTLMs      = 300000   // default TTL for groups in milliseconds (5 minutes)
+	DefaultCacheScope = "public" // default cache scope for groups
+)
+
 // GroupConfig is the parsed configuration for a group: a single named collection
 // that holds both tools and prompts. Its description doubles as the MCP server
 // instructions for clients connected to the group.
@@ -30,6 +35,8 @@ type GroupConfig struct {
 	Description string   `yaml:"description"`
 	ToolNames   []string `yaml:"tools"`
 	PromptNames []string `yaml:"prompts"`
+	CacheScope  string   `yaml:"cacheScope" validate:"omitempty,oneof=public private"`
+	TTLMs       *int     `yaml:"ttlMs" validate:"omitempty,gte=0"`
 }
 
 // Group is an initialized group: the source of truth for a named collection of
@@ -94,6 +101,22 @@ func NewGroup(config GroupConfig) Group {
 	return Group{GroupConfig: config, toolNameSet: toolNameSet, promptNameSet: promptNameSet}
 }
 
+// GetTTLMs returns the time to live for the group
+func (g Group) GetTTLMs() int {
+	if g.TTLMs == nil {
+		return DefaultTTLMs
+	}
+	return *g.TTLMs
+}
+
+// GetCacheScope returns the cache scope for the group
+func (g Group) GetCacheScope() string {
+	if g.CacheScope == "" {
+		return DefaultCacheScope
+	}
+	return g.CacheScope
+}
+
 // ContainsTool reports whether the group includes a tool with the given name.
 func (g Group) ContainsTool(name string) bool {
 	_, ok := g.toolNameSet[name]

internal/group/group_test.go

@@ -15,12 +15,15 @@
 package group_test
 
 import (
+	"context"
 	"slices"
 	"strings"
 	"testing"
 
+	"github.com/google/go-cmp/cmp"
 	"github.com/googleapis/mcp-toolbox/internal/group"
 	"github.com/googleapis/mcp-toolbox/internal/prompts"
+	"github.com/googleapis/mcp-toolbox/internal/server"
 	"github.com/googleapis/mcp-toolbox/internal/server/primitives"
 	"github.com/googleapis/mcp-toolbox/internal/testutils"
 	"github.com/googleapis/mcp-toolbox/internal/tools"
@@ -39,16 +42,22 @@ func testFixtures() (map[string]tools.Tool, map[string]prompts.Prompt) {
 	return toolsMap, promptsMap
 }
 
+func intPtr(v int) *int {
+	return &v
+}
+
 func TestGroupConfig_Initialize(t *testing.T) {
 	t.Parallel()
 	toolsMap, promptsMap := testFixtures()
 
 	testCases := []struct {
-		name        string
-		config      group.GroupConfig
-		wantTools   []string
-		wantPrompts []string
-		wantErr     string
+		name           string
+		config         group.GroupConfig
+		wantTools      []string
+		wantPrompts    []string
+		wantErr        string
+		wantTTLMs      *int
+		wantCacheScope string
 	}{
 		{
 			name: "tools and prompts",
@@ -113,6 +122,44 @@ func TestGroupConfig_Initialize(t *testing.T) {
 			},
 			wantErr: "prompt does not exist: \"nope\"",
 		},
+		{
+			name: "valid ttlMs",
+			config: group.GroupConfig{
+				Name:  "g",
+				TTLMs: intPtr(10000),
+			},
+			wantTTLMs: intPtr(10000),
+		},
+		{
+			name: "empty ttlMs",
+			config: group.GroupConfig{
+				Name: "g",
+			},
+			wantTTLMs: intPtr(300000),
+		},
+		{
+			name: "public cacheScope",
+			config: group.GroupConfig{
+				Name:       "g",
+				CacheScope: "public",
+			},
+			wantCacheScope: "public",
+		},
+		{
+			name: "private cacheScope",
+			config: group.GroupConfig{
+				Name:       "g",
+				CacheScope: "private",
+			},
+			wantCacheScope: "private",
+		},
+		{
+			name: "empty cacheScope",
+			config: group.GroupConfig{
+				Name: "g",
+			},
+			wantCacheScope: "public",
+		},
 	}
 
 	for _, tc := range testCases {
@@ -147,6 +194,22 @@ func TestGroupConfig_Initialize(t *testing.T) {
 					t.Errorf("group missing prompt %q", name)
 				}
 			}
+
+			expectedScope := tc.wantCacheScope
+			if expectedScope == "" {
+				expectedScope = group.DefaultCacheScope
+			}
+			if g.GetCacheScope() != expectedScope {
+				t.Errorf("CacheScope = %q, want %q", g.GetCacheScope(), expectedScope)
+			}
+
+			expectedTTL := group.DefaultTTLMs
+			if tc.wantTTLMs != nil {
+				expectedTTL = *tc.wantTTLMs
+			}
+			if g.GetTTLMs() != expectedTTL {
+				t.Errorf("TTLMs = %d, want %d", g.GetTTLMs(), expectedTTL)
+			}
 		})
 	}
 }
@@ -217,3 +280,80 @@ func TestGroup_Contains(t *testing.T) {
 		t.Errorf("group reports an absent prompt")
 	}
 }
+
+func TestParseFromYamlGroup(t *testing.T) {
+	tcs := []struct {
+		desc string
+		in   string
+		want server.GroupConfigs
+	}{
+		{
+			desc: "basic group",
+			in: `
+			kind: group
+			name: my-group
+			ttlMs: 60000
+			cacheScope: private
+			`,
+			want: map[string]group.GroupConfig{
+				"my-group": {
+					Name:       "my-group",
+					TTLMs:      intPtr(60000),
+					CacheScope: "private",
+				},
+			},
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.desc, func(t *testing.T) {
+			// Parse contents
+			_, _, _, _, _, got, err := server.UnmarshalPrimitiveConfig(context.Background(), testutils.FormatYaml(tc.in))
+			if err != nil {
+				t.Fatalf("unable to unmarshal: %s", err)
+			}
+			if !cmp.Equal(tc.want, got) {
+				t.Fatalf("incorrect parse: want %v, got %v", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestFailParseFromYaml(t *testing.T) {
+	tcs := []struct {
+		desc string
+		in   string
+		err  string
+	}{
+		{
+			desc: "invalid cacheScope",
+			in: `
+			kind: group
+			name: my-group
+			cacheScope: secret
+			`,
+			err: "Field validation for 'CacheScope' failed on the 'oneof' tag",
+		},
+		{
+			desc: "invalid ttlMs",
+			in: `
+			kind: group
+			name: my-group
+			ttlMs: -100
+			`,
+			err: "Field validation for 'TTLMs' failed on the 'gte' tag",
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.desc, func(t *testing.T) {
+			// Parse contents
+			_, _, _, _, _, _, err := server.UnmarshalPrimitiveConfig(context.Background(), testutils.FormatYaml(tc.in))
+			if err == nil {
+				t.Fatalf("expect parsing to fail")
+			}
+			errStr := err.Error()
+			if !strings.Contains(errStr, tc.err) {
+				t.Fatalf("unexpected error: got %q, want it to contain %q", errStr, tc.err)
+			}
+		})
+	}
+}

internal/server/mcp/v20260728/manifests.go

@@ -128,8 +128,8 @@ func GenerateListToolsResult(pMgr *primitives.PrimitiveManager, g group.Group, u
 			ResultType: resultTypeComplete,
 		},
 		CacheableResult: CacheableResult{
-			TtlMs:      300000, // 5 minutes
-			CacheScope: cacheScopePublic,
+			TtlMs:      g.GetTTLMs(),
+			CacheScope: cacheScope(g.GetCacheScope()),
 		},
 	}
 	return res, nil
@@ -170,8 +170,8 @@ func GenerateListPromptsResult(pMgr *primitives.PrimitiveManager, g group.Group)
 			ResultType: resultTypeComplete,
 		},
 		CacheableResult: CacheableResult{
-			TtlMs:      300000, // 5 minutes
-			CacheScope: cacheScopePublic,
+			TtlMs:      g.GetTTLMs(),
+			CacheScope: cacheScope(g.GetCacheScope()),
 		},
 	}
 	return res, nil