feat: Add session resource helper functions (#617)

* feat: add session resource helper functions

- Add ErrSessionDoesNotSupportResources error constant
- Implement AddSessionResource() helper for adding single resource
- Implement AddSessionResources() helper for batch resource operations
- Implement DeleteSessionResources() helper for removing resources
- Auto-register resource capabilities with listChanged=true for session resources
- Send notifications/resources/list_changed when resources are modified
- Match session tools helper pattern for consistency

* update

* test: fix race condition in TestNotificationErrorHandling

Use channel instead of shared variable to avoid race condition when
capturing errors from goroutines in the notification error handling test

* test: fix AddSessionResource assertions to validate state changes

- Capture pre-call resource count before AddSessionResource
- Assert resource is present and count increased after call
- Validate listChanged behavior matches expectations
- Fix auto-registration check to properly verify capabilities

* test: fix assertion for non-existent resource deletion

- Update test to assert no notification is sent when deleting non-existent resource
- Replace expectation of notification with assertion that no notification occurs
- Fail test if unexpected notification is received

* test: properly validate global+session resource merging

- Exercise server's ListResources and ReadResource handlers with session context
- Assert global resources appear in merged list
- Verify session resource overrides global resource with same URI
- Confirm ReadResource uses session handler for overridden resources
- Test that non-overridden global resources still use global handlers

* fix: only send resource notification when actually deleting resources

- Modified DeleteSessionResources to track if resources were actually deleted
- Only send list_changed notification if something was removed
- Fixed race condition in TestStreamableHTTP_SessionWithResources by protecting shared state
- Added sync.Once to prevent multiple WaitGroup.Done() calls

* Add RFC 3986 URI validation to AddSessionResources and optimize DeleteSessionResources

- Validate Resource.URI is non-empty and conforms to RFC 3986 using url.ParseRequestURI
- Return formatted errors for invalid or empty URIs instead of silently inserting them
- Skip SetSessionResources call in DeleteSessionResources when no resources were actually deleted
- Add comprehensive test for session resource overriding global resources

Author: ezynda3

server/errors.go

@@ -13,11 +13,12 @@ var (
 	ErrToolNotFound     = errors.New("tool not found")
 
 	// Session-related errors
-	ErrSessionNotFound              = errors.New("session not found")
-	ErrSessionExists                = errors.New("session already exists")
-	ErrSessionNotInitialized        = errors.New("session not properly initialized")
-	ErrSessionDoesNotSupportTools   = errors.New("session does not support per-session tools")
-	ErrSessionDoesNotSupportLogging = errors.New("session does not support setting logging level")
+	ErrSessionNotFound                = errors.New("session not found")
+	ErrSessionExists                  = errors.New("session already exists")
+	ErrSessionNotInitialized          = errors.New("session not properly initialized")
+	ErrSessionDoesNotSupportTools     = errors.New("session does not support per-session tools")
+	ErrSessionDoesNotSupportResources = errors.New("session does not support per-session resources")
+	ErrSessionDoesNotSupportLogging   = errors.New("session does not support setting logging level")
 
 	// Notification-related errors
 	ErrNotificationNotInitialized = errors.New("notification channel not initialized")

server/session.go

@@ -3,6 +3,7 @@ package server
 import (
 	"context"
 	"fmt"
+	"net/url"
 
 	"github.com/mark3labs/mcp-go/mcp"
 )
@@ -460,3 +461,155 @@ func (s *MCPServer) DeleteSessionTools(sessionID string, names ...string) error
 
 	return nil
 }
+
+// AddSessionResource adds a resource for a specific session
+func (s *MCPServer) AddSessionResource(sessionID string, resource mcp.Resource, handler ResourceHandlerFunc) error {
+	return s.AddSessionResources(sessionID, ServerResource{Resource: resource, Handler: handler})
+}
+
+// AddSessionResources adds resources for a specific session
+func (s *MCPServer) AddSessionResources(sessionID string, resources ...ServerResource) error {
+	sessionValue, ok := s.sessions.Load(sessionID)
+	if !ok {
+		return ErrSessionNotFound
+	}
+
+	session, ok := sessionValue.(SessionWithResources)
+	if !ok {
+		return ErrSessionDoesNotSupportResources
+	}
+
+	// For session resources, we want listChanged enabled by default
+	s.implicitlyRegisterCapabilities(
+		func() bool { return s.capabilities.resources != nil },
+		func() { s.capabilities.resources = &resourceCapabilities{listChanged: true} },
+	)
+
+	// Get existing resources (this should return a thread-safe copy)
+	sessionResources := session.GetSessionResources()
+
+	// Create a new map to avoid concurrent modification issues
+	newSessionResources := make(map[string]ServerResource, len(sessionResources)+len(resources))
+
+	// Copy existing resources
+	for k, v := range sessionResources {
+		newSessionResources[k] = v
+	}
+
+	// Add new resources with validation
+	for _, resource := range resources {
+		// Validate that URI is non-empty
+		if resource.Resource.URI == "" {
+			return fmt.Errorf("resource URI cannot be empty")
+		}
+
+		// Validate that URI conforms to RFC 3986
+		if _, err := url.ParseRequestURI(resource.Resource.URI); err != nil {
+			return fmt.Errorf("invalid resource URI: %w", err)
+		}
+
+		newSessionResources[resource.Resource.URI] = resource
+	}
+
+	// Set the resources (this should be thread-safe)
+	session.SetSessionResources(newSessionResources)
+
+	// It only makes sense to send resource notifications to initialized sessions --
+	// if we're not initialized yet the client can't possibly have sent their
+	// initial resources/list message.
+	//
+	// For initialized sessions, honor resources.listChanged, which is specifically
+	// about whether notifications will be sent or not.
+	// see <https://modelcontextprotocol.io/specification/2025-03-26/server/resources#capabilities>
+	if session.Initialized() && s.capabilities.resources != nil && s.capabilities.resources.listChanged {
+		// Send notification only to this session
+		if err := s.SendNotificationToSpecificClient(sessionID, "notifications/resources/list_changed", nil); err != nil {
+			// Log the error but don't fail the operation
+			// The resources were successfully added, but notification failed
+			if s.hooks != nil && len(s.hooks.OnError) > 0 {
+				hooks := s.hooks
+				go func(sID string, hooks *Hooks) {
+					ctx := context.Background()
+					hooks.onError(ctx, nil, "notification", map[string]any{
+						"method":    "notifications/resources/list_changed",
+						"sessionID": sID,
+					}, fmt.Errorf("failed to send notification after adding resources: %w", err))
+				}(sessionID, hooks)
+			}
+		}
+	}
+
+	return nil
+}
+
+// DeleteSessionResources removes resources from a specific session
+func (s *MCPServer) DeleteSessionResources(sessionID string, uris ...string) error {
+	sessionValue, ok := s.sessions.Load(sessionID)
+	if !ok {
+		return ErrSessionNotFound
+	}
+
+	session, ok := sessionValue.(SessionWithResources)
+	if !ok {
+		return ErrSessionDoesNotSupportResources
+	}
+
+	// Get existing resources (this should return a thread-safe copy)
+	sessionResources := session.GetSessionResources()
+	if sessionResources == nil {
+		return nil
+	}
+
+	// Create a new map to avoid concurrent modification issues
+	newSessionResources := make(map[string]ServerResource, len(sessionResources))
+
+	// Copy existing resources except those being deleted
+	for k, v := range sessionResources {
+		newSessionResources[k] = v
+	}
+
+	// Remove specified resources and track if anything was actually deleted
+	actuallyDeleted := false
+	for _, uri := range uris {
+		if _, exists := newSessionResources[uri]; exists {
+			delete(newSessionResources, uri)
+			actuallyDeleted = true
+		}
+	}
+
+	// Skip no-op write if nothing was actually deleted
+	if !actuallyDeleted {
+		return nil
+	}
+
+	// Set the resources (this should be thread-safe)
+	session.SetSessionResources(newSessionResources)
+
+	// It only makes sense to send resource notifications to initialized sessions --
+	// if we're not initialized yet the client can't possibly have sent their
+	// initial resources/list message.
+	//
+	// For initialized sessions, honor resources.listChanged, which is specifically
+	// about whether notifications will be sent or not.
+	// see <https://modelcontextprotocol.io/specification/2025-03-26/server/resources#capabilities>
+	// Only send notification if something was actually deleted
+	if actuallyDeleted && session.Initialized() && s.capabilities.resources != nil && s.capabilities.resources.listChanged {
+		// Send notification only to this session
+		if err := s.SendNotificationToSpecificClient(sessionID, "notifications/resources/list_changed", nil); err != nil {
+			// Log the error but don't fail the operation
+			// The resources were successfully deleted, but notification failed
+			if s.hooks != nil && len(s.hooks.OnError) > 0 {
+				hooks := s.hooks
+				go func(sID string, hooks *Hooks) {
+					ctx := context.Background()
+					hooks.onError(ctx, nil, "notification", map[string]any{
+						"method":    "notifications/resources/list_changed",
+						"sessionID": sID,
+					}, fmt.Errorf("failed to send notification after deleting resources: %w", err))
+				}(sessionID, hooks)
+			}
+		}
+	}
+
+	return nil
+}