feat(catalog): implement MCP server database models and repository layer

Add complete database persistence layer for MCP servers and tools with composite versioning
strategy, comprehensive validation, and filter support.

Database Models and Interfaces:
- McpServer and McpServerTool models with typed attributes
- Repository interfaces for CRUD operations and source management
- Composite name versioning (base_name@version) with @ separator validation
- Filter mappings for 19 McpServer properties and 2 McpServerTool properties

Repository Implementation:
- McpServerRepository with full CRUD operations (Save, GetByID, GetByNameAndVersion, List, Delete)
- GetDistinctSourceIDs for source catalog management
- Upsert logic based on (base_name, version) tuple
- GORM query builder for database portability (MySQL/PostgreSQL)
- Source-based bulk deletion for catalog loader cleanup

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: Chris Hambridge <chambrid@redhat.com>

Author: chambridge

catalog/cmd/catalog.go

@@ -65,6 +65,7 @@ func runCatalogServer(cmd *cobra.Command, args []string) error {
 		getRepo[models.CatalogMetricsArtifactRepository](repoSet),
 		getRepo[models.CatalogSourceRepository](repoSet),
 		getRepo[models.PropertyOptionsRepository](repoSet),
+		getRepo[models.McpServerRepository](repoSet),
 	)
 
 	loader := catalog.NewLoader(services, catalogCfg.ConfigPath)

catalog/internal/catalog/catalog_test.go

@@ -43,6 +43,7 @@ func TestLoadCatalogSources(t *testing.T) {
 				&MockCatalogMetricsArtifactRepository{},
 				&MockCatalogSourceRepository{},
 				&MockPropertyOptionsRepository{},
+				nil, // McpServerRepository
 			)
 			loader := NewLoader(services, []string{tt.args.catalogsPath})
 			err := loader.Start(context.Background())
@@ -104,6 +105,7 @@ func TestLoadCatalogSourcesEnabledDisabled(t *testing.T) {
 				&MockCatalogMetricsArtifactRepository{},
 				&MockCatalogSourceRepository{},
 				&MockPropertyOptionsRepository{},
+				nil, // McpServerRepository
 			)
 			loader := NewLoader(services, []string{tt.args.catalogsPath})
 			err := loader.Start(context.Background())
@@ -131,6 +133,7 @@ func TestLabelsValidation(t *testing.T) {
 		&MockCatalogMetricsArtifactRepository{},
 		&MockCatalogSourceRepository{},
 		&MockPropertyOptionsRepository{},
+		nil, // McpServerRepository
 	)
 
 	tests := []struct {
@@ -262,6 +265,7 @@ func TestCatalogSourceLabelsDefaultToEmptySlice(t *testing.T) {
 				&MockCatalogMetricsArtifactRepository{},
 				&MockCatalogSourceRepository{},
 				&MockPropertyOptionsRepository{},
+				nil, // McpServerRepository
 			)
 			loader := NewLoader(services, []string{tt.args.catalogsPath})
 			err := loader.Start(context.Background())
@@ -301,6 +305,7 @@ func TestLoadCatalogSourcesWithMockRepositories(t *testing.T) {
 		mockMetricsArtifactRepo,
 		&MockCatalogSourceRepository{},
 		&MockPropertyOptionsRepository{},
+		nil, // McpServerRepository
 	)
 
 	// Register a test provider that will create some test data
@@ -429,6 +434,7 @@ func TestLoadCatalogSourcesWithRepositoryErrors(t *testing.T) {
 		mockMetricsArtifactRepo,
 		&MockCatalogSourceRepository{},
 		&MockPropertyOptionsRepository{},
+		nil, // McpServerRepository
 	)
 
 	// Register a test provider
@@ -505,6 +511,7 @@ func TestLoadCatalogSourcesWithNilEnabled(t *testing.T) {
 		mockMetricsArtifactRepo,
 		&MockCatalogSourceRepository{},
 		&MockPropertyOptionsRepository{},
+		nil, // McpServerRepository
 	)
 
 	// Register a test provider
@@ -1086,6 +1093,7 @@ func TestAPIProviderGetPerformanceArtifacts(t *testing.T) {
 		&MockCatalogMetricsArtifactRepository{},
 		&MockCatalogSourceRepository{},
 		&MockPropertyOptionsRepository{},
+		nil, // McpServerRepository
 	)
 	provider := NewDBCatalog(services, nil)
 
@@ -1114,6 +1122,7 @@ func TestAPIProviderInterface(t *testing.T) {
 		&MockCatalogMetricsArtifactRepository{},
 		&MockCatalogSourceRepository{},
 		&MockPropertyOptionsRepository{},
+		nil, // McpServerRepository
 	)
 	var provider APIProvider = NewDBCatalog(services, nil)
 

catalog/internal/catalog/db_catalog_test.go

@@ -52,6 +52,7 @@ func TestDBCatalog(t *testing.T) {
 		metricsArtifactRepo,
 		catalogSourceRepo,
 		service.NewPropertyOptionsRepository(sharedDB),
+		nil, // McpServerRepository
 	)
 
 	// Create DB catalog instance
@@ -1437,6 +1438,7 @@ func TestDBCatalog_GetPerformanceArtifactsWithService(t *testing.T) {
 		metricsArtifactRepo,
 		catalogSourceRepo,
 		service.NewPropertyOptionsRepository(sharedDB),
+		nil, // McpServerRepository
 	)
 
 	sources := NewSourceCollection()
@@ -1989,6 +1991,7 @@ func TestFindModelsWithRecommendedLatency(t *testing.T) {
 		metricsArtifactRepo,
 		catalogSourceRepo,
 		service.NewPropertyOptionsRepository(sharedDB),
+		nil, // McpServerRepository
 	)
 
 	// Create DB catalog instance

catalog/internal/catalog/integration_test.go

@@ -39,6 +39,7 @@ func setupIntegrationTestProvider(t *testing.T, ctx context.Context, sharedDB *g
 		metricsArtifactRepo,
 		catalogSourceRepo,
 		service.NewPropertyOptionsRepository(sharedDB),
+		nil, // McpServerRepository
 	)
 
 	// Insert test data:
@@ -180,6 +181,7 @@ func setupBenchmarkProvider(b *testing.B, ctx context.Context, sharedDB *gorm.DB
 		metricsArtifactRepo,
 		catalogSourceRepo,
 		service.NewPropertyOptionsRepository(sharedDB),
+		nil, // McpServerRepository
 	)
 
 	// Insert 100+ models with performance data for benchmarking

catalog/internal/catalog/loader_test.go

@@ -105,6 +105,7 @@ func TestRemoveModelsFromMissingSources(t *testing.T) {
 				&MockCatalogMetricsArtifactRepository{},
 				&MockCatalogSourceRepository{},
 				&MockPropertyOptionsRepository{},
+				nil, // McpServerRepository
 			)
 
 			// Create loader and populate sources

catalog/internal/db/filter/entity_mappings.go

@@ -12,6 +12,8 @@ type CatalogRestEntityType string
 const (
 	RestEntityCatalogModel    CatalogRestEntityType = "CatalogModel"
 	RestEntityCatalogArtifact CatalogRestEntityType = "CatalogArtifact"
+	RestEntityMcpServer       CatalogRestEntityType = "McpServer"
+	RestEntityMcpServerTool   CatalogRestEntityType = "McpServerTool"
 )
 
 // catalogEntityMappings implements EntityMappingFunctions for the catalog package
@@ -27,6 +29,8 @@ func (c *catalogEntityMappings) GetMLMDEntityType(restEntityType filter.RestEnti
 	switch restEntityType {
 	case filter.RestEntityType(RestEntityCatalogArtifact):
 		return filter.EntityTypeArtifact
+	case filter.RestEntityType(RestEntityMcpServerTool):
+		return filter.EntityTypeArtifact
 	default:
 		return filter.EntityTypeContext
 	}
@@ -67,6 +71,20 @@ func (c *catalogEntityMappings) GetPropertyDefinitionForRestEntity(restEntityTyp
 		}
 	}
 
+	if restEntityType == filter.RestEntityType(RestEntityMcpServer) {
+		if _, isWellKnown := mcpServerProperties[propertyName]; isWellKnown {
+			// Use the well-known property definition
+			return mcpServerProperties[propertyName]
+		}
+	}
+
+	if restEntityType == filter.RestEntityType(RestEntityMcpServerTool) {
+		if _, isWellKnown := mcpServerToolProperties[propertyName]; isWellKnown {
+			// Use the well-known property definition
+			return mcpServerToolProperties[propertyName]
+		}
+	}
+
 	// Not a well-known property for this entity type, treat as custom
 	return filter.PropertyDefinition{
 		Location:  filter.Custom,
@@ -119,3 +137,53 @@ var catalogArtifactProperties = map[string]filter.PropertyDefinition{
 	// Artifact type (stored in type_id but we can filter by string representation)
 	"artifactType": {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "artifactType"},
 }
+
+// mcpServerProperties defines the allowed properties for McpServer entities.
+// This follows the same pattern as catalogModelProperties - only properties that are:
+// 1. Entity table columns (required for core identity)
+// 2. Key filterable dimensions that need explicit type handling (arrays, bools)
+// 3. Common properties shared with CatalogModel for consistency
+// All other properties can be queried via custom property fallback.
+var mcpServerProperties = map[string]filter.PropertyDefinition{
+	// Common Context properties (Entity Table - required)
+	"id":                       {Location: filter.EntityTable, ValueType: filter.IntValueType, Column: "id"},
+	"name":                     {Location: filter.EntityTable, ValueType: filter.StringValueType, Column: "name"},
+	"externalId":               {Location: filter.EntityTable, ValueType: filter.StringValueType, Column: "external_id"},
+	"createTimeSinceEpoch":     {Location: filter.EntityTable, ValueType: filter.IntValueType, Column: "create_time_since_epoch"},
+	"lastUpdateTimeSinceEpoch": {Location: filter.EntityTable, ValueType: filter.IntValueType, Column: "last_update_time_since_epoch"},
+
+	// Core properties matching CatalogModel pattern
+	"source_id":    {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "source_id"},
+	"base_name":    {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "base_name"},
+	"description":  {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "description"},
+	"provider":     {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "provider"},
+	"license":      {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "license"},
+	"license_link": {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "license_link"},
+	"logo":         {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "logo"},
+	"readme":       {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "readme"},
+	"version":      {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "version"},
+
+	// MCP-specific filterable dimensions (need explicit type for arrays)
+	"tags":           {Location: filter.PropertyTable, ValueType: filter.ArrayValueType, Column: "tags"},
+	"transports":     {Location: filter.PropertyTable, ValueType: filter.ArrayValueType, Column: "transports"},
+	"deploymentMode": {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "deploymentMode"},
+
+	// Security indicators (need explicit type for booleans)
+	"verifiedSource": {Location: filter.PropertyTable, ValueType: filter.BoolValueType, Column: "verifiedSource"},
+	"secureEndpoint": {Location: filter.PropertyTable, ValueType: filter.BoolValueType, Column: "secureEndpoint"},
+	"sast":           {Location: filter.PropertyTable, ValueType: filter.BoolValueType, Column: "sast"},
+	"readOnlyTools":  {Location: filter.PropertyTable, ValueType: filter.BoolValueType, Column: "readOnlyTools"},
+}
+
+// mcpServerToolProperties defines the allowed properties for McpServerTool entities
+var mcpServerToolProperties = map[string]filter.PropertyDefinition{
+	// Common Artifact properties
+	"id":                       {Location: filter.EntityTable, ValueType: filter.IntValueType, Column: "id"},
+	"name":                     {Location: filter.EntityTable, ValueType: filter.StringValueType, Column: "name"},
+	"createTimeSinceEpoch":     {Location: filter.EntityTable, ValueType: filter.IntValueType, Column: "create_time_since_epoch"},
+	"lastUpdateTimeSinceEpoch": {Location: filter.EntityTable, ValueType: filter.IntValueType, Column: "last_update_time_since_epoch"},
+
+	// McpServerTool-specific properties stored in ArtifactProperty table
+	"description": {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "description"},
+	"accessType":  {Location: filter.PropertyTable, ValueType: filter.StringValueType, Column: "accessType"},
+}

catalog/internal/db/models/mcp_server.go

@@ -0,0 +1,57 @@
+package models
+
+import (
+	catalogfilter "github.com/kubeflow/model-registry/catalog/internal/db/filter"
+	"github.com/kubeflow/model-registry/internal/db/filter"
+	"github.com/kubeflow/model-registry/internal/db/models"
+)
+
+// McpServerListOptions holds the options for listing MCP servers.
+type McpServerListOptions struct {
+	models.Pagination
+	Name        *string
+	SourceIDs   *[]string
+	Query       *string
+	FilterQuery *string
+	NamedQuery  *string
+}
+
+// GetRestEntityType implements the FilterApplier interface.
+func (c *McpServerListOptions) GetRestEntityType() filter.RestEntityType {
+	return filter.RestEntityType(catalogfilter.RestEntityMcpServer)
+}
+
+// GetFilterQuery returns the filter query string for advanced filtering.
+func (c *McpServerListOptions) GetFilterQuery() string {
+	if c.FilterQuery == nil {
+		return ""
+	}
+	return *c.FilterQuery
+}
+
+// McpServerAttributes holds the attributes for an MCP server record.
+type McpServerAttributes struct {
+	Name                     *string
+	ExternalID               *string
+	CreateTimeSinceEpoch     *int64
+	LastUpdateTimeSinceEpoch *int64
+}
+
+// McpServer represents an MCP server stored in the database.
+type McpServer interface {
+	models.Entity[McpServerAttributes]
+}
+
+// McpServerImpl is the concrete implementation of McpServer.
+type McpServerImpl = models.BaseEntity[McpServerAttributes]
+
+// McpServerRepository defines the interface for MCP server persistence.
+type McpServerRepository interface {
+	GetByID(id int32) (McpServer, error)
+	GetByNameAndVersion(name string, version string) (McpServer, error)
+	List(listOptions McpServerListOptions) (*models.ListWrapper[McpServer], error)
+	Save(server McpServer) (McpServer, error)
+	DeleteBySource(sourceID string) error
+	DeleteByID(id int32) error
+	GetDistinctSourceIDs() ([]string, error)
+}

catalog/internal/db/models/mcp_server_tool.go

@@ -0,0 +1,29 @@
+package models
+
+import (
+	"github.com/kubeflow/model-registry/internal/db/models"
+)
+
+// McpServerToolAttributes holds the attributes for an MCP server tool record.
+type McpServerToolAttributes struct {
+	Name                     *string
+	CreateTimeSinceEpoch     *int64
+	LastUpdateTimeSinceEpoch *int64
+}
+
+// McpServerTool represents an MCP server tool stored in the database.
+type McpServerTool interface {
+	models.Entity[McpServerToolAttributes]
+}
+
+// McpServerToolImpl is the concrete implementation of McpServerTool.
+type McpServerToolImpl = models.BaseEntity[McpServerToolAttributes]
+
+// McpServerToolRepository defines the interface for MCP server tool persistence.
+type McpServerToolRepository interface {
+	GetByID(id int32) (McpServerTool, error)
+	List(parentID int32) ([]McpServerTool, error)
+	Save(tool McpServerTool, parentID *int32) (McpServerTool, error)
+	DeleteByParentID(parentID int32) error
+	DeleteByID(id int32) error
+}