Add RegistryServerName to RunConfig for registry entry tracking (#4696)

Running workloads need to be mapped back to their registry entry by
name so that downstream consumers (e.g. the registry export endpoint)
can look up server metadata. Add a RegistryServerName field to
RunConfig following the same pattern as RegistryAPIURL and RegistryURL:
builder option, resolver helper, wiring through all three call sites,
and regenerated OpenAPI docs.

Part of stacklok/toolhive-rfcs#68

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JAORMX

cmd/thv/app/run_flags.go

@@ -347,12 +347,15 @@ func BuildRunnerConfig(
 		return nil, fmt.Errorf("failed to parse environment variables: %w", err)
 	}
 
-	// Resolve registry source URLs when the server was discovered via registry lookup.
+	// Resolve registry source URLs and server name when the server was discovered via registry lookup.
 	regAPIURL, regURL := runner.ResolveRegistrySourceURLs(serverMetadata, appConfig)
+	regServerName := runner.ResolveRegistryServerName(serverMetadata)
 
 	// Build the runner config
 	return buildRunnerConfig(ctx, runFlags, cmdArgs, debugMode, validatedHost, rt, imageURL, serverMetadata,
-		envVars, envVarValidator, oidcConfig, telemetryConfig, runner.WithRegistrySourceURLs(regAPIURL, regURL))
+		envVars, envVarValidator, oidcConfig, telemetryConfig,
+		runner.WithRegistrySourceURLs(regAPIURL, regURL),
+		runner.WithRegistryServerName(regServerName))
 }
 
 // setupOIDCConfiguration sets up OIDC configuration and validates URLs

docs/server/docs.go

@@ -252,8 +252,9 @@ func (s *WorkloadService) BuildFullRunConfig(
 		}
 	}
 
-	// Resolve registry source URLs when the server was discovered via registry lookup.
+	// Resolve registry source URLs and server name when the server was discovered via registry lookup.
 	regAPIURL, regURL := runner.ResolveRegistrySourceURLs(serverMetadata, s.appConfig)
+	regServerName := runner.ResolveRegistryServerName(serverMetadata)
 
 	options := []runner.RunConfigBuilderOption{
 		runner.WithRuntime(s.containerRuntime),
@@ -283,6 +284,7 @@ func (s *WorkloadService) BuildFullRunConfig(
 		runner.WithToolsOverride(toolsOverride),
 		runner.WithTelemetryConfigFromFlags("", false, false, false, "", 0.0, nil, false, nil, false),
 		runner.WithRegistrySourceURLs(regAPIURL, regURL),
+		runner.WithRegistryServerName(regServerName),
 	}
 
 	// Add header forward configuration if specified

docs/server/swagger.json

@@ -311,7 +311,7 @@ func TestBuildServerConfig(t *testing.T) {
 			expectError: false, // Actually succeeds and tests the type assertion line
 		},
 		{
-			name:     "registry source URLs are recorded on config",
+			name:     "registry source URLs and server name are recorded on config",
 			imageURL: "test/image:latest",
 			imageMetadata: &regtypes.ImageMetadata{
 				BaseServerMetadata: regtypes.BaseServerMetadata{
@@ -321,12 +321,14 @@ func TestBuildServerConfig(t *testing.T) {
 			},
 			extraOpts: []runner.RunConfigBuilderOption{
 				runner.WithRegistrySourceURLs("https://api.example.com", "https://registry.example.com"),
+				runner.WithRegistryServerName("fetch"),
 			},
 			expectError: false,
 			checkConfig: func(t *testing.T, rc *runner.RunConfig) {
 				t.Helper()
 				assert.Equal(t, "https://api.example.com", rc.RegistryAPIURL)
 				assert.Equal(t, "https://registry.example.com", rc.RegistryURL)
+				assert.Equal(t, "fetch", rc.RegistryServerName)
 			},
 		},
 	}

docs/server/swagger.yaml

@@ -50,8 +50,9 @@ func (h *Handler) RunServer(ctx context.Context, request mcp.CallToolRequest) (*
 		return mcp.NewToolResultError(fmt.Sprintf("Failed to get MCP server: %v", err)), nil
 	}
 
-	// Resolve registry source URLs when the server was discovered via registry lookup.
+	// Resolve registry source URLs and server name when the server was discovered via registry lookup.
 	regAPIURL, regURL := runner.ResolveRegistrySourceURLs(serverMetadata, h.configProvider.GetConfig())
+	regServerName := runner.ResolveRegistryServerName(serverMetadata)
 
 	// Build run configuration.
 	// Use type assertion with nil check to guard against typed nil pointers.
@@ -61,7 +62,8 @@ func (h *Handler) RunServer(ctx context.Context, request mcp.CallToolRequest) (*
 	}
 
 	runConfig, err := buildServerConfig(ctx, args, imageURL, imageMetadata,
-		runner.WithRegistrySourceURLs(regAPIURL, regURL))
+		runner.WithRegistrySourceURLs(regAPIURL, regURL),
+		runner.WithRegistryServerName(regServerName))
 	if err != nil {
 		return mcp.NewToolResultError(fmt.Sprintf("Failed to build run configuration: %v", err)), nil
 	}

pkg/api/v1/workload_service.go

@@ -63,6 +63,10 @@ type RunConfig struct {
 	// Empty when the server was not discovered via registry lookup.
 	RegistryURL string `json:"registry_url,omitempty" yaml:"registry_url,omitempty"`
 
+	// RegistryServerName is the registry entry name used to look up this server's metadata.
+	// Empty when the server was not discovered via registry lookup.
+	RegistryServerName string `json:"registry_server_name,omitempty" yaml:"registry_server_name,omitempty"`
+
 	// RemoteAuthConfig contains OAuth configuration for remote MCP servers
 	RemoteAuthConfig *remote.Config `json:"remote_auth_config,omitempty" yaml:"remote_auth_config,omitempty"`
 

pkg/mcp/server/handler_test.go

@@ -123,6 +123,24 @@ func ResolveRegistrySourceURLs(serverMetadata regtypes.ServerMetadata, appConfig
 	return appConfig.RegistryApiUrl, appConfig.RegistryUrl
 }
 
+// WithRegistryServerName records the registry entry name used to look up this server's metadata.
+func WithRegistryServerName(name string) RunConfigBuilderOption {
+	return func(b *runConfigBuilder) error {
+		b.config.RegistryServerName = name
+		return nil
+	}
+}
+
+// ResolveRegistryServerName returns the registry entry name from server metadata
+// when the server was discovered via registry lookup (non-nil metadata).
+// Returns empty string when metadata is nil (direct image reference or protocol scheme).
+func ResolveRegistryServerName(serverMetadata regtypes.ServerMetadata) string {
+	if serverMetadata == nil {
+		return ""
+	}
+	return serverMetadata.GetName()
+}
+
 // WithRegistryProxyPort sets the proxy port from registry metadata.
 // This is used as a fallback when the CLI --proxy-port flag is not set.
 func WithRegistryProxyPort(port int) RunConfigBuilderOption {

pkg/mcp/server/run_server.go

@@ -1418,3 +1418,80 @@ func TestResolveRegistrySourceURLs(t *testing.T) {
 		})
 	}
 }
+
+func TestWithRegistryServerName(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "name set",
+			input:    "my-server",
+			expected: "my-server",
+		},
+		{
+			name:     "empty name",
+			input:    "",
+			expected: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			builder := &runConfigBuilder{config: NewRunConfig()}
+			opt := WithRegistryServerName(tt.input)
+			err := opt(builder)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, builder.config.RegistryServerName)
+		})
+	}
+}
+
+func TestResolveRegistryServerName(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		serverMetadata regtypes.ServerMetadata
+		expected       string
+	}{
+		{
+			name:           "nil metadata returns empty string",
+			serverMetadata: nil,
+			expected:       "",
+		},
+		{
+			name: "metadata with name set",
+			serverMetadata: &regtypes.ImageMetadata{
+				BaseServerMetadata: regtypes.BaseServerMetadata{
+					Name: "fetch",
+				},
+			},
+			expected: "fetch",
+		},
+		{
+			name: "metadata with empty name",
+			serverMetadata: &regtypes.ImageMetadata{
+				BaseServerMetadata: regtypes.BaseServerMetadata{
+					Name: "",
+				},
+			},
+			expected: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			result := ResolveRegistryServerName(tt.serverMetadata)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}