Enhance mcpproxy with tools command for debugging and server management

- Introduced `mcpproxy tools list` command to list tools from upstream servers with detailed logging options.
- Refactored client architecture into modular components: CLI Client, Managed Client, and Core Client for better separation of concerns.
- Updated documentation to include new CLI commands and examples for debugging server connections.
- Enhanced logging capabilities for tool discovery and connection issues.
- Updated dependencies in go.mod for improved functionality.

Author: Dumbris

DESIGN.md

@@ -193,6 +193,10 @@ mcpproxy implements comprehensive per-upstream-server logging to facilitate debu
 - Main application log: `main.log`
 - Per-server logs: `server-{name}.log`
 
+**Debug Commands:**
+- `mcpproxy tools list --server=NAME --log-level=trace`: Debug individual server connections
+- Enhanced trace logging shows all JSON-RPC frames and transport details
+
 **Log Rotation:**
 - Automatic rotation based on file size (10MB default)
 - Configurable retention (5 backup files, 30 days default)
@@ -212,6 +216,136 @@ mcpproxy implements comprehensive per-upstream-server logging to facilitate debu
 * Auto‑update channel.
 * GUI front‑end built with Wails.
 
+## 12  Client Architecture (Refactored)
+
+### 12.1 Modular Client Design
+
+The upstream client architecture has been refactored into three distinct layers for better separation of concerns, testability, and reusability:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   CLI Client    │    │ Managed Client  │    │   Core Client   │
+│                 │    │                 │    │                 │
+│ • CLI-specific  │ ──▶│ • State mgmt    │ ──▶│ • Basic MCP     │
+│ • Debug output  │    │ • Concurrency   │    │ • Connection    │
+│ • Tool display  │    │ • Background    │    │ • Auth fallback │
+│ • Stderr monitor│    │   recovery      │    │ • No state      │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+**Core Interfaces:**
+```go
+// MCPClient - Basic MCP operations
+type MCPClient interface {
+    Connect(ctx context.Context) error
+    Disconnect() error
+    IsConnected() bool
+    ListTools(ctx context.Context) ([]*config.ToolMetadata, error)
+    CallTool(ctx context.Context, toolName string, args map[string]interface{}) (*mcp.CallToolResult, error)
+    GetConnectionInfo() types.ConnectionInfo
+    GetServerInfo() *mcp.InitializeResult
+}
+
+// StatefulClient - Adds state management
+type StatefulClient interface {
+    MCPClient
+    GetState() types.ConnectionState
+    IsConnecting() bool
+    ShouldRetry() bool
+    SetStateChangeCallback(callback func(oldState, newState types.ConnectionState, info *types.ConnectionInfo))
+}
+```
+
+### 12.2 Core Client (`internal/upstream/core/`)
+
+**Purpose:** Minimal, stateless MCP client implementation
+- **Responsibility:** Direct MCP protocol communication
+- **Features:**
+  - Transport-agnostic (HTTP, SSE, stdio)
+  - Authentication fallback (headers → no-auth → OAuth)
+  - Environment variable filtering for stdio processes
+  - No background processes or state management
+
+**Key Components:**
+- `client.go`: Main client implementation
+- `auth.go`: Authentication strategies and fallback logic
+
+### 12.3 Managed Client (`internal/upstream/managed/`)
+
+**Purpose:** Stateful wrapper for daemon/long-running use
+- **Responsibility:** Production-ready client for `mcpproxy serve`
+- **Features:**
+  - Connection state machine with retry logic
+  - Background health monitoring and recovery
+  - Concurrency control for ListTools operations
+  - Exponential backoff for failed connections
+  - State change notifications
+
+**Key Features:**
+```go
+type ManagedClient struct {
+    coreClient   *core.CoreClient
+    StateManager *types.StateManager
+    // Concurrency control
+    listToolsMu sync.Mutex
+    // Background monitoring
+    stopMonitoring chan struct{}
+}
+```
+
+### 12.4 CLI Client (`internal/upstream/cli/`)
+
+**Purpose:** Specialized client for CLI debugging operations
+- **Responsibility:** Enhanced debugging for `mcpproxy tools list`
+- **Features:**
+  - Detailed output formatting with emojis
+  - JSON-RPC frame logging at trace level
+  - Stderr monitoring for stdio processes
+  - Single-shot operations (connect → list → disconnect)
+
+**Debug Output Features:**
+- **Transport Details:** All JSON-RPC request/response frames
+- **Stderr Capture:** Real-time stderr output from stdio processes
+- **Connection Events:** Detailed state transitions and timing
+- **Error Context:** Enhanced error messages with troubleshooting hints
+
+### 12.5 Shared Types (`internal/upstream/types/`)
+
+**Purpose:** Common data structures to break import cycles
+- **Connection States:** `Disconnected`, `Connecting`, `Authenticating`, `Discovering`, `Ready`, `Error`
+- **State Manager:** Handles state transitions, retry logic, and callbacks
+- **Connection Info:** Detailed connection metadata and error tracking
+
+**State Machine:**
+```
+Disconnected ──▶ Connecting ──▶ Authenticating ──▶ Discovering ──▶ Ready
+     ▲                │               │               │            │
+     └────────────────┴───────────────┴───────────────┴────────────┘
+                                   Error
+```
+
+### 12.6 Benefits of Refactored Architecture
+
+1. **Separation of Concerns:**
+   - Core: Pure MCP protocol implementation
+   - Managed: Production state management
+   - CLI: Debug-focused single operations
+
+2. **Reusability:**
+   - Core client shared between managed and CLI variants
+   - State management logic isolated and testable
+   - Transport logic decoupled from application logic
+
+3. **Testability:**
+   - Each layer can be unit tested independently
+   - Mock interfaces for integration testing
+   - Isolated state machine testing
+
+4. **Maintainability:**
+   - Clear responsibilities and boundaries
+   - Smaller, focused code files
+   - Type-safe interfaces between layers
+
 ## Upstream Server Management
 
 ### Dynamic Server Configuration

README.md

@@ -121,8 +121,15 @@ Edit `mcp_config.json` (see below). Or **ask LLM** to add servers (see [doc](htt
 | `tools_limit` | Max tools returned to client | `15` |
 | `tool_response_limit` | Auto-truncate responses above N chars (`0` disables) | `20000` |
 
-### CLI flags
+### CLI Commands
 
+**Main Commands:**
+```bash
+mcpproxy serve                      # Start proxy server with system tray
+mcpproxy tools list --server=NAME  # Debug tool discovery for specific server
+```
+
+**Serve Command Flags:**
 ```text
 mcpproxy serve --help
   -c, --config <file>          path to mcp_config.json
@@ -136,6 +143,28 @@ mcpproxy serve --help
       --allow-server-remove    allow removing servers (default true)
 ```
 
+**Tools Command Flags:**
+```text
+mcpproxy tools list --help
+  -s, --server <name>          upstream server name (required)
+  -l, --log-level <level>      trace|debug|info|warn|error (default: info)
+  -t, --timeout <duration>     connection timeout (default: 30s)
+  -o, --output <format>        output format: table|json|yaml (default: table)
+  -c, --config <file>          path to mcp_config.json
+```
+
+**Debug Examples:**
+```bash
+# List tools with trace logging to see all JSON-RPC frames
+mcpproxy tools list --server=github-server --log-level=trace
+
+# List tools with custom timeout for slow servers
+mcpproxy tools list --server=slow-server --timeout=60s
+
+# Output tools in JSON format for scripting
+mcpproxy tools list --server=weather-api --output=json
+```
+
 ---
 
 ## OAuth Authentication Support

cmd/mcpproxy/main.go

@@ -90,9 +90,13 @@ func main() {
 	// Add search-servers command
 	searchCmd := createSearchServersCommand()
 
+	// Add tools command
+	toolsCmd := GetToolsCommand()
+
 	// Add commands to root
 	rootCmd.AddCommand(serverCmd)
 	rootCmd.AddCommand(searchCmd)
+	rootCmd.AddCommand(toolsCmd)
 
 	// Default to server command for backward compatibility
 	rootCmd.RunE = runServer