Merge pull request #146 from docker/slim/list-versus-ls

list versus ls
update docs for using oss mcp community registry

Author: slimslenderslacks

README.md

@@ -84,7 +84,8 @@ docker mcp catalog ls
 docker mcp catalog show docker-mcp
 ```
 
-More about [the MCP Catalog](docs/catalog.md).
+* more about [the MCP Catalog](docs/catalog.md).
+* more about [importing from the OSS MCP Community Registry](docs/catalog.md#importing-from-the-oss-mcp-community-registry).
 
 ### MCP Gateway Operations
 
@@ -106,7 +107,7 @@ Enable and disable the set of MCP servers that will be available for default cli
 
 ```bash
 # List enabled servers
-docker mcp server list
+docker mcp server ls
 
 # Enable one or more servers
 docker mcp server enable <server-name> [server-name...]
@@ -166,10 +167,10 @@ docker mcp --help
 docker mcp tools count
 
 # List all available MCP tools
-docker mcp tools list
+docker mcp tools ls
 
 # List all available MCP tools in JSON format
-docker mcp tools list --format=json
+docker mcp tools ls --format=json
 
 # Inspect a specific tool
 docker mcp tools inspect <tool-name>

cmd/docker-mcp/catalog/ls.go

@@ -9,7 +9,7 @@ import (
 	"github.com/docker/mcp-gateway/cmd/docker-mcp/internal/telemetry"
 )
 
-func Ls(ctx context.Context, outputJSON bool) error {
+func Ls(ctx context.Context, format Format) error {
 	// Initialize telemetry
 	telemetry.Init()
 
@@ -25,7 +25,7 @@ func Ls(ctx context.Context, outputJSON bool) error {
 	// Record successful operation
 	telemetry.RecordCatalogOperation(ctx, "ls", "all", float64(duration.Milliseconds()), true)
 
-	if outputJSON {
+	if format == JSON {
 		data, err := json.Marshal(cfg)
 		if err != nil {
 			return err

cmd/docker-mcp/commands/catalog.go

@@ -58,7 +58,7 @@ command will import servers from the MCP registry URL into that catalog.`,
 			// If mcp-registry flag is provided, import to existing catalog
 			if mcpRegistry != "" {
 				if dryRun {
-					return runOfficialregistryImport(cmd.Context(), mcpRegistry, nil)
+					return runMcpregistryImport(cmd.Context(), mcpRegistry, nil)
 				}
 				return importMCPRegistryToCatalog(cmd.Context(), args[0], mcpRegistry)
 			}
@@ -87,7 +87,7 @@ cannot be exported as it is managed by Docker.`,
 
 func lsCatalogCommand() *cobra.Command {
 	var opts struct {
-		JSON bool
+		Format catalog.Format
 	}
 	cmd := &cobra.Command{
 		Use:   "ls",
@@ -96,15 +96,15 @@ func lsCatalogCommand() *cobra.Command {
 		Args:  cobra.NoArgs,
 		Example: `  # List all catalogs
   docker mcp catalog ls
-  
+
   # List catalogs in JSON format
-  docker mcp catalog ls --json`,
+  docker mcp catalog ls --format=json`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			return catalog.Ls(cmd.Context(), opts.JSON)
+			return catalog.Ls(cmd.Context(), opts.Format)
 		},
 	}
 	flags := cmd.Flags()
-	flags.BoolVar(&opts.JSON, "json", false, "Print as JSON.")
+	flags.Var(&opts.Format, "format", fmt.Sprintf("Output format. Supported: %s.", catalog.SupportedFormats()))
 	return cmd
 }
 
@@ -281,7 +281,7 @@ func importMCPRegistryToCatalog(ctx context.Context, catalogName, mcpRegistryURL
 
 	// Fetch server from MCP registry
 	var servers []catalogTypes.Server
-	if err := runOfficialregistryImport(ctx, mcpRegistryURL, &servers); err != nil {
+	if err := runMcpregistryImport(ctx, mcpRegistryURL, &servers); err != nil {
 		return fmt.Errorf("failed to fetch server from MCP registry: %w", err)
 	}
 

cmd/docker-mcp/commands/feature.go

@@ -118,9 +118,10 @@ func featureDisableCommand(dockerCli command.Cli) *cobra.Command {
 // featureListCommand creates the `feature list` command
 func featureListCommand(dockerCli command.Cli) *cobra.Command {
 	return &cobra.Command{
-		Use:   "list",
-		Short: "List all available features and their status",
-		Long:  "List all available experimental features and show whether they are enabled or disabled.",
+		Use:     "ls",
+		Aliases: []string{"list"},
+		Short:   "List all available features and their status",
+		Long:    "List all available experimental features and show whether they are enabled or disabled.",
 		RunE: func(_ *cobra.Command, _ []string) error {
 			configFile := dockerCli.ConfigFile()
 

cmd/docker-mcp/commands/gateway.go

@@ -110,7 +110,7 @@ func gatewayCommand(docker docker.Client, dockerCli command.Cli) *cobra.Command
 			if len(mcpRegistryUrls) > 0 {
 				var mcpServers []catalogTypes.Server
 				for _, registryURL := range mcpRegistryUrls {
-					if err := runOfficialregistryImport(cmd.Context(), registryURL, &mcpServers); err != nil {
+					if err := runMcpregistryImport(cmd.Context(), registryURL, &mcpServers); err != nil {
 						return fmt.Errorf("failed to fetch server from MCP registry %s: %w", registryURL, err)
 					}
 				}

cmd/docker-mcp/commands/import.go

@@ -11,7 +11,7 @@ import (
 	"github.com/docker/mcp-gateway/cmd/docker-mcp/internal/oci"
 )
 
-func runOfficialregistryImport(ctx context.Context, serverURL string, servers *[]catalog.Server) error {
+func runMcpregistryImport(ctx context.Context, serverURL string, servers *[]catalog.Server) error {
 	// Validate URL
 	parsedURL, err := url.Parse(serverURL)
 	if err != nil {

cmd/docker-mcp/commands/officialregistry_test.go renamed to cmd/docker-mcp/commands/mcpregistry_test.go

@@ -7,7 +7,7 @@ import (
 	"testing"
 )
 
-func TestOfficialregistryImportCommand(t *testing.T) {
+func TestMcpregistryImportCommand(t *testing.T) {
 	// Test server that serves the Garmin MCP example JSON
 	testServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet {
@@ -69,43 +69,43 @@ func TestOfficialregistryImportCommand(t *testing.T) {
 
 	// Test the import function
 	ctx := context.Background()
-	err := runOfficialregistryImport(ctx, testServer.URL, nil)
+	err := runMcpregistryImport(ctx, testServer.URL, nil)
 	if err != nil {
 		t.Errorf("Expected no error, got: %v", err)
 	}
 }
 
-func TestOfficialregistryImportCommand_InvalidURL(t *testing.T) {
+func TestMcpregistryImportCommand_InvalidURL(t *testing.T) {
 	ctx := context.Background()
 
 	// Test invalid URL
-	err := runOfficialregistryImport(ctx, "not-a-url", nil)
+	err := runMcpregistryImport(ctx, "not-a-url", nil)
 	if err == nil {
 		t.Error("Expected error for invalid URL, got none")
 	}
 
 	// Test unsupported scheme
-	err = runOfficialregistryImport(ctx, "ftp://example.com", nil)
+	err = runMcpregistryImport(ctx, "ftp://example.com", nil)
 	if err == nil {
 		t.Error("Expected error for unsupported scheme, got none")
 	}
 }
 
-func TestOfficialregistryImportCommand_HTTPError(t *testing.T) {
+func TestMcpregistryImportCommand_HTTPError(t *testing.T) {
 	// Test server that returns 404
 	testServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 	}))
 	defer testServer.Close()
 
 	ctx := context.Background()
-	err := runOfficialregistryImport(ctx, testServer.URL, nil)
+	err := runMcpregistryImport(ctx, testServer.URL, nil)
 	if err == nil {
 		t.Error("Expected error for 404 response, got none")
 	}
 }
 
-func TestOfficialregistryImportCommand_InvalidJSON(t *testing.T) {
+func TestMcpregistryImportCommand_InvalidJSON(t *testing.T) {
 	// Test server that returns invalid JSON
 	testServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
@@ -118,7 +118,7 @@ func TestOfficialregistryImportCommand_InvalidJSON(t *testing.T) {
 	defer testServer.Close()
 
 	ctx := context.Background()
-	err := runOfficialregistryImport(ctx, testServer.URL, nil)
+	err := runMcpregistryImport(ctx, testServer.URL, nil)
 	if err == nil {
 		t.Error("Expected error for invalid JSON, got none")
 	}

cmd/docker-mcp/commands/server.go

@@ -21,8 +21,8 @@ func serverCommand(docker docker.Client) *cobra.Command {
 
 	var outputJSON bool
 	lsCommand := &cobra.Command{
-		Use:     "list",
-		Aliases: []string{"ls"},
+		Use:     "ls",
+		Aliases: []string{"list"},
 		Short:   "List enabled servers",
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {

cmd/docker-mcp/commands/tools.go

@@ -25,8 +25,8 @@ func toolsCommand(docker docker.Client) *cobra.Command {
 	cmd.PersistentFlags().StringSliceVar(&gatewayArgs, "gateway-arg", nil, "Additional arguments passed to the gateway")
 
 	cmd.AddCommand(&cobra.Command{
-		Use:     "list",
-		Aliases: []string{"ls"},
+		Use:     "ls",
+		Aliases: []string{"list"},
 		Short:   "List tools",
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {

cmd/docker-mcp/internal/gateway/dynamic_mcps.go

@@ -363,17 +363,16 @@ func (g *Gateway) createMcpRemoveTool(_ Configuration, clientConfig *clientConfi
 	}
 }
 
-// mcpOfficialRegistryImportTool implements a tool for importing servers from official registry URLs
-func (g *Gateway) createMcpOfficialRegistryImportTool(configuration Configuration, _ *clientConfig) *ToolRegistration {
+func (g *Gateway) createMcpRegistryImportTool(configuration Configuration, _ *clientConfig) *ToolRegistration {
 	tool := &mcp.Tool{
-		Name:        "mcp-official-registry-import",
-		Description: "Import MCP servers from an official registry URL. Fetches server definitions via HTTP GET and adds them to the local catalog.",
+		Name:        "mcp-registry-import",
+		Description: "Import MCP servers from an MCP registry URL. Fetches server definitions via HTTP GET and adds them to the local catalog.",
 		InputSchema: &jsonschema.Schema{
 			Type: "object",
 			Properties: map[string]*jsonschema.Schema{
 				"url": {
 					Type:        "string",
-					Description: "URL to fetch the official registry JSON from (must be a valid HTTP/HTTPS URL)",
+					Description: "URL to fetch the server details JSON (must be a valid HTTP/HTTPS URL)",
 				},
 			},
 			Required: []string{"url"},