[v0.8.2] Add filtering positional argument to hatch mcp [discover|show|list] [servers|hosts] commands

README.md

@@ -54,9 +54,10 @@ hatch mcp configure github-mcp --host gemini \
   --httpUrl https://api.github.com/mcp \
   --header Authorization="Bearer $GIT_PAT_TOKEN"
 
-# Register the same server on multiple hosts at once
-hatch mcp configure my-server --host claude-desktop,cursor,vscode \
+# Register the same server on multiple hosts using sync
+hatch mcp configure my-server --host claude-desktop \
   --command python --args "-m my_server"
+hatch mcp sync --from-host claude-desktop --to-host cursor,vscode
 ```
 
 ### Inspect what is configured
@@ -65,8 +66,11 @@ hatch mcp configure my-server --host claude-desktop,cursor,vscode \
 # See all servers across all hosts
 hatch mcp list servers
 
+# Filter servers by name
+hatch mcp list servers weather
+
 # See all hosts a specific server is registered on
-hatch mcp show servers --server "context7"
+hatch mcp show servers context7
 
 # Detect which MCP host platforms are installed
 hatch mcp discover hosts

docs/articles/api/cli/mcp.md

@@ -31,16 +31,22 @@ This module provides handlers for:
 ## Handler Functions
 
 ### Discovery
-- `handle_mcp_discover_hosts()`: Detect available MCP host platforms
-- `handle_mcp_discover_servers()`: Find MCP servers in packages (deprecated)
+- `handle_mcp_discover_hosts(args)`: Detect available MCP host platforms
+  - `filter_name`: Optional positional argument to filter by host name (regex pattern)
+- `handle_mcp_discover_servers(args)`: Find MCP servers in packages (deprecated)
+  - `filter_name`: Optional positional argument to filter by server name (regex pattern)
 
 ### Listing
-- `handle_mcp_list_hosts()`: Host-centric server listing (shows all servers on hosts)
-- `handle_mcp_list_servers()`: Server-centric host listing (shows all hosts for servers)
+- `handle_mcp_list_hosts(args)`: Host-centric server listing (shows all servers on hosts)
+  - `filter_name`: Optional positional argument to filter by host name (regex pattern)
+- `handle_mcp_list_servers(args)`: Server-centric host listing (shows all hosts for servers)
+  - `filter_name`: Optional positional argument to filter by server name (regex pattern)
 
 ### Show Commands
-- `handle_mcp_show_hosts()`: Detailed hierarchical view of host configurations
-- `handle_mcp_show_servers()`: Detailed hierarchical view of server configurations
+- `handle_mcp_show_hosts(args)`: Detailed hierarchical view of host configurations
+  - `filter_name`: Optional positional argument to filter by host name (regex pattern)
+- `handle_mcp_show_servers(args)`: Detailed hierarchical view of server configurations
+  - `filter_name`: Optional positional argument to filter by server name (regex pattern)
 
 ### Configuration
 - `handle_mcp_configure()`: Configure MCP server on host with all host-specific arguments
@@ -69,6 +75,7 @@ def handle_mcp_command(args: Namespace) -> int:
         args: Namespace with:
             - env_manager: HatchEnvironmentManager instance
             - mcp_manager: MCPHostConfigurationManager instance
+            - filter_name: Optional positional argument to filter by name (regex pattern)
             - <command-specific arguments>
 
     Returns:

docs/articles/devs/architecture/mcp_backup_system.md

@@ -192,10 +192,9 @@ Designed for future CLI command integration:
 
 ```bash
 # Future CLI commands
-hatch mcp backup create --host vscode
-hatch mcp backup restore --host vscode --timestamp 20250921_100000_123456
-hatch mcp backup list --host cursor
-hatch mcp backup clean --host claude-desktop --older-than-days 30
+hatch mcp backup restore vscode --backup-file backup_20250921_100000_123456.json
+hatch mcp backup list cursor
+hatch mcp backup clean claude-desktop --older-than-days 30
 ```
 
 ## Testing Architecture

docs/articles/users/CLIReference.md

@@ -518,32 +518,37 @@ Discover available MCP host platforms on the system.
 
 Syntax:
 
-`hatch mcp discover hosts [--json]`
+`hatch mcp discover hosts [filter_name] [--json]`
 
 
-| Flag | Type | Description | Default |
+| Argument / Flag | Type | Description | Default |
 |---:|---|---|---|
+| `filter_name` | string (positional, optional) | Filter by host name using regex pattern | none |
 | `--json` | flag | Output in JSON format | false |
 
 
-**Example Output**:
+**Usage Examples**:
 
 ```bash
+# Show all available host platforms
 $ hatch mcp discover hosts
-Available MCP Host Platforms:
-  Host                Status           Config Path
-  ─────────────────────────────────────────────────────────────────
-  claude-desktop      ✓ Available      /Users/user/.config/claude/...
-  cursor              ✓ Available      /Users/user/.cursor/mcp.json
-  vscode              ✗ Not Found      -
-  mistral-vibe        ✓ Available      /Users/user/.config/mistral/mcp.toml
+
+# Filter to only Claude Desktop
+$ hatch mcp discover hosts claude-desktop
+
+# Filter with regex pattern (case-sensitive)
+$ hatch mcp discover hosts "^cursor|^vscode"
+
+# JSON output with filter
+$ hatch mcp discover hosts cursor --json
 ```
 
 **Key Details**:
 - Header: `"Available MCP Host Platforms:"`
 - Columns: Host (width 18), Status (width 15), Config Path (width "auto")
 - Status: `"✓ Available"` or `"✗ Not Found"`
 - Shows ALL host types (MCPHostType enum), not just available ones
+- `filter_name` accepts Python regex patterns for flexible matching
 
 ---
 
@@ -555,13 +560,35 @@ Discover MCP servers in Hatch environments.
 
 Syntax:
 
-`hatch mcp discover servers [--env ENV]`
+`hatch mcp discover servers [filter_name] [--env ENV]`
 
 
-| Flag | Type | Description | Default |
+| Argument / Flag | Type | Description | Default |
 |---:|---|---|---|
+| `filter_name` | string (positional, optional) | Filter by server name using regex pattern | none |
 | `--env` | string | Specific environment to discover servers in | current environment |
 
+**Usage Examples**:
+
+```bash
+# List all MCP servers in current environment
+$ hatch mcp discover servers
+
+# Filter to specific server by name
+$ hatch mcp discover servers my-server
+
+# Filter with regex pattern
+$ hatch mcp discover servers "^my-.*server$"
+
+# Discover servers in specific environment
+$ hatch mcp discover servers --env test-env
+
+# Combined: filter + specific environment
+$ hatch mcp discover servers hatch-mcp-server --env prod-env
+```
+
+**Note**: This command is deprecated. Use `hatch mcp list servers` instead for more detailed information.
+
 ---
 
 #### `hatch mcp list hosts`
@@ -575,15 +602,38 @@ List host/server pairs from host configuration files.
 
 Syntax:
 
-`hatch mcp list hosts [--server PATTERN] [--json]`
+`hatch mcp list hosts [filter_name] [--server PATTERN] [--json]`
 
 
-| Flag | Type | Description | Default |
+| Argument / Flag | Type | Description | Default |
 |---:|---|---|---|
+| `filter_name` | string (positional, optional) | Filter by host name using regex pattern | none |
 | `--server` | string | Filter by server name using regex pattern | none |
 | `--json` | flag | Output in JSON format | false |
 
 
+**Usage Examples**:
+
+```bash
+# List all hosts and their servers
+$ hatch mcp list hosts
+
+# Filter by specific host
+$ hatch mcp list hosts claude-desktop
+
+# Filter hosts by regex pattern
+$ hatch mcp list hosts "^claude"
+
+# Filter by server (works with or without host filter)
+$ hatch mcp list hosts --server weather
+
+# Combine host and server filters
+$ hatch mcp list hosts claude-desktop --server weather
+
+# JSON output
+$ hatch mcp list hosts cursor --json
+```
+
 **Example Output**:
 
 ```bash
@@ -601,6 +651,7 @@ MCP Hosts:
 - Columns: Host (width 18), Server (width 18), Hatch (width 8), Environment (width 15)
 - Hatch column: `"✅"` for Hatch-managed, `"❌"` for third-party
 - Shows ALL servers on hosts (both Hatch-managed and third-party)
+- `filter_name` is positional and filters hosts; `--server` filters servers separately
 - Environment column: environment name if Hatch-managed, `"-"` otherwise
 - Sorted by: host (alphabetically), then server
 
@@ -615,14 +666,37 @@ List server/host pairs from host configuration files.
 
 Syntax:
 
-`hatch mcp list servers [--host PATTERN] [--json]`
+`hatch mcp list servers [filter_name] [--host PATTERN] [--json]`
 
 
-| Flag | Type | Description | Default |
+| Argument / Flag | Type | Description | Default |
 |---:|---|---|---|
+| `filter_name` | string (positional, optional) | Filter by server name using regex pattern | none |
 | `--host` | string | Filter by host name using regex pattern | none |
 | `--json` | flag | Output in JSON format | false |
 
+**Usage Examples**:
+
+```bash
+# List all servers and their hosts
+$ hatch mcp list servers
+
+# Filter by specific server
+$ hatch mcp list servers weather-server
+
+# Filter servers by regex pattern
+$ hatch mcp list servers "^weather"
+
+# Filter by host (works with or without server filter)
+$ hatch mcp list servers --host claude-desktop
+
+# Combine server and host filters
+$ hatch mcp list servers weather --host cursor
+
+# JSON output
+$ hatch mcp list servers hatch-mcp --json
+```
+
 **Example Output**:
 
 ```bash
@@ -654,14 +728,37 @@ Show detailed hierarchical view of all MCP host configurations.
 
 Syntax:
 
-`hatch mcp show hosts [--server PATTERN] [--json]`
+`hatch mcp show hosts [filter_name] [--server PATTERN] [--json]`
 
 
-| Flag | Type | Description | Default |
+| Argument / Flag | Type | Description | Default |
 |---:|---|---|---|
+| `filter_name` | string (positional, optional) | Filter by host name using regex pattern | none |
 | `--server` | string | Filter by server name using regex pattern | none |
 | `--json` | flag | Output in JSON format | false |
 
+**Usage Examples**:
+
+```bash
+# Show detailed configuration for all hosts
+$ hatch mcp show hosts
+
+# Show configuration for specific host
+$ hatch mcp show hosts claude-desktop
+
+# Show hosts matching regex pattern
+$ hatch mcp show hosts "^cursor|^vscode"
+
+# Filter by server name
+$ hatch mcp show hosts --server weather
+
+# Combine host and server filters
+$ hatch mcp show hosts claude --server weather-server
+
+# JSON output with filter
+$ hatch mcp show hosts cursor --json
+```
+
 **Example Output**:
 
 ```bash
@@ -719,14 +816,37 @@ Show detailed hierarchical view of all MCP server configurations across hosts.
 
 Syntax:
 
-`hatch mcp show servers [--host PATTERN] [--json]`
+`hatch mcp show servers [filter_name] [--host PATTERN] [--json]`
 
 
-| Flag | Type | Description | Default |
+| Argument / Flag | Type | Description | Default |
 |---:|---|---|---|
+| `filter_name` | string (positional, optional) | Filter by server name using regex pattern | none |
 | `--host` | string | Filter by host name using regex pattern | none |
 | `--json` | flag | Output in JSON format | false |
 
+**Usage Examples**:
+
+```bash
+# Show detailed configuration for all servers
+$ hatch mcp show servers
+
+# Show configuration for specific server
+$ hatch mcp show servers weather-server
+
+# Show servers matching regex pattern
+$ hatch mcp show servers "^hatch-.*"
+
+# Filter by host name
+$ hatch mcp show servers --host claude-desktop
+
+# Combine server and host filters
+$ hatch mcp show servers weather --host cursor
+
+# JSON output with filter
+$ hatch mcp show servers "^my-" --json
+```
+
 **Example Output**:
 
 ```bash

docs/articles/users/GettingStarted.md

@@ -174,16 +174,36 @@ Hatch provides multiple commands for viewing your environments, packages, and ho
 
 - `hatch mcp discover hosts`: Detect available MCP host platforms
 
-**Filtering**: All list and show commands support regex filtering:
+**Filtering**: All list and show commands support regex filtering using positional arguments and flags:
+
+**Positional Filter (by position - simple syntax)**:
 ```bash
-# Filter by server name
+# Filter by host name (positional)
+hatch mcp list hosts claude-desktop
+
+# Filter by server name (positional)
+hatch mcp list servers weather-server
+
+# Filter discovery results
+hatch mcp discover hosts claude
+```
+
+**Flag-Based Filtering (regex patterns)**:
+```bash
+# Filter by server name using regex
 hatch mcp list hosts --server "weather.*"
 
-# Filter by host name
+# Filter by host name using regex
 hatch mcp show servers --host "claude.*"
+```
+
+**Compound Filtering (positional + flags together)**:
+```bash
+# Positional filter + server flag
+hatch mcp list servers weather --host ".*desktop"
 
-# Filter by environment
-hatch env list hosts --env "my-project"
+# Positional filter + multiple conditions
+hatch mcp show hosts claude --server "api.*"
 ```
 
 ## Understanding Hatch Concepts