Address Claude's feedback

Signed-off-by: Radoslav Dimitrov <[email protected]>

Author: rdimitrov

pkg/registry/converters/converters_test.go

@@ -137,7 +137,7 @@ func TestServerJSONToImageMetadata_NoPackages(t *testing.T) {
 
 	assert.Error(t, err)
 	assert.Nil(t, imageMetadata)
-	assert.Contains(t, err.Error(), "serverJSON has no packages")
+	assert.Contains(t, err.Error(), "has no packages")
 }
 
 func TestServerJSONToImageMetadata_NoOCIPackages(t *testing.T) {
@@ -157,7 +157,7 @@ func TestServerJSONToImageMetadata_NoOCIPackages(t *testing.T) {
 
 	assert.Error(t, err)
 	assert.Nil(t, imageMetadata)
-	assert.Contains(t, err.Error(), "serverJSON has no OCI packages")
+	assert.Contains(t, err.Error(), "has no OCI packages")
 }
 
 func TestServerJSONToImageMetadata_MultipleOCIPackages(t *testing.T) {
@@ -517,7 +517,7 @@ func TestServerJSONToRemoteServerMetadata_NoRemotes(t *testing.T) {
 
 	assert.Error(t, err)
 	assert.Nil(t, remoteMetadata)
-	assert.Contains(t, err.Error(), "serverJSON has no remotes")
+	assert.Contains(t, err.Error(), "has no remotes")
 }
 
 func TestServerJSONToRemoteServerMetadata_WithHeaders(t *testing.T) {

pkg/registry/converters/toolhive_to_upstream.go

@@ -1,5 +1,13 @@
-// Package converters provides conversion functions from toolhive ImageMetadata/RemoteServerMetadata formats
-// to upstream MCP ServerJSON format.
+// Package converters provides bidirectional conversion between toolhive registry formats
+// and the upstream MCP (Model Context Protocol) ServerJSON format.
+//
+// The package supports two conversion directions:
+//   - toolhive → upstream: ImageMetadata/RemoteServerMetadata → ServerJSON (this file)
+//   - upstream → toolhive: ServerJSON → ImageMetadata/RemoteServerMetadata (upstream_to_toolhive.go)
+//
+// Toolhive-specific fields (permissions, provenance, metadata) are stored in the upstream
+// format's publisher extensions under "io.github.stacklok", allowing additional metadata
+// while maintaining compatibility with the standard MCP registry format.
 package converters
 
 import (
@@ -35,6 +43,17 @@ func ImageMetadataToServerJSON(name string, imageMetadata *registry.ImageMetadat
 			URL:    imageMetadata.RepositoryURL,
 			Source: "github", // Assume GitHub
 		}
+	} else {
+		// Use toolhive-registry as fallback when no repository URL is available.
+		// This is necessary for schema validation - the upstream Repository field is a struct
+		// (not a pointer), so it can't be omitted with omitempty and would serialize as
+		// empty strings {"url": "", "source": ""}, which fails URI format validation.
+		// Using the toolhive-registry URL is reasonable since it's where these servers
+		// are registered and documented.
+		serverJSON.Repository = model.Repository{
+			URL:    "https://github.com/stacklok/toolhive-registry",
+			Source: "github",
+		}
 	}
 
 	// Create package
@@ -73,6 +92,17 @@ func RemoteServerMetadataToServerJSON(name string, remoteMetadata *registry.Remo
 			URL:    remoteMetadata.RepositoryURL,
 			Source: "github", // Assume GitHub
 		}
+	} else {
+		// Use toolhive-registry as fallback when no repository URL is available.
+		// This is necessary for schema validation - the upstream Repository field is a struct
+		// (not a pointer), so it can't be omitted with omitempty and would serialize as
+		// empty strings {"url": "", "source": ""}, which fails URI format validation.
+		// Using the toolhive-registry URL is reasonable since it's where these servers
+		// are registered and documented.
+		serverJSON.Repository = model.Repository{
+			URL:    "https://github.com/stacklok/toolhive-registry",
+			Source: "github",
+		}
 	}
 
 	// Create remote
@@ -115,12 +145,15 @@ func createPackagesFromImageMetadata(imageMetadata *registry.ImageMetadata) []mo
 	}
 
 	// Add URL for non-stdio transports
+	// Note: We use localhost as the host because container-based MCP servers run locally
+	// and are accessed via port forwarding. The actual container may listen on 0.0.0.0,
+	// but clients connect via localhost on the host machine.
 	if transportType == model.TransportTypeStreamableHTTP || transportType == model.TransportTypeSSE {
 		if imageMetadata.TargetPort > 0 {
 			// Include port in URL if explicitly set
 			transport.URL = fmt.Sprintf("http://localhost:%d", imageMetadata.TargetPort)
 		} else {
-			// No port specified - use URL without port
+			// No port specified - use URL without port (standard HTTP port 80)
 			transport.URL = "http://localhost"
 		}
 	}

pkg/registry/converters/upstream_to_toolhive.go

@@ -22,23 +22,25 @@ func ServerJSONToImageMetadata(serverJSON *upstream.ServerJSON) (*registry.Image
 	}
 
 	if len(serverJSON.Packages) == 0 {
-		return nil, fmt.Errorf("serverJSON has no packages (not a container-based server)")
+		return nil, fmt.Errorf("server '%s' has no packages (not a container-based server)", serverJSON.Name)
 	}
 
 	// Filter for OCI packages only
 	var ociPackages []model.Package
+	var packageTypes []string
 	for _, pkg := range serverJSON.Packages {
 		if pkg.RegistryType == model.RegistryTypeOCI {
 			ociPackages = append(ociPackages, pkg)
 		}
+		packageTypes = append(packageTypes, string(pkg.RegistryType))
 	}
 
 	if len(ociPackages) == 0 {
-		return nil, fmt.Errorf("serverJSON has no OCI packages")
+		return nil, fmt.Errorf("server '%s' has no OCI packages (found: %v)", serverJSON.Name, packageTypes)
 	}
 
 	if len(ociPackages) > 1 {
-		return nil, fmt.Errorf("serverJSON has %d OCI packages, expected exactly 1", len(ociPackages))
+		return nil, fmt.Errorf("server '%s' has %d OCI packages, expected exactly 1", serverJSON.Name, len(ociPackages))
 	}
 
 	pkg := ociPackages[0]
@@ -75,9 +77,16 @@ func ServerJSONToImageMetadata(serverJSON *upstream.ServerJSON) (*registry.Image
 	if pkg.Transport.URL != "" {
 		// Parse URL like "http://localhost:8080"
 		parsedURL, err := url.Parse(pkg.Transport.URL)
-		if err == nil && parsedURL.Port() != "" {
+		if err != nil {
+			// Log parse error to aid debugging but don't fail conversion
+			fmt.Printf("⚠️  Failed to parse transport URL '%s' for server '%s': %v\n",
+				pkg.Transport.URL, serverJSON.Name, err)
+		} else if parsedURL.Port() != "" {
 			if port, err := strconv.Atoi(parsedURL.Port()); err == nil {
 				imageMetadata.TargetPort = port
+			} else {
+				fmt.Printf("⚠️  Failed to parse port from URL '%s' for server '%s': %v\n",
+					pkg.Transport.URL, serverJSON.Name, err)
 			}
 		}
 	}
@@ -101,7 +110,7 @@ func ServerJSONToRemoteServerMetadata(serverJSON *upstream.ServerJSON) (*registr
 	}
 
 	if len(serverJSON.Remotes) == 0 {
-		return nil, fmt.Errorf("serverJSON has no remotes (not a remote server)")
+		return nil, fmt.Errorf("server '%s' has no remotes (not a remote server)", serverJSON.Name)
 	}
 
 	remote := serverJSON.Remotes[0] // Use first remote

pkg/registry/official.go

@@ -232,16 +232,17 @@ func (*OfficialRegistry) createRepository(entry *types.RegistryEntry) model.Repo
 		repositoryURL = entry.RemoteServerMetadata.RepositoryURL
 	}
 
+	// If no repository URL is available, use toolhive-registry as fallback.
+	// This is necessary for schema validation - the upstream Repository field is a struct
+	// (not a pointer), so it can't be omitted with omitempty and would serialize as
+	// empty strings {"url": "", "source": ""}, which fails URI format validation.
+	// Using the toolhive-registry URL is reasonable since it's where these servers
+	// are registered and documented.
 	if repositoryURL == "" {
-		// Use a toolhive-registry placeholder URL to satisfy validation when no repository is available for remote servers
-		repositoryURL = "https://github.com/stacklok/toolhive-registry"
-		if entry.IsRemote() {
-			return model.Repository{
-				URL:    repositoryURL,
-				Source: "github",
-			}
+		return model.Repository{
+			URL:    "https://github.com/stacklok/toolhive-registry",
+			Source: "github",
 		}
-		return model.Repository{}
 	}
 
 	return model.Repository{

schemas/registry.schema.json

@@ -61,7 +61,7 @@
     }
   },
   "_schema_version": {
-    "mcp_registry_version": "v1.3.3",
+    "mcp_registry_version": "v1.3.5",
     "schema_date": "2025-10-17",
     "updated_at": "2025-10-22T12:35:00Z",
     "updated_by": "manual update to use static.modelcontextprotocol.io schema URL"