feat(cli): agent-first output — JSON default, compact index, search, human mode

v1.2.2

Changed:
- JSON is now the default output for list-tools and bare invocation
- Bare 'mcp-cli-ent' outputs compact index: {server: [{name, description}]}
- --human flag switches to terminal output (terse by default)
- --human --verbose expands to 4-line format (desc, params, call)
- All stdout pollution removed in JSON mode (headers, errors → stderr)
- Empty results return structured JSON error with error_code

Added:
- --search <query> filters tools by name/description (case-insensitive)
- --verbose in JSON mode includes full inputSchema
- Shared JSONTool, indexTool types and encodeErrorJSON helper

Fixed:
- Dead verbose branch removed (identical if/else output)
- Server count after search uses actual matching servers
- Deterministic output: server keys sorted alphabetically
- jsonServer dead code deleted
- desc/description field name consistency across commands

Author: EstebanForge

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to MCP CLI-Ent will be documented in this file.
 
+<!-- RELEASE:START 1.2.2 -->
+## [1.2.2] - 2026-06-08
+
+### Changed
+
+- **JSON is now the default output format** for `list-tools` and bare `mcp-cli-ent` invocation. Agents parse structured JSON natively; `--human` flag switches to terminal-readable output.
+- **Terse human output by default**: `--human` output shows one line per tool (`name: description`). Use `--human --verbose` for expanded 4-line format (desc, params, call).
+- **Dead verbose branch removed**: The `if verbose`/`else` block in `listToolsFromServer` produced identical output regardless of flag. Deleted.
+
+### Added
+
+- **`--human` flag**: Switches from JSON to human-readable terminal output.
+- **`--search <query>` flag**: Filters tools by name or description (case-insensitive substring). Works in both JSON and human modes.
+- **`--verbose` now includes full schema**: In JSON mode, `--verbose` adds the complete `inputSchema` for each tool.
+
+### Fixed
+
+- **Server count after search**: `--human --search` now reports the correct number of matching servers instead of total configured servers.
+- **Deterministic JSON output**: Server keys are now sorted alphabetically for stable, diff-friendly output.
+- **Shared `JSONTool` type**: Extracted from local duplicates in `commands.go` and `root.go` to a single package-level type, preventing silent output contract divergence.
+
+<!-- RELEASE:END 1.2.2 -->
+
 <!-- RELEASE:START 1.2.1 -->
 ## [1.2.1] - 2026-06-07
 

VERSION

@@ -1 +1 @@
-1.2.1
+1.2.2

internal/cli/commands.go

@@ -385,11 +385,6 @@ func runListTools(cmd *cobra.Command, args []string) error {
 			return fmt.Errorf("server '%s' is disabled", serverName)
 		}
 
-		// Display server description if available
-		if serverConfig.Description != "" {
-			fmt.Printf("%s - %s\n\n", serverName, serverConfig.Description)
-		}
-
 		return listToolsFromServer(ctx, serverName, serverConfig)
 	}
 }
@@ -452,44 +447,60 @@ func listToolsFromServer(ctx context.Context, serverName string, serverConfig co
 	}
 
 	if len(tools) == 0 {
-		fmt.Println("No tools found.")
+		if humanOutput {
+			fmt.Println("No tools found.")
+		} else {
+			return encodeErrorJSON("no_tools", "No tools found on %s", serverName)
+		}
 		return nil
 	}
 
-	fmt.Printf("Available tools (%d):\n", len(tools))
-	for _, tool := range tools {
-		fmt.Printf("  • %s\n", tool.Name)
-		if tool.Description != "" {
-			fmt.Printf("    desc: %s\n", tool.Description)
-		}
-		if tool.InputSchema != nil {
-			if properties, ok := tool.InputSchema["properties"].(map[string]interface{}); ok {
-				var paramNames []string
-				for name := range properties {
-					paramNames = append(paramNames, name)
-				}
-				if len(paramNames) > 0 {
-					fmt.Printf("    params: %s\n", strings.Join(paramNames, ", "))
-				}
+	// Filter by search query
+	if searchQuery != "" {
+		var filtered []mcp.Tool
+		for _, tool := range tools {
+			if toolMatches(tool, searchQuery) {
+				filtered = append(filtered, tool)
 			}
 		}
-		// Build and display call example
-		exampleArgs := BuildExampleArgs(&tool)
-		if verbose {
-			if exampleArgs == "'{}'" {
-				fmt.Printf("    call: mcp-cli-ent call %s %s\n\n", serverName, tool.Name)
+		if len(filtered) == 0 {
+			if humanOutput {
+				fmt.Printf("No tools matching '%s' found on %s.\n", searchQuery, serverName)
 			} else {
-				fmt.Printf("    call: mcp-cli-ent call %s %s %s\n\n", serverName, tool.Name, exampleArgs)
+				return encodeErrorJSON("no_match", "No tools matching '%s' found on %s", searchQuery, serverName)
 			}
-		} else {
-			if exampleArgs == "'{}'" {
-				fmt.Printf("    call: mcp-cli-ent call %s %s\n\n", serverName, tool.Name)
-			} else {
-				fmt.Printf("    call: mcp-cli-ent call %s %s %s\n\n", serverName, tool.Name, exampleArgs)
+			return nil
+		}
+		tools = filtered
+	}
+
+	// JSON output by default
+	if !humanOutput {
+		result := make([]JSONTool, 0, len(tools))
+		for _, tool := range tools {
+			jt := JSONTool{
+				Name:        tool.Name,
+				Description: tool.Description,
+				Params:      extractParamNames(tool.InputSchema),
+				Call:        buildCallString(serverName, tool.Name, BuildExampleArgs(&tool)),
 			}
+			if verbose {
+				jt.Schema = tool.InputSchema
+			}
+			result = append(result, jt)
 		}
+
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		return enc.Encode(result)
 	}
 
+	// Human-readable output (terse by default, verbose expands)
+	if serverConfig.Description != "" {
+		fmt.Printf("%s - %s\n\n", serverName, serverConfig.Description)
+	}
+	fmt.Printf("Available tools (%d):\n", len(tools))
+	printToolsHuman(tools, serverName, verbose)
 	return nil
 }