Merge pull request #81 from masegraye/task/catalog-management

Enable User-Managed Catalogs for MCP Gateway

Author: slimslenderslacks

cmd/docker-mcp/catalog/add.go

@@ -23,6 +23,11 @@ func ParseAddArgs(dst, src, catalogFile string) *ParsedAddArgs {
 }
 
 func ValidateArgs(args ParsedAddArgs) error {
+	// Prevent users from modifying the Docker catalog
+	if args.Dst == DockerCatalogName {
+		return fmt.Errorf("cannot add servers to catalog '%s' as it is managed by Docker", args.Dst)
+	}
+
 	cfg, err := ReadConfig()
 	if err != nil {
 		return err

cmd/docker-mcp/catalog/bootstrap.go

@@ -0,0 +1,85 @@
+package catalog
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Bootstrap creates a starter catalog file with Docker and Docker Hub server entries as examples
+func Bootstrap(ctx context.Context, outputPath string) error {
+	// Check if output file already exists
+	if _, err := os.Stat(outputPath); err == nil {
+		return fmt.Errorf("file %q already exists - will not overwrite", outputPath)
+	}
+
+	// Load Docker catalog configuration
+	_, err := ReadConfigWithDefaultCatalog(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to load Docker catalog config: %w", err)
+	}
+
+	// Read Docker catalog YAML data
+	dockerCatalogData, err := ReadCatalogFile(DockerCatalogName)
+	if err != nil {
+		return fmt.Errorf("failed to read Docker catalog: %w", err)
+	}
+
+	// Parse the Docker catalog to extract server entries
+	var dockerCatalog map[string]any
+	if err := yaml.Unmarshal(dockerCatalogData, &dockerCatalog); err != nil {
+		return fmt.Errorf("failed to parse Docker catalog: %w", err)
+	}
+
+	// Extract registry section
+	registryInterface, ok := dockerCatalog["registry"]
+	if !ok {
+		return fmt.Errorf("docker catalog missing 'registry' section")
+	}
+
+	registry, ok := registryInterface.(map[string]any)
+	if !ok {
+		return fmt.Errorf("docker catalog 'registry' section is not a map")
+	}
+
+	// Extract Docker and Docker Hub servers
+	dockerHubServer, hasDockerHub := registry[DockerHubServerName]
+	dockerCLIServer, hasDockerCLI := registry[DockerCLIServerName]
+
+	if !hasDockerHub {
+		return fmt.Errorf("docker catalog missing '%s' server", DockerHubServerName)
+	}
+	if !hasDockerCLI {
+		return fmt.Errorf("docker catalog missing '%s' server", DockerCLIServerName)
+	}
+
+	// Create bootstrap catalog with just the Docker servers
+	bootstrapCatalog := map[string]any{
+		"registry": map[string]any{
+			DockerHubServerName: dockerHubServer,
+			DockerCLIServerName: dockerCLIServer,
+		},
+	}
+
+	// Marshal to YAML
+	bootstrapData, err := yaml.Marshal(bootstrapCatalog)
+	if err != nil {
+		return fmt.Errorf("failed to marshal bootstrap catalog: %w", err)
+	}
+
+	// Create output directory if it doesn't exist
+	outputDir := filepath.Dir(outputPath)
+	if err := os.MkdirAll(outputDir, 0o755); err != nil {
+		return fmt.Errorf("failed to create output directory: %w", err)
+	}
+
+	// Write the bootstrap catalog file
+	if err := os.WriteFile(outputPath, bootstrapData, 0o644); err != nil {
+		return fmt.Errorf("failed to write bootstrap catalog file: %w", err)
+	}
+
+	return nil
+}

cmd/docker-mcp/catalog/catalog.go

@@ -9,8 +9,13 @@ import (
 )
 
 const (
-	DockerCatalogName = "docker-mcp"
-	DockerCatalogURL  = "https://desktop.docker.com/mcp/catalog/v2/catalog.yaml"
+	DockerCatalogName     = "docker-mcp"
+	DockerCatalogURL      = "https://desktop.docker.com/mcp/catalog/v2/catalog.yaml"
+	DockerCatalogFilename = "docker-mcp.yaml"
+
+	// Docker server names for bootstrap command
+	DockerHubServerName = "dockerhub"
+	DockerCLIServerName = "docker"
 )
 
 var aliasToURL = map[string]string{

cmd/docker-mcp/catalog/create.go

@@ -5,6 +5,11 @@ import (
 )
 
 func Create(name string) error {
+	// Prevent users from creating the Docker catalog
+	if name == DockerCatalogName {
+		return fmt.Errorf("cannot create catalog '%s' as it is reserved for Docker's official catalog", name)
+	}
+
 	cfg, err := ReadConfig()
 	if err != nil {
 		return err

cmd/docker-mcp/catalog/export.go

@@ -0,0 +1,115 @@
+package catalog
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/docker/mcp-gateway/cmd/docker-mcp/internal/catalog"
+	"github.com/docker/mcp-gateway/cmd/docker-mcp/internal/user"
+)
+
+// Export exports a configured catalog to a file
+// This function only allows exporting user-managed catalogs, not the Docker catalog
+func Export(_ context.Context, catalogName, outputPath string) error {
+	// Validate that we're not trying to export the Docker catalog
+	if catalogName == DockerCatalogName || catalogName == DockerCatalogFilename {
+		return fmt.Errorf("cannot export the Docker MCP catalog as it is managed by Docker")
+	}
+
+	// Get configured catalogs to verify the catalog exists
+	configuredCatalogs, err := getConfiguredCatalogs()
+	if err != nil {
+		return fmt.Errorf("failed to read configured catalogs: %w", err)
+	}
+
+	// Check if the catalog exists in the configured catalogs
+	catalogFileName := catalogName + ".yaml"
+	found := false
+	for _, configuredCatalog := range configuredCatalogs {
+		if configuredCatalog == catalogFileName {
+			found = true
+			break
+		}
+	}
+
+	if !found {
+		return fmt.Errorf("catalog '%s' not found in configured catalogs", catalogName)
+	}
+
+	// Read the catalog file
+	homeDir, err := user.HomeDir()
+	if err != nil {
+		return fmt.Errorf("failed to get home directory: %w", err)
+	}
+
+	catalogPath := filepath.Join(homeDir, ".docker", "mcp", "catalogs", catalogFileName)
+	catalogData, err := os.ReadFile(catalogPath)
+	if err != nil {
+		return fmt.Errorf("failed to read catalog file: %w", err)
+	}
+
+	// Parse the catalog to validate it
+	var catalogContent catalog.Catalog
+	if err := yaml.Unmarshal(catalogData, &catalogContent); err != nil {
+		return fmt.Errorf("failed to parse catalog: %w", err)
+	}
+
+	// Create output directory if it doesn't exist
+	outputDir := filepath.Dir(outputPath)
+	if err := os.MkdirAll(outputDir, 0o755); err != nil {
+		return fmt.Errorf("failed to create output directory: %w", err)
+	}
+
+	// Write the catalog to the output file
+	if err := os.WriteFile(outputPath, catalogData, 0o644); err != nil {
+		return fmt.Errorf("failed to write export file: %w", err)
+	}
+
+	fmt.Printf("Catalog '%s' exported to '%s'\n", catalogName, outputPath)
+	return nil
+}
+
+// Helper function to get configured catalogs (same logic as in internal/catalog)
+func getConfiguredCatalogs() ([]string, error) {
+	homeDir, err := user.HomeDir()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get home directory: %w", err)
+	}
+
+	catalogRegistryPath := filepath.Join(homeDir, ".docker", "mcp", "catalog.json")
+
+	// Read the catalog registry file
+	data, err := os.ReadFile(catalogRegistryPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return []string{}, nil // No configured catalogs, return empty list
+		}
+		return nil, fmt.Errorf("failed to read catalog registry: %w", err)
+	}
+
+	// Parse the registry
+	var registry struct {
+		Catalogs map[string]struct {
+			DisplayName string `json:"displayName"`
+			URL         string `json:"url"`
+			LastUpdate  string `json:"lastUpdate"`
+		} `json:"catalogs"`
+	}
+
+	if err := json.Unmarshal(data, &registry); err != nil {
+		return nil, fmt.Errorf("failed to parse catalog registry: %w", err)
+	}
+
+	// Convert catalog names to file paths
+	var catalogFiles []string
+	for catalogName := range registry.Catalogs {
+		catalogFiles = append(catalogFiles, catalogName+".yaml")
+	}
+
+	return catalogFiles, nil
+}

cmd/docker-mcp/catalog/fork.go

@@ -5,13 +5,23 @@ import (
 )
 
 func Fork(src, dst string) error {
+	// Prevent users from creating a destination catalog with the Docker name
+	if dst == DockerCatalogName {
+		return fmt.Errorf("cannot create catalog '%s' as it is reserved for Docker's official catalog", dst)
+	}
+
 	cfg, err := ReadConfig()
 	if err != nil {
 		return err
 	}
-	if _, ok := cfg.Catalogs[src]; !ok {
-		return fmt.Errorf("catalog %q not found", src)
+
+	// Special handling for Docker catalog - it exists but not in cfg.Catalogs
+	if src != DockerCatalogName {
+		if _, ok := cfg.Catalogs[src]; !ok {
+			return fmt.Errorf("catalog %q not found", src)
+		}
 	}
+
 	if _, ok := cfg.Catalogs[dst]; ok {
 		return fmt.Errorf("catalog %q already exists", dst)
 	}

cmd/docker-mcp/catalog/rm.go

@@ -7,6 +7,11 @@ import (
 )
 
 func Rm(name string) error {
+	// Prevent users from removing the Docker catalog
+	if name == DockerCatalogName {
+		return fmt.Errorf("cannot remove catalog '%s' as it is managed by Docker", name)
+	}
+
 	cfg, err := ReadConfig()
 	if err != nil {
 		return err

cmd/docker-mcp/commands/bootstrap.go

@@ -0,0 +1,24 @@
+package commands
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/docker/mcp-gateway/cmd/docker-mcp/catalog"
+)
+
+func bootstrapCatalogCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "bootstrap <output-file-path>",
+		Short: "Create a starter catalog file with Docker and Docker Hub server entries as examples",
+		Long: `Create a starter catalog file with Docker Hub and Docker CLI server entries as examples.
+This command extracts the official Docker server definitions and creates a properly formatted
+catalog file that users can modify and use as a foundation for their custom catalogs.
+
+The output file is standalone and not automatically imported - users can modify it and then
+import it or use it as a source for the 'catalog add' command.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return catalog.Bootstrap(cmd.Context(), args[0])
+		},
+	}
+}