Add filtering functionality to server list endpoint (#374)

## Summary - Adds `updated_since`, `search`, and `version` query parameters to `GET /v0/servers` - Enables incremental synchronization via RFC3339 timestamp filtering - Provides simple substring search on server names - Supports latest version filtering with `version=latest` This implementation provides the core filtering capabilities needed for efficient registry synchronization and improved server discovery. Fixes #291 Fixes #135
2025-09-08 13:55:33 -07:00 · 2025-09-08 13:55:33 -07:00 · a85456a9b9
commit a85456a9b9
parent be6c2d9142
2 changed files with 262 additions and 13 deletions
--- a/internal/api/handlers/v0/servers.go
+++ b/internal/api/handlers/v0/servers.go
@ -3,9 +3,11 @@ package v0
 import (
 	"context"
 	"net/http"
+	"time"

 	"github.com/danielgtaylor/huma/v2"
 	"github.com/google/uuid"
+	"github.com/modelcontextprotocol/registry/internal/database"
 	"github.com/modelcontextprotocol/registry/internal/service"
 	apiv0 "github.com/modelcontextprotocol/registry/pkg/api/v0"
 )
@ -19,8 +21,11 @@ type Metadata struct {

 // ListServersInput represents the input for listing servers
 type ListServersInput struct {
-	Cursor string `query:"cursor" doc:"Pagination cursor (UUID)" format:"uuid" required:"false"`
-	Limit  int    `query:"limit" doc:"Number of items per page" default:"30" minimum:"1" maximum:"100"`
+	Cursor       string `query:"cursor" doc:"Pagination cursor (UUID)" format:"uuid" required:"false" example:"550e8400-e29b-41d4-a716-446655440000"`
+	Limit        int    `query:"limit" doc:"Number of items per page" default:"30" minimum:"1" maximum:"100" example:"50"`
+	UpdatedSince string `query:"updated_since" doc:"Filter servers updated since timestamp (RFC3339 datetime)" required:"false" example:"2025-08-07T13:15:04.280Z"`
+	Search       string `query:"search" doc:"Search servers by name (substring match)" required:"false" example:"filesystem"`
+	Version      string `query:"version" doc:"Filter by version ('latest' for latest version, or an exact version like '1.2.3')" required:"false" example:"latest"`
 }

 // ListServersBody represents the paginated server list response body
@ -53,8 +58,38 @@ func RegisterServersEndpoints(api huma.API, registry service.RegistryService) {
 			}
 		}

-		// Get paginated results
-		servers, nextCursor, err := registry.List(input.Cursor, input.Limit)
+		// Build filter from input parameters
+		filter := &database.ServerFilter{}
+
+		// Parse updated_since parameter
+		if input.UpdatedSince != "" {
+			// Parse RFC3339 format
+			if updatedTime, err := time.Parse(time.RFC3339, input.UpdatedSince); err == nil {
+				filter.UpdatedSince = &updatedTime
+			} else {
+				return nil, huma.Error400BadRequest("Invalid updated_since format: expected RFC3339 timestamp (e.g., 2025-08-07T13:15:04.280Z)")
+			}
+		}
+
+		// Handle search parameter
+		if input.Search != "" {
+			filter.SubstringName = &input.Search
+		}
+
+		// Handle version parameter
+		if input.Version != "" {
+			if input.Version == "latest" {
+				// Special case: filter for latest versions
+				isLatest := true
+				filter.IsLatest = &isLatest
+			} else {
+				// Future: exact version matching
+				filter.Version = &input.Version
+			}
+		}
+
+		// Get paginated results with filtering
+		servers, nextCursor, err := registry.List(filter, input.Cursor, input.Limit)
 		if err != nil {
 			return nil, huma.Error500InternalServerError("Failed to get registry list", err)
 		}
--- a/internal/api/handlers/v0/servers_test.go
+++ b/internal/api/handlers/v0/servers_test.go
@ -127,6 +127,122 @@ func TestServersListEndpoint(t *testing.T) {
 			expectedStatus:  http.StatusOK,
 			expectedServers: []apiv0.ServerJSON{},
 		},
+		{
+			name:        "successful search by name substring",
+			queryParams: "?search=test-server",
+			setupRegistryService: func(registry service.RegistryService) {
+				server1 := apiv0.ServerJSON{
+					Name:        "com.example/test-server-matching",
+					Description: "Matching test server",
+					Repository: model.Repository{
+						URL:    "https://github.com/example/test-matching",
+						Source: "github",
+						ID:     "example/test-matching",
+					},
+					VersionDetail: model.VersionDetail{Version: "1.0.0"},
+				}
+				server2 := apiv0.ServerJSON{
+					Name:        "com.example/other-server",
+					Description: "Non-matching server",
+					Repository: model.Repository{
+						URL:    "https://github.com/example/other",
+						Source: "github",
+						ID:     "example/other",
+					},
+					VersionDetail: model.VersionDetail{Version: "1.0.0"},
+				}
+				_, _ = registry.Publish(server1)
+				_, _ = registry.Publish(server2)
+			},
+			expectedStatus:  http.StatusOK,
+			expectedServers: nil, // Will verify in test that only matching server is returned
+		},
+		{
+			name:        "successful updated_since filter with RFC3339",
+			queryParams: "?updated_since=2020-01-01T00:00:00Z",
+			setupRegistryService: func(registry service.RegistryService) {
+				server := apiv0.ServerJSON{
+					Name:        "com.example/recent-server",
+					Description: "Recently updated server",
+					Repository: model.Repository{
+						URL:    "https://github.com/example/recent",
+						Source: "github",
+						ID:     "example/recent",
+					},
+					VersionDetail: model.VersionDetail{Version: "1.0.0"},
+				}
+				_, _ = registry.Publish(server)
+			},
+			expectedStatus:  http.StatusOK,
+			expectedServers: nil, // Will verify server is returned since it was updated after 2020
+		},
+		{
+			name:        "successful version=latest filter",
+			queryParams: "?version=latest",
+			setupRegistryService: func(registry service.RegistryService) {
+				server1 := apiv0.ServerJSON{
+					Name:        "com.example/versioned-server",
+					Description: "First version",
+					Repository: model.Repository{
+						URL:    "https://github.com/example/versioned",
+						Source: "github",
+						ID:     "example/versioned",
+					},
+					VersionDetail: model.VersionDetail{Version: "1.0.0"},
+				}
+				server2 := apiv0.ServerJSON{
+					Name:        "com.example/versioned-server",
+					Description: "Second version (latest)",
+					Repository: model.Repository{
+						URL:    "https://github.com/example/versioned",
+						Source: "github",
+						ID:     "example/versioned",
+					},
+					VersionDetail: model.VersionDetail{Version: "2.0.0"},
+				}
+				_, _ = registry.Publish(server1)
+				_, _ = registry.Publish(server2) // This will be marked as latest
+			},
+			expectedStatus:  http.StatusOK,
+			expectedServers: nil, // Will verify only latest server is returned
+		},
+		{
+			name:        "combined search and updated_since filter",
+			queryParams: "?search=combined&updated_since=2020-01-01T00:00:00Z",
+			setupRegistryService: func(registry service.RegistryService) {
+				server1 := apiv0.ServerJSON{
+					Name:        "com.example/combined-test",
+					Description: "Server with combined filtering",
+					Repository: model.Repository{
+						URL:    "https://github.com/example/combined",
+						Source: "github",
+						ID:     "example/combined",
+					},
+					VersionDetail: model.VersionDetail{Version: "1.0.0"},
+				}
+				server2 := apiv0.ServerJSON{
+					Name:        "com.example/other-server",
+					Description: "Server that doesn't match search",
+					Repository: model.Repository{
+						URL:    "https://github.com/example/nomatch",
+						Source: "github",
+						ID:     "example/nomatch",
+					},
+					VersionDetail: model.VersionDetail{Version: "1.0.0"},
+				}
+				_, _ = registry.Publish(server1)
+				_, _ = registry.Publish(server2)
+			},
+			expectedStatus:  http.StatusOK,
+			expectedServers: nil, // Will verify only matching server is returned
+		},
+		{
+			name:                 "invalid updated_since format",
+			queryParams:          "?updated_since=invalid-timestamp",
+			setupRegistryService: func(_ service.RegistryService) {},
+			expectedStatus:       http.StatusBadRequest,
+			expectedError:        "Invalid updated_since format: expected RFC3339",
+		},
 	}

 	for _, tc := range testCases {
@ -170,7 +286,25 @@ func TestServersListEndpoint(t *testing.T) {
 					assert.Equal(t, tc.expectedServers, resp.Servers)
 				} else {
 					// For tests with dynamic data, check structure and count
-					assert.NotEmpty(t, resp.Servers, "Expected at least one server")
+					// Special handling for filter test cases
+					switch tc.name {
+					case "successful search by name substring":
+						assert.Len(t, resp.Servers, 1, "Expected exactly one matching server")
+						assert.Contains(t, resp.Servers[0].Name, "test-server", "Server name should contain search term")
+					case "successful updated_since filter with RFC3339":
+						assert.Len(t, resp.Servers, 1, "Expected one server updated after 2020")
+						assert.Contains(t, resp.Servers[0].Name, "recent-server")
+					case "successful version=latest filter":
+						assert.Len(t, resp.Servers, 1, "Expected one latest server")
+						assert.Contains(t, resp.Servers[0].Description, "latest")
+					case "combined search and updated_since filter":
+						assert.Len(t, resp.Servers, 1, "Expected one server matching both filters")
+						assert.Contains(t, resp.Servers[0].Name, "combined", "Server name should contain search term")
+					default:
+						assert.NotEmpty(t, resp.Servers, "Expected at least one server")
+					}
+					
+					// General structure validation
 					for _, server := range resp.Servers {
 						assert.NotEmpty(t, server.Name)
 						assert.NotEmpty(t, server.Description)