perf: add inventory cache for stateless server patterns

Add CachedInventory to build tool/resource/prompt definitions once at
startup rather than per-request. This is particularly useful for the
remote server pattern where a new server instance is created per request.

Key features:
- InitInventoryCache(t) initializes the cache once at startup
- CachedInventoryBuilder() returns a builder with pre-cached definitions
- Per-request configuration (read-only, toolsets, feature flags) still works
- Thread-safe via sync.Once
- Backward compatible: NewInventory(t) still works without caching

This addresses the performance concern raised in go-sdk PR #685 at a
higher level by caching the entire []ServerTool slice rather than
individual schemas.

Related: modelcontextprotocol/go-sdk#685

Author: SamMorrowDrums

pkg/github/inventory_cache.go

@@ -0,0 +1,116 @@
+package github
+
+import (
+	"sync"
+
+	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/github/github-mcp-server/pkg/translations"
+)
+
+// CachedInventory provides a cached inventory builder that builds tool definitions
+// only once, regardless of how many times NewInventoryBuilder is called.
+//
+// This is particularly useful for stateless server patterns (like the remote server)
+// where a new server instance is created per request. Without caching, every request
+// would rebuild all ~130 tool definitions including JSON schema generation, causing
+// significant performance overhead.
+//
+// Usage:
+//
+//	// Option 1: Initialize once at startup with your translator
+//	github.InitInventoryCache(myTranslator)
+//
+//	// Then get pre-built inventory on each request
+//	inv := github.CachedInventoryBuilder().
+//	    WithReadOnly(cfg.ReadOnly).
+//	    WithToolsets(cfg.Toolsets).
+//	    Build()
+//
+//	// Option 2: Use NewInventory which doesn't use the cache (legacy behavior)
+//	inv := github.NewInventory(myTranslator).Build()
+//
+// The cache stores the built []ServerTool, []ServerResourceTemplate, and []ServerPrompt.
+// Per-request configuration (read-only, toolsets, feature flags, filters) is still
+// applied when building the Inventory from the cached data.
+type CachedInventory struct {
+	once      sync.Once
+	tools     []inventory.ServerTool
+	resources []inventory.ServerResourceTemplate
+	prompts   []inventory.ServerPrompt
+}
+
+// global singleton for caching
+var globalInventoryCache = &CachedInventory{}
+
+// InitInventoryCache initializes the global inventory cache with the given translator.
+// This should be called once at startup before any requests are processed.
+// It's safe to call multiple times - only the first call has any effect.
+//
+// For the local server, this is typically called with the configured translator.
+// For the remote server, use translations.NullTranslationHelper since translations
+// aren't needed per-request.
+//
+// Example:
+//
+//	func main() {
+//	    t, _ := translations.TranslationHelper()
+//	    github.InitInventoryCache(t)
+//	    // ... start server
+//	}
+func InitInventoryCache(t translations.TranslationHelperFunc) {
+	globalInventoryCache.init(t)
+}
+
+// init initializes the cache with the given translator (sync.Once protected).
+func (c *CachedInventory) init(t translations.TranslationHelperFunc) {
+	c.once.Do(func() {
+		c.tools = AllTools(t)
+		c.resources = AllResources(t)
+		c.prompts = AllPrompts(t)
+	})
+}
+
+// CachedInventoryBuilder returns an inventory.Builder pre-populated with cached
+// tool/resource/prompt definitions.
+//
+// The cache must be initialized via InitInventoryCache before calling this function.
+// If the cache is not initialized, this will initialize it with NullTranslationHelper.
+//
+// Per-request configuration can still be applied via the builder methods:
+//   - WithReadOnly(bool) - filter to read-only tools
+//   - WithToolsets([]string) - enable specific toolsets
+//   - WithTools([]string) - enable specific tools
+//   - WithFeatureChecker(func) - per-request feature flag evaluation
+//   - WithFilter(func) - custom filtering
+//
+// Example:
+//
+//	inv := github.CachedInventoryBuilder().
+//	    WithReadOnly(cfg.ReadOnly).
+//	    WithToolsets(cfg.EnabledToolsets).
+//	    WithFeatureChecker(createFeatureChecker(cfg.EnabledFeatures)).
+//	    Build()
+func CachedInventoryBuilder() *inventory.Builder {
+	// Ensure cache is initialized (with NullTranslationHelper as fallback)
+	globalInventoryCache.init(translations.NullTranslationHelper)
+
+	return inventory.NewBuilder().
+		SetTools(globalInventoryCache.tools).
+		SetResources(globalInventoryCache.resources).
+		SetPrompts(globalInventoryCache.prompts)
+}
+
+// IsCacheInitialized returns true if the inventory cache has been initialized.
+// This is primarily useful for testing.
+func IsCacheInitialized() bool {
+	// We can't directly check sync.Once state, but we can check if tools are populated
+	return len(globalInventoryCache.tools) > 0
+}
+
+// ResetInventoryCache resets the global inventory cache, allowing it to be
+// reinitialized with a different translator. This should only be used in tests.
+//
+// WARNING: This is not thread-safe and should never be called in production code.
+func ResetInventoryCache() {
+	globalInventoryCache = &CachedInventory{}
+}

pkg/github/inventory_cache_test.go

@@ -0,0 +1,148 @@
+package github
+
+import (
+	"context"
+	"testing"
+
+	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCachedInventory(t *testing.T) {
+	// Reset cache before test
+	ResetInventoryCache()
+
+	t.Run("InitInventoryCache initializes tools", func(t *testing.T) {
+		ResetInventoryCache()
+
+		// Cache should be empty before init
+		assert.False(t, IsCacheInitialized())
+
+		// Initialize with null translator
+		InitInventoryCache(translations.NullTranslationHelper)
+
+		// Cache should now be initialized
+		assert.True(t, IsCacheInitialized())
+	})
+
+	t.Run("CachedInventoryBuilder returns builder with cached tools", func(t *testing.T) {
+		ResetInventoryCache()
+		InitInventoryCache(translations.NullTranslationHelper)
+
+		builder := CachedInventoryBuilder()
+		require.NotNil(t, builder)
+
+		inv := builder.Build()
+		require.NotNil(t, inv)
+
+		// Should have tools available
+		tools := inv.AllTools()
+		assert.Greater(t, len(tools), 0)
+	})
+
+	t.Run("CachedInventoryBuilder auto-initializes if not initialized", func(t *testing.T) {
+		ResetInventoryCache()
+
+		// Don't call InitInventoryCache
+
+		// CachedInventoryBuilder should still work (auto-init with NullTranslationHelper)
+		builder := CachedInventoryBuilder()
+		require.NotNil(t, builder)
+
+		inv := builder.Build()
+		require.NotNil(t, inv)
+
+		tools := inv.AllTools()
+		assert.Greater(t, len(tools), 0)
+	})
+
+	t.Run("InitInventoryCache is idempotent", func(t *testing.T) {
+		ResetInventoryCache()
+
+		// First init with a custom translator that tracks calls
+		callCount := 0
+		customTranslator := func(_, defaultValue string) string {
+			callCount++
+			return defaultValue
+		}
+
+		InitInventoryCache(customTranslator)
+		firstCallCount := callCount
+
+		// Second init should be no-op
+		callCount = 0
+		InitInventoryCache(translations.NullTranslationHelper)
+
+		assert.Equal(t, 0, callCount, "second InitInventoryCache should not call translator")
+
+		// Verify first translator was used (tools are still populated from first call)
+		assert.True(t, IsCacheInitialized())
+		assert.Greater(t, firstCallCount, 0, "first init should have called translator")
+	})
+
+	t.Run("cached inventory preserves per-request configuration", func(t *testing.T) {
+		ResetInventoryCache()
+		InitInventoryCache(translations.NullTranslationHelper)
+
+		// Build with read-only filter
+		invReadOnly := CachedInventoryBuilder().
+			WithReadOnly(true).
+			WithToolsets([]string{"all"}).
+			Build()
+
+		// Build without read-only filter
+		invAll := CachedInventoryBuilder().
+			WithReadOnly(false).
+			WithToolsets([]string{"all"}).
+			Build()
+
+		// AvailableTools applies filters - all tools should have more than read-only
+		ctx := context.Background()
+		allTools := invAll.AvailableTools(ctx)
+		readOnlyTools := invReadOnly.AvailableTools(ctx)
+
+		assert.Greater(t, len(allTools), len(readOnlyTools),
+			"read-only inventory should have fewer tools")
+	})
+
+	t.Run("cached inventory supports toolset filtering", func(t *testing.T) {
+		ResetInventoryCache()
+		InitInventoryCache(translations.NullTranslationHelper)
+
+		// Build with only one toolset
+		invOneToolset := CachedInventoryBuilder().
+			WithToolsets([]string{"context"}).
+			Build()
+
+		// Build with all toolsets
+		invAll := CachedInventoryBuilder().
+			WithToolsets([]string{"all"}).
+			Build()
+
+		ctx := context.Background()
+		oneToolsetTools := invOneToolset.AvailableTools(ctx)
+		allTools := invAll.AvailableTools(ctx)
+
+		assert.Greater(t, len(allTools), len(oneToolsetTools),
+			"all toolsets should have more tools than single toolset")
+	})
+}
+
+func TestNewInventoryVsCachedInventoryBuilder(t *testing.T) {
+	ResetInventoryCache()
+
+	// NewInventory creates fresh tools each time
+	inv1 := NewInventory(translations.NullTranslationHelper).Build()
+	inv2 := NewInventory(translations.NullTranslationHelper).Build()
+
+	// Both should have the same number of tools
+	assert.Equal(t, len(inv1.AllTools()), len(inv2.AllTools()))
+
+	// CachedInventoryBuilder uses cached tools
+	InitInventoryCache(translations.NullTranslationHelper)
+	cachedInv := CachedInventoryBuilder().Build()
+
+	// Should also have the same number of tools
+	assert.Equal(t, len(inv1.AllTools()), len(cachedInv.AllTools()))
+}