feat: implement CLI output formatting system (Spec 014)

Add unified output formatting for CLI commands with support for
table, JSON, and YAML formats.

Key features:
- Global `-o/--output` flag for format selection (table/json/yaml)
- `--json` shorthand for `-o json`
- `--help-json` flag for machine-readable command discovery
- `MCPPROXY_OUTPUT` environment variable for default format
- Structured error output with recovery hints

Implementation:
- New `internal/cli/output/` package with OutputFormatter interface
- JSONFormatter: pretty-printed, snake_case fields, empty arrays as []
- TableFormatter: aligned columns, Unicode indicators, NO_COLOR support
- YAMLFormatter: using yaml.v3
- HelpInfo types for structured help output

Migrated commands:
- upstream list: full format support
- tools list: full format support
- secrets list: full format support (removed local --json flag)
- call tool: JSON formatter for -o json

Documentation:
- docs/cli-output-formatting.md: complete usage guide
- Updated CLAUDE.md with output formatting section

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Dumbris

CLAUDE.md

@@ -61,6 +61,19 @@ mcpproxy doctor                     # Run health checks
 
 See [docs/cli-management-commands.md](docs/cli-management-commands.md) for complete reference.
 
+### CLI Output Formatting
+```bash
+mcpproxy upstream list -o json      # JSON output for scripting
+mcpproxy upstream list -o yaml      # YAML output
+mcpproxy upstream list --json       # Shorthand for -o json
+mcpproxy --help-json                # Machine-readable help for AI agents
+```
+
+**Formats**: `table` (default), `json`, `yaml`
+**Environment**: `MCPPROXY_OUTPUT=json` sets default format
+
+See [docs/cli-output-formatting.md](docs/cli-output-formatting.md) for complete reference.
+
 ## Architecture Overview
 
 ### Core Components
@@ -69,6 +82,7 @@ See [docs/cli-management-commands.md](docs/cli-management-commands.md) for compl
 |-----------|---------|
 | `cmd/mcpproxy/` | CLI entry point, Cobra commands |
 | `cmd/mcpproxy-tray/` | System tray application with state machine |
+| `internal/cli/output/` | CLI output formatters (table, JSON, YAML) |
 | `internal/runtime/` | Lifecycle, event bus, background services |
 | `internal/server/` | HTTP server, MCP proxy |
 | `internal/httpapi/` | REST API endpoints (`/api/v1`) |
@@ -333,6 +347,8 @@ See `docs/prerelease-builds.md` for download instructions.
 ## Active Technologies
 - Go 1.24 (toolchain go1.24.10) (001-update-version-display)
 - In-memory only for version cache (no persistence per clarification) (001-update-version-display)
+- Go 1.24 (toolchain go1.24.10) + Cobra CLI framework, encoding/json, gopkg.in/yaml.v3 (014-cli-output-formatting)
+- N/A (CLI output only) (014-cli-output-formatting)
 
 ## Recent Changes
 - 001-update-version-display: Added Go 1.24 (toolchain go1.24.10)

cmd/mcpproxy/call_cmd.go

@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"mcpproxy-go/internal/cache"
+	"mcpproxy-go/internal/cli/output"
 	"mcpproxy-go/internal/cliclient"
 	"mcpproxy-go/internal/config"
 	"mcpproxy-go/internal/index"
@@ -25,6 +26,8 @@ import (
 	"go.uber.org/zap"
 )
 
+// Call command output format constants (kept for backward compatibility)
+// Note: "pretty" is the default for call command (different from global "table" default)
 const (
 	outputFormatJSON   = "json"
 	outputFormatPretty = "pretty"
@@ -208,13 +211,14 @@ func loadCallConfig() (*config.Config, error) {
 	return globalConfig, nil
 }
 
-// outputCallResultAsJSON outputs the result in JSON format
+// outputCallResultAsJSON outputs the result in JSON format using unified formatter
 func outputCallResultAsJSON(result interface{}) error {
-	output, err := json.MarshalIndent(result, "", "  ")
+	formatter := &output.JSONFormatter{Indent: true}
+	formatted, err := formatter.Format(result)
 	if err != nil {
 		return fmt.Errorf("failed to format result as JSON: %w", err)
 	}
-	fmt.Println(string(output))
+	fmt.Println(formatted)
 	return nil
 }
 

cmd/mcpproxy/main.go

@@ -38,6 +38,7 @@ import (
 	bbolterrors "go.etcd.io/bbolt/errors"
 	"go.uber.org/zap"
 
+	"mcpproxy-go/internal/cli/output"
 	"mcpproxy-go/internal/config"
 	"mcpproxy-go/internal/experiments"
 	"mcpproxy-go/internal/logs"
@@ -66,6 +67,10 @@ var (
 	allowServerRemove bool
 	enablePrompts     bool
 
+	// Output formatting flags (global)
+	globalOutputFormat string
+	globalJSONOutput   bool
+
 	version = "v0.1.0" // This will be injected by -ldflags during build
 )
 
@@ -98,6 +103,11 @@ func main() {
 	rootCmd.PersistentFlags().BoolVar(&logToFile, "log-to-file", false, "Enable logging to file in standard OS location (default: console only)")
 	rootCmd.PersistentFlags().StringVar(&logDir, "log-dir", "", "Custom log directory path (overrides standard OS location)")
 
+	// Output formatting flags (global)
+	rootCmd.PersistentFlags().StringVarP(&globalOutputFormat, "output", "o", "", "Output format: table, json, yaml")
+	rootCmd.PersistentFlags().BoolVar(&globalJSONOutput, "json", false, "Shorthand for -o json")
+	rootCmd.MarkFlagsMutuallyExclusive("output", "json")
+
 	// Add server command
 	serverCmd := &cobra.Command{
 		Use:   "serve",
@@ -157,6 +167,10 @@ func main() {
 	rootCmd.AddCommand(upstreamCmd)
 	rootCmd.AddCommand(doctorCmd)
 
+	// Setup --help-json for machine-readable help discovery
+	// This must be called AFTER all commands are added
+	output.SetupHelpJSON(rootCmd)
+
 	// Default to server command for backward compatibility
 	rootCmd.RunE = runServer
 
@@ -633,3 +647,14 @@ func classifyError(err error) int {
 	// Default to general error
 	return ExitCodeGeneralError
 }
+
+// ResolveOutputFormat determines the output format from global flags and environment.
+// Priority: --json alias > -o flag > MCPPROXY_OUTPUT env var > default (table)
+func ResolveOutputFormat() string {
+	return output.ResolveFormat(globalOutputFormat, globalJSONOutput)
+}
+
+// GetOutputFormatter creates a formatter for the resolved output format.
+func GetOutputFormatter() (output.OutputFormatter, error) {
+	return output.NewFormatter(ResolveOutputFormat())
+}

cmd/mcpproxy/secrets_cmd.go

@@ -2,14 +2,14 @@ package main
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"os"
 	"strings"
 	"time"
 
 	"github.com/spf13/cobra"
 
+	"mcpproxy-go/internal/cli/output"
 	"mcpproxy-go/internal/config"
 	"mcpproxy-go/internal/logs"
 	"mcpproxy-go/internal/secret"
@@ -185,10 +185,7 @@ func getSecretsDeleteCommand() *cobra.Command {
 
 // getSecretsListCommand returns the secrets list command
 func getSecretsListCommand() *cobra.Command {
-	var (
-		jsonOutput bool
-		allTypes   bool
-	)
+	var allTypes bool
 
 	cmd := &cobra.Command{
 		Use:   "list",
@@ -199,58 +196,70 @@ func getSecretsListCommand() *cobra.Command {
 			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 			defer cancel()
 
+			// Get output format from global flags
+			outputFormat := ResolveOutputFormat()
+			formatter, err := GetOutputFormatter()
+			if err != nil {
+				return output.NewStructuredError(output.ErrCodeInvalidOutputFormat, err.Error()).
+					WithGuidance("Use -o table, -o json, or -o yaml")
+			}
+
+			var refs []secret.Ref
+			var providerName string
+
 			if allTypes {
 				// List from all available providers
-				refs, err := resolver.ListAll(ctx)
+				refs, err = resolver.ListAll(ctx)
 				if err != nil {
 					return fmt.Errorf("failed to list secrets: %w", err)
 				}
-
-				if jsonOutput {
-					return json.NewEncoder(os.Stdout).Encode(refs)
-				}
-
-				if len(refs) == 0 {
-					fmt.Println("No secrets found")
-					return nil
-				}
-
-				fmt.Printf("Found %d secrets:\n", len(refs))
-				for _, ref := range refs {
-					fmt.Printf("  %s (%s)\n", ref.Name, ref.Type)
-				}
+				providerName = "all providers"
 			} else {
 				// List from keyring only
 				keyringProvider := secret.NewKeyringProvider()
 				if !keyringProvider.IsAvailable() {
 					return fmt.Errorf("keyring is not available on this system")
 				}
 
-				refs, err := keyringProvider.List(ctx)
+				refs, err = keyringProvider.List(ctx)
 				if err != nil {
 					return fmt.Errorf("failed to list keyring secrets: %w", err)
 				}
+				providerName = "keyring"
+			}
 
-				if jsonOutput {
-					return json.NewEncoder(os.Stdout).Encode(refs)
+			// Handle JSON/YAML output
+			if outputFormat == "json" || outputFormat == "yaml" {
+				result, fmtErr := formatter.Format(refs)
+				if fmtErr != nil {
+					return fmt.Errorf("failed to format output: %w", fmtErr)
 				}
+				fmt.Println(result)
+				return nil
+			}
 
-				if len(refs) == 0 {
-					fmt.Println("No secrets found in keyring")
-					return nil
-				}
+			// Table output
+			if len(refs) == 0 {
+				fmt.Printf("No secrets found in %s\n", providerName)
+				return nil
+			}
 
-				fmt.Printf("Found %d secrets in keyring:\n", len(refs))
-				for _, ref := range refs {
-					fmt.Printf("  %s\n", ref.Name)
-				}
+			headers := []string{"NAME", "TYPE"}
+			var rows [][]string
+			for _, ref := range refs {
+				rows = append(rows, []string{ref.Name, ref.Type})
 			}
 
+			result, fmtErr := formatter.FormatTable(headers, rows)
+			if fmtErr != nil {
+				return fmt.Errorf("failed to format table: %w", fmtErr)
+			}
+			fmt.Print(result)
 			return nil
 		},
 	}
 
-	cmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
+	// Note: --json flag removed, use global -o json instead
 	cmd.Flags().BoolVar(&allTypes, "all", false, "List secrets from all available providers")
 
 	return cmd