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
This commit is contained in:
adam jones 2025-09-08 13:55:33 -07:00 • committed by GitHub
commit a85456a9b9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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)
}