Add support for creating catalogs from community registry (#406)

This PR adds support for creating a catalog from the community registry (https://registry.modelcontextprotocol.io/) using mcp-gateway. A CI job will publish the catalog as an OCI artifact and upload it to Docker Hub under the mcp namespace `mcp/community-registry`. Users can then manually pull it using `docker mcp catalog pull mcp/community-registry`, keeping it opt-in for now.

The --from-community-registry flag will be used here as an additional CI step to publish the catalog as an OCI artifact: https://github.com/docker/ai-mcp/pull/132/changes

**What I did**

* Add `--from-community-registry` flag to `docker mcp catalog create` to create a catalog with all (oci + remotes for now) community registry servers
* Transforms compatible servers (OCI stdio + remotes) into catalog entries
* Skips incompatible servers (npm, pypi, etc.) with a summary to stderr for unknown errors. These will be supported later on
* Tag imported servers with "community" metadata

**Testing**
```
❯ docker mcp catalog list
Reference | Digest | Title
mcp/docker-mcp-catalog:latest	| c08094360f8d91dd62cedc03ca16fda9df9ea1512e6336294890759b79e1f5f1	| Docker MCP Catalog
❯ docker mcp catalog create justinchang41497/community-registry \
    --from-community-registry registry.modelcontextprotocol.io \
    --title "MCP Community Registry"
Fetched 806 servers from registry.modelcontextprotocol.io
  Total in registry: 1962
  Imported:          806
    OCI (stdio):     101
    Remote:          705
  Skipped:           1156
    npm:             696
    pypi:            338
    no packages:     61
    mcpb:            37
    nuget:           15
    oci:             9
Catalog justinchang41497/community-registry:latest created
❯   docker mcp catalog create justinchang41497/community-registry \
    --from-community-registry registry.modelcontextprotocol.io \
    --title "MCP Community Registry"
❯ docker mcp catalog list
Reference | Digest | Title
justinchang41497/community-registry:latest	| 9f1a00d2a804c0513065de2b8c7ed5df501bbe1cf7cd505d5c2f485e6206d94c	| MCP Community Registry
mcp/docker-mcp-catalog:latest	| c08094360f8d91dd62cedc03ca16fda9df9ea1512e6336294890759b79e1f5f1	| Docker MCP Catalog
```

Push catalog as OCI artifact:
```
❯ docker mcp catalog push justinchang41497/community-registry
Pushed catalog to justinchang41497/community-registry:latest@sha256:9f1a00d2a804c0513065de2b8c7ed5df501bbe1cf7cd505d5c2f485e6206d94c
```

Pulling catalog directly instead of creating it:

```
❯   docker mcp catalog pull justinchang41497/community-registry
Catalog justinchang41497/community-registry:latest pulled
```

**Related issue**
<!-- If this is a bug fix, make sure your description includes "fixes #xxxx", or "closes #xxxx" -->

**(not mandatory) A picture of a cute animal, if possible in relation to what you did**
<img width="612" height="545" alt="image" src="https://github.com/user-attachments/assets/c1580ff2-bd47-458b-9392-b5340fedc7e6" />

Author: jchangx

cmd/docker-mcp/commands/catalog_next.go

@@ -35,19 +35,30 @@ func catalogNextCommand() *cobra.Command {
 
 func createCatalogNextCommand() *cobra.Command {
 	var opts struct {
-		Title             string
-		FromWorkingSet    string
-		FromLegacyCatalog string
-		Servers           []string
+		Title                 string
+		FromWorkingSet        string
+		FromLegacyCatalog     string
+		FromCommunityRegistry string
+		Servers               []string
 	}
 
 	cmd := &cobra.Command{
-		Use:   "create <oci-reference> [--server <ref1> --server <ref2> ...] [--from-profile <profile-id>] [--from-legacy-catalog <url>] [--title <title>]",
-		Short: "Create a new catalog from a profile or legacy catalog",
+		Use:   "create <oci-reference> [--server <ref1> --server <ref2> ...] [--from-profile <profile-id>] [--from-legacy-catalog <url>] [--from-community-registry <hostname>] [--title <title>]",
+		Short: "Create a new catalog from a profile, legacy catalog, or community registry",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if opts.FromWorkingSet != "" && opts.FromLegacyCatalog != "" {
-				return fmt.Errorf("cannot use both --from-profile and --from-legacy-catalog")
+			sourceCount := 0
+			if opts.FromWorkingSet != "" {
+				sourceCount++
+			}
+			if opts.FromLegacyCatalog != "" {
+				sourceCount++
+			}
+			if opts.FromCommunityRegistry != "" {
+				sourceCount++
+			}
+			if sourceCount > 1 {
+				return fmt.Errorf("only one of --from-profile, --from-legacy-catalog, or --from-community-registry can be specified")
 			}
 
 			dao, err := db.New()
@@ -56,14 +67,15 @@ func createCatalogNextCommand() *cobra.Command {
 			}
 			registryClient := registryapi.NewClient()
 			ociService := oci.NewService()
-			return catalognext.Create(cmd.Context(), dao, registryClient, ociService, args[0], opts.Servers, opts.FromWorkingSet, opts.FromLegacyCatalog, opts.Title)
+			return catalognext.Create(cmd.Context(), dao, registryClient, ociService, args[0], opts.Servers, opts.FromWorkingSet, opts.FromLegacyCatalog, opts.FromCommunityRegistry, opts.Title)
 		},
 	}
 
 	flags := cmd.Flags()
 	flags.StringArrayVar(&opts.Servers, "server", []string{}, "Server to include specified with a URI: https:// (MCP Registry reference) or docker:// (Docker Image reference) or catalog:// (Catalog reference) or file:// (Local file path). Can be specified multiple times.")
 	flags.StringVar(&opts.FromWorkingSet, "from-profile", "", "Profile ID to create the catalog from")
 	flags.StringVar(&opts.FromLegacyCatalog, "from-legacy-catalog", "", "Legacy catalog URL to create the catalog from")
+	flags.StringVar(&opts.FromCommunityRegistry, "from-community-registry", "", "Community registry hostname to fetch servers from (e.g. registry.modelcontextprotocol.io)")
 	flags.StringVar(&opts.Title, "title", "", "Title of the catalog")
 
 	return cmd

pkg/catalog/registry_to_catalog.go

@@ -2,6 +2,7 @@ package catalog
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"strings"
 
@@ -11,6 +12,10 @@ import (
 	"github.com/docker/mcp-gateway/pkg/registryapi"
 )
 
+// ErrIncompatibleServer is returned by TransformToDocker when the server has
+// no compatible package type (e.g. no OCI+stdio package and no remote).
+var ErrIncompatibleServer = errors.New("incompatible server")
+
 // Type aliases for imported types from the registry package
 type (
 	ServerDetail  = v0.ServerJSON
@@ -380,7 +385,7 @@ func TransformToDocker(serverDetail ServerDetail) (*Server, error) {
 
 	// Validate that we have at least one way to run the server
 	if server.Image == "" && server.Remote.URL == "" {
-		return nil, fmt.Errorf("no OCI packages found")
+		return nil, fmt.Errorf("%w: no compatible packages for %s", ErrIncompatibleServer, serverDetail.Name)
 	}
 
 	// Add config schema if we have config variables

pkg/catalog_next/catalog.go

@@ -45,6 +45,7 @@ const (
 	SourcePrefixLegacyCatalog = "legacy-catalog:"
 	SourcePrefixOCI           = "oci:"
 	SourcePrefixUser          = "user:"
+	SourcePrefixRegistry      = "registry:"
 )
 
 type Server struct {

pkg/catalog_next/create.go

@@ -5,7 +5,9 @@ import (
 	"database/sql"
 	"errors"
 	"fmt"
+	"os"
 	"slices"
+	"sort"
 	"strings"
 	"time"
 
@@ -19,7 +21,7 @@ import (
 	"github.com/docker/mcp-gateway/pkg/workingset"
 )
 
-func Create(ctx context.Context, dao db.DAO, registryClient registryapi.Client, ociService oci.Service, refStr string, servers []string, workingSetID string, legacyCatalogURL string, title string) error {
+func Create(ctx context.Context, dao db.DAO, registryClient registryapi.Client, ociService oci.Service, refStr string, servers []string, workingSetID string, legacyCatalogURL string, communityRegistryRef string, title string) error {
 	telemetry.Init()
 	start := time.Now()
 	var success bool
@@ -46,10 +48,15 @@ func Create(ctx context.Context, dao db.DAO, registryClient registryapi.Client,
 		if err != nil {
 			return fmt.Errorf("failed to create catalog from legacy catalog: %w", err)
 		}
+	} else if communityRegistryRef != "" {
+		catalog, err = createCatalogFromCommunityRegistry(ctx, registryClient, communityRegistryRef)
+		if err != nil {
+			return fmt.Errorf("failed to create catalog from community registry: %w", err)
+		}
 	} else {
 		// Construct from servers
 		if title == "" {
-			return fmt.Errorf("title is required when creating a catalog without using an existing legacy catalog or profile")
+			return fmt.Errorf("title is required when creating a catalog without using an existing legacy catalog, profile, or community registry")
 		}
 		catalog = Catalog{
 			CatalogArtifact: CatalogArtifact{
@@ -191,3 +198,139 @@ func workingSetServerToCatalogServer(server workingset.Server) Server {
 		Snapshot: server.Snapshot,
 	}
 }
+
+type communityRegistryResult struct {
+	serversAdded   int
+	serversOCI     int
+	serversRemote  int
+	serversSkipped int
+	totalServers   int
+	skippedByType  map[string]int
+}
+
+func createCatalogFromCommunityRegistry(ctx context.Context, registryClient registryapi.Client, registryRef string) (Catalog, error) {
+	baseURL := "https://" + registryRef
+	servers, err := registryClient.ListServers(ctx, baseURL, "")
+	if err != nil {
+		return Catalog{}, fmt.Errorf("failed to fetch servers from community registry: %w", err)
+	}
+
+	catalogServers := make([]Server, 0)
+	skippedByType := make(map[string]int)
+	var ociCount, remoteCount int
+
+	for _, serverResp := range servers {
+		catalogServer, err := legacycatalog.TransformToDocker(serverResp.Server)
+		if err != nil {
+			if !errors.Is(err, legacycatalog.ErrIncompatibleServer) {
+				fmt.Fprintf(os.Stderr, "Warning: failed to transform server %q: %v\n", serverResp.Server.Name, err)
+			}
+			if len(serverResp.Server.Packages) > 0 {
+				skippedByType[serverResp.Server.Packages[0].RegistryType]++
+			} else {
+				skippedByType["none"]++
+			}
+			continue
+		}
+
+		// Tag with "community" for source identification
+		if catalogServer.Metadata == nil {
+			catalogServer.Metadata = &legacycatalog.Metadata{}
+		}
+		catalogServer.Metadata.Tags = appendIfMissing(catalogServer.Metadata.Tags, "community")
+
+		var s Server
+		switch catalogServer.Type {
+		case "server":
+			ociCount++
+			s = Server{
+				Type:  workingset.ServerTypeImage,
+				Image: catalogServer.Image,
+				Snapshot: &workingset.ServerSnapshot{
+					Server: *catalogServer,
+				},
+			}
+		case "remote":
+			remoteCount++
+			s = Server{
+				Type:     workingset.ServerTypeRemote,
+				Endpoint: catalogServer.Remote.URL,
+				Snapshot: &workingset.ServerSnapshot{
+					Server: *catalogServer,
+				},
+			}
+		default:
+			continue
+		}
+		catalogServers = append(catalogServers, s)
+	}
+
+	slices.SortStableFunc(catalogServers, func(a, b Server) int {
+		return strings.Compare(a.Snapshot.Server.Name, b.Snapshot.Server.Name)
+	})
+
+	result := communityRegistryResult{
+		serversAdded:   len(catalogServers),
+		serversOCI:     ociCount,
+		serversRemote:  remoteCount,
+		serversSkipped: totalSkipped(skippedByType),
+		totalServers:   len(servers),
+		skippedByType:  skippedByType,
+	}
+	printCommunityRegistryResult(registryRef, result)
+
+	return Catalog{
+		CatalogArtifact: CatalogArtifact{
+			Title:   "MCP Community Registry",
+			Servers: catalogServers,
+		},
+		Source: SourcePrefixRegistry + registryRef,
+	}, nil
+}
+
+func totalSkipped(skippedByType map[string]int) int {
+	total := 0
+	for _, count := range skippedByType {
+		total += count
+	}
+	return total
+}
+
+func printCommunityRegistryResult(refStr string, result communityRegistryResult) {
+	fmt.Fprintf(os.Stderr, "Fetched %d servers from %s\n", result.serversAdded, refStr)
+	fmt.Fprintf(os.Stderr, "  Total in registry: %d\n", result.totalServers)
+	fmt.Fprintf(os.Stderr, "  Imported:          %d\n", result.serversAdded)
+	fmt.Fprintf(os.Stderr, "    OCI (stdio):     %d\n", result.serversOCI)
+	fmt.Fprintf(os.Stderr, "    Remote:          %d\n", result.serversRemote)
+	fmt.Fprintf(os.Stderr, "  Skipped:           %d\n", result.serversSkipped)
+
+	if len(result.skippedByType) > 0 {
+		type typeCount struct {
+			name  string
+			count int
+		}
+		var sorted []typeCount
+		for t, c := range result.skippedByType {
+			sorted = append(sorted, typeCount{t, c})
+		}
+		sort.Slice(sorted, func(i, j int) bool {
+			return sorted[i].count > sorted[j].count
+		})
+		for _, tc := range sorted {
+			label := tc.name
+			if label == "none" {
+				label = "no packages"
+			}
+			fmt.Fprintf(os.Stderr, "    %-17s%d\n", label+":", tc.count)
+		}
+	}
+}
+
+func appendIfMissing(slice []string, val string) []string {
+	for _, item := range slice {
+		if item == val {
+			return slice
+		}
+	}
+	return append(slice, val)
+}