Standardize MCP command arguments to workflow-id-or-file

pkg/cli/mcp_add.go

@@ -300,7 +300,7 @@ func NewMCPAddSubcommand() *cobra.Command {
 	var customToolID string
 
 	cmd := &cobra.Command{
-		Use:   "add [workflow-file] [mcp-server-name]",
+		Use:   "add [workflow-id-or-file] [mcp-server-name]",
 		Short: "Add an MCP tool to an agentic workflow",
 		Long: `Add an MCP tool to an agentic workflow by searching the MCP registry.
 
@@ -309,6 +309,10 @@ and automatically compiles the workflow. If the tool already exists, the command
 
 When called with no arguments, it will show a list of available MCP servers from the registry.
 
+The workflow-id-or-file can be:
+- A workflow ID (basename without .md extension, e.g., "weekly-research")
+- A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
+
 Examples:
   gh aw mcp add                                          # List available MCP servers
   gh aw mcp add weekly-research makenotion/notion-mcp-server  # Add Notion MCP server to weekly-research.md
@@ -336,9 +340,9 @@ Registry URL defaults to: https://api.mcp.github.com/v0`,
 				return listAvailableServers(registryURL, verbose)
 			}
 
-			// If only workflow file is provided, show error (need both workflow and server)
+			// If only workflow ID/file is provided, show error (need both workflow and server)
 			if len(args) == 1 {
-				return fmt.Errorf("both workflow file and server name are required to add an MCP tool\nUse 'gh aw mcp add' to list available servers")
+				return fmt.Errorf("both workflow ID/file and server name are required to add an MCP tool\nUse 'gh aw mcp add' to list available servers")
 			}
 
 			// If both arguments are provided, add the MCP tool

pkg/cli/mcp_inspect.go

@@ -470,13 +470,17 @@ func NewMCPInspectSubcommand() *cobra.Command {
 	var checkSecrets bool
 
 	cmd := &cobra.Command{
-		Use:   "inspect [workflow-file]",
+		Use:   "inspect [workflow-id-or-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.
 
+The workflow-id-or-file can be:
+- A workflow ID (basename without .md extension, e.g., "weekly-research")
+- A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
+
 Examples:
   gh aw mcp inspect                    # List workflows with MCP servers
   gh aw mcp inspect weekly-research    # Inspect MCP servers in weekly-research.md  

pkg/cli/mcp_list.go

@@ -211,12 +211,16 @@ func listWorkflowsWithMCPServers(workflowsDir string, verbose bool) error {
 // NewMCPListSubcommand creates the mcp list subcommand
 func NewMCPListSubcommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "list [workflow-file]",
+		Use:   "list [workflow-id-or-file]",
 		Short: "List MCP servers defined in agentic workflows",
 		Long: `List MCP servers defined in agentic workflows.
 
-When no workflow file is specified, lists all workflows that contain MCP server configurations.
-When a workflow file is specified, lists the MCP servers configured in that specific workflow.
+When no workflow ID/file is specified, lists all workflows that contain MCP server configurations.
+When a workflow ID/file is specified, lists the MCP servers configured in that specific workflow.
+
+The workflow-id-or-file can be:
+- A workflow ID (basename without .md extension, e.g., "weekly-research")
+- A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
 
 Examples:
   gh aw mcp list                     # List all workflows with MCP servers

pkg/cli/mcp_list_test.go

@@ -156,8 +156,8 @@ on:
 func TestNewMCPListSubcommand(t *testing.T) {
 	cmd := NewMCPListSubcommand()
 
-	if cmd.Use != "list [workflow-file]" {
-		t.Errorf("Expected Use to be 'list [workflow-file]', got %s", cmd.Use)
+	if cmd.Use != "list [workflow-id-or-file]" {
+		t.Errorf("Expected Use to be 'list [workflow-id-or-file]', got %s", cmd.Use)
 	}
 
 	if cmd.Short != "List MCP servers defined in agentic workflows" {

pkg/cli/mcp_list_tools.go

@@ -228,14 +228,18 @@ func displayToolsList(info *parser.MCPServerInfo, verbose bool) {
 // NewMCPListToolsSubcommand creates the mcp list-tools subcommand
 func NewMCPListToolsSubcommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "list-tools <mcp_server> [workflow-file]",
+		Use:   "list-tools <mcp_server> [workflow-id-or-file]",
 		Short: "List available tools for a specific MCP server",
 		Long: `List available tools for a specific MCP server.
 
 This command connects to the specified MCP server and displays all available tools.
 It reuses the same infrastructure as 'mcp inspect' to establish connections and
 query server capabilities.
 
+The workflow-id-or-file can be:
+- A workflow ID (basename without .md extension, e.g., "weekly-research")
+- A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
+
 Examples:
   gh aw mcp list-tools github                    # Find workflows with 'github' MCP server
   gh aw mcp list-tools github weekly-research    # List tools for 'github' server in weekly-research.md

pkg/cli/mcp_list_tools_test.go

@@ -318,8 +318,8 @@ func TestDisplayToolsList(t *testing.T) {
 func TestNewMCPListToolsSubcommand(t *testing.T) {
 	cmd := NewMCPListToolsSubcommand()
 
-	if cmd.Use != "list-tools <mcp_server> [workflow-file]" {
-		t.Errorf("Expected Use to be 'list-tools <mcp_server> [workflow-file]', got: %s", cmd.Use)
+	if cmd.Use != "list-tools <mcp_server> [workflow-id-or-file]" {
+		t.Errorf("Expected Use to be 'list-tools <mcp_server> [workflow-id-or-file]', got: %s", cmd.Use)
 	}
 
 	if cmd.Short != "List available tools for a specific MCP server" {