Refactor "mcp-inspect" to nested "mcp inspect" command structure

cmd/gh-aw/main.go

@@ -373,7 +373,7 @@ func init() {
 	rootCmd.AddCommand(enableCmd)
 	rootCmd.AddCommand(disableCmd)
 	rootCmd.AddCommand(cli.NewLogsCommand())
-	rootCmd.AddCommand(cli.NewMCPInspectCommand())
+	rootCmd.AddCommand(cli.NewMCPCommand())
 	rootCmd.AddCommand(versionCmd)
 }
 

cmd/gh-aw/main_entry_test.go

@@ -309,7 +309,7 @@ func TestCommandLineIntegration(t *testing.T) {
 
 	t.Run("command structure validation", func(t *testing.T) {
 		// Test that essential commands are present
-		expectedCommands := []string{"add", "compile", "list", "remove", "status", "run", "version"}
+		expectedCommands := []string{"add", "compile", "list", "remove", "status", "run", "version", "mcp"}
 
 		cmdMap := make(map[string]bool)
 		for _, cmd := range rootCmd.Commands() {
@@ -341,6 +341,61 @@ func TestCommandLineIntegration(t *testing.T) {
 	})
 }
 
+func TestMCPCommand(t *testing.T) {
+	// Test the new MCP command structure
+	t.Run("mcp command is available", func(t *testing.T) {
+		found := false
+		for _, cmd := range rootCmd.Commands() {
+			if cmd.Name() == "mcp" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Error("mcp command should be available")
+		}
+	})
+
+	t.Run("mcp command has inspect subcommand", func(t *testing.T) {
+		mcpCmd, _, _ := rootCmd.Find([]string{"mcp"})
+		if mcpCmd == nil {
+			t.Fatal("mcp command not found")
+		}
+
+		found := false
+		for _, subCmd := range mcpCmd.Commands() {
+			if subCmd.Name() == "inspect" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Error("mcp inspect subcommand should be available")
+		}
+	})
+
+	t.Run("mcp inspect command help", func(t *testing.T) {
+		// Test help for nested command
+		mcpCmd, _, _ := rootCmd.Find([]string{"mcp"})
+		if mcpCmd == nil {
+			t.Fatal("mcp command not found")
+		}
+
+		inspectCmd, _, _ := mcpCmd.Find([]string{"inspect"})
+		if inspectCmd == nil {
+			t.Fatal("mcp inspect command not found")
+		}
+
+		// Basic validation that command structure is valid
+		if inspectCmd.Use == "" {
+			t.Error("mcp inspect command should have usage text")
+		}
+		if inspectCmd.Short == "" {
+			t.Error("mcp inspect command should have short description")
+		}
+	})
+}
+
 func TestCommandErrorHandling(t *testing.T) {
 	t.Run("invalid command produces error", func(t *testing.T) {
 		// Capture stderr

docs/src/content/docs/guides/mcps.md

@@ -41,7 +41,7 @@ tools:
 
 > [!TIP]
 > You can inspect test your MCP configuration by running <br/>
-> `gh aw mcp-inspect <workflow-file>`
+> `gh aw mcp inspect <workflow-file>`
 
 
 ### Engine Compatibility
@@ -236,23 +236,23 @@ The compiler enforces these network permission rules:
 
 ### MCP Server Inspection
 
-Use the `mcp-inspect` command to analyze and troubleshoot MCP configurations:
+Use the `mcp inspect` command to analyze and troubleshoot MCP configurations:
 
 ```bash
 # List all workflows with MCP servers configured
-gh aw mcp-inspect
+gh aw mcp inspect
 
 # Inspect all MCP servers in a specific workflow
-gh aw mcp-inspect my-workflow
+gh aw mcp inspect my-workflow
 
 # Inspect a specific MCP server in a workflow
-gh aw mcp-inspect my-workflow --server trello-server
+gh aw mcp inspect my-workflow --server trello-server
 
 # Enable verbose output for debugging connection issues
-gh aw mcp-inspect my-workflow --verbose
+gh aw mcp inspect my-workflow --verbose
 
 # Launch official MCP inspector web interface
-gh aw mcp-inspect my-workflow --inspector
+gh aw mcp inspect my-workflow --inspector
 
 ### Common Issues and Solutions
 
@@ -278,7 +278,7 @@ Error: Tool 'my_tool' not found
 
 **Solutions**:
 1. Add tool to `allowed` list
-2. Check tool name spelling (use `gh aw mcp-inspect` to see available tools)
+2. Check tool name spelling (use `gh aw mcp inspect` to see available tools)
 3. Verify MCP server is running correctly
 
 ## Related Documentation

docs/src/content/docs/tools/cli.md

@@ -189,28 +189,28 @@ gh aw logs --format json -o ./exports/
 
 ## 🔍 MCP Server Inspection
 
-The `mcp-inspect` command allows you to analyze and troubleshoot Model Context Protocol (MCP) servers configured in your workflows.
+The `mcp inspect` command allows you to analyze and troubleshoot Model Context Protocol (MCP) servers configured in your workflows.
 
 > **📘 Complete MCP Guide**: For comprehensive MCP setup, configuration examples, and troubleshooting, see the [MCPs](/gh-aw/guides/mcps/).
 
 ```bash
 # List all workflows that contain MCP server configurations
-gh aw mcp-inspect
+gh aw mcp inspect
 
 # Inspect all MCP servers in a specific workflow
-gh aw mcp-inspect workflow-name
+gh aw mcp inspect workflow-name
 
 # Filter inspection to specific servers by name
-gh aw mcp-inspect workflow-name --server server-name
+gh aw mcp inspect workflow-name --server server-name
 
 # Show detailed information about a specific tool (requires --server)
-gh aw mcp-inspect workflow-name --server server-name --tool tool-name
+gh aw mcp inspect workflow-name --server server-name --tool tool-name
 
 # Enable verbose output with connection details
-gh aw mcp-inspect workflow-name --verbose
+gh aw mcp inspect workflow-name --verbose
 
 # Launch the official @modelcontextprotocol/inspector web interface
-gh aw mcp-inspect workflow-name --inspector
+gh aw mcp inspect workflow-name --inspector
 ```
 
 **Key Features:**

pkg/cli/mcp.go

@@ -0,0 +1,29 @@
+package cli
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// NewMCPCommand creates the main mcp command with subcommands
+func NewMCPCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "mcp",
+		Short: "Model Context Protocol (MCP) server management and inspection",
+		Long: `Model Context Protocol (MCP) server management and inspection.
+
+MCP enables AI workflows to connect to external tools and data sources through
+standardized servers. This command provides tools for inspecting and managing
+MCP server configurations in your agentic workflows.
+
+Available subcommands:
+  inspect  - Inspect MCP servers and list available tools, resources, and roots`,
+		Run: func(cmd *cobra.Command, args []string) {
+			_ = cmd.Help()
+		},
+	}
+
+	// Add subcommands
+	cmd.AddCommand(NewMCPInspectSubcommand())
+
+	return cmd
+}

pkg/cli/mcp_inspect.go

@@ -184,7 +184,7 @@ func listWorkflowsWithMCP(workflowsDir string, verbose bool) error {
 	for _, workflow := range workflowsWithMCP {
 		fmt.Printf("  • %s\n", workflow)
 	}
-	fmt.Printf("\nRun 'gh aw mcp-inspect <workflow-name>' to inspect MCP servers in a specific workflow.\n")
+	fmt.Printf("\nRun 'gh aw mcp inspect <workflow-name>' to inspect MCP servers in a specific workflow.\n")
 
 	return nil
 }
@@ -452,3 +452,73 @@ func spawnMCPInspector(workflowFile string, serverFilter string, verbose bool) e
 
 	return cmd.Run()
 }
+
+// NewMCPInspectSubcommand creates the mcp inspect subcommand
+// This is the former mcp-inspect command now nested under mcp
+func NewMCPInspectSubcommand() *cobra.Command {
+	var serverFilter string
+	var toolFilter string
+	var spawnInspector bool
+
+	cmd := &cobra.Command{
+		Use:   "inspect [workflow-file]",
+		Short: "Inspect MCP servers and list available tools, resources, and roots",
+		Long: `Inspect MCP servers used by a workflow and display available tools, resources, and roots.
+
+This command starts each MCP server configured in the workflow, queries its capabilities,
+and displays the results in a formatted table. It supports stdio, Docker, and HTTP MCP servers.
+
+Examples:
+  gh aw mcp inspect                    # List workflows with MCP servers
+  gh aw mcp inspect weekly-research    # Inspect MCP servers in weekly-research.md  
+  gh aw mcp inspect weekly-research --server github --tool create_issue  # Show details for a specific tool
+  gh aw mcp inspect weekly-research -v # Verbose output with detailed connection info
+  gh aw mcp inspect weekly-research --inspector  # Launch @modelcontextprotocol/inspector
+
+The command will:
+- Parse the workflow file to extract MCP server configurations
+- Start each MCP server (stdio, docker, http)
+- Query available tools, resources, and roots
+- Validate required secrets are available  
+- Display results in formatted tables with error details`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			var workflowFile string
+			if len(args) > 0 {
+				workflowFile = args[0]
+			}
+
+			verbose, _ := cmd.Flags().GetBool("verbose")
+			// Check for verbose flag from parent commands (root and mcp)
+			if cmd.Parent() != nil {
+				if parentVerbose, _ := cmd.Parent().PersistentFlags().GetBool("verbose"); parentVerbose {
+					verbose = true
+				}
+				if cmd.Parent().Parent() != nil {
+					if rootVerbose, _ := cmd.Parent().Parent().PersistentFlags().GetBool("verbose"); rootVerbose {
+						verbose = true
+					}
+				}
+			}
+
+			// Validate that tool flag requires server flag
+			if toolFilter != "" && serverFilter == "" {
+				return fmt.Errorf("--tool flag requires --server flag to be specified")
+			}
+
+			// Handle spawn inspector flag
+			if spawnInspector {
+				return spawnMCPInspector(workflowFile, serverFilter, verbose)
+			}
+
+			return InspectWorkflowMCP(workflowFile, serverFilter, toolFilter, verbose)
+		},
+	}
+
+	cmd.Flags().StringVar(&serverFilter, "server", "", "Filter to inspect only the specified MCP server")
+	cmd.Flags().StringVar(&toolFilter, "tool", "", "Show detailed information about a specific tool (requires --server)")
+	cmd.Flags().BoolP("verbose", "v", false, "Enable verbose output with detailed connection information")
+	cmd.Flags().BoolVar(&spawnInspector, "inspector", false, "Launch the official @modelcontextprotocol/inspector tool")
+
+	return cmd
+}