Enhance logging system and add tail_log operation

- Updated logging configuration to support custom log directories and filenames.
- Introduced `tail_log` operation for reading recent log entries from upstream servers, aiding in debugging.
- Improved log structure and content for better traceability of MCP server interactions.
- Adjusted CLI commands and documentation to reflect new logging features and configurations.

Author: Dumbris

DESIGN.md

@@ -24,12 +24,12 @@ Re‑implement the existing Python MCP proxy in Go, delivering a single‑binary
 
 * WebSocket/stdin transports, distributed indexing, vector search.
 
-## 3  Tech Stack
+## 3  Tech Stack
 
 | Concern           | Library                           | Reason                             |
 | ----------------- | --------------------------------- | ---------------------------------- |
 | MCP server/client | **`mark3labs/mcp-go`**            | Native Go, Streamable‑HTTP support |
-| Full‑text search  | **Bleve v2**                      | Embeddable BM25                    |
+| Full‑text search  | **Bleve v2**                      | Embeddable BM25                    |
 | CLI & config      | **`spf13/cobra` + `spf13/viper`** | Flags → env → file binding         |
 | Persistence       | **bbolt**                         | Single‑file ACID                   |
 | Sys‑tray          | **`fyne.io/systray`**             | Tiny cross‑platform tray           |
@@ -66,7 +66,7 @@ Re‑implement the existing Python MCP proxy in Go, delivering a single‑binary
   * Stored alongside tool metadata in both Bleve doc and Bolt `toolhash` bucket.
   * During re‑sync `ListTools` results are hashed; unchanged hashes skip re‑indexing.
 
-## 6  Data Model (bbolt)
+## 6  Data Model (bbolt)
 
 | Bucket      | Key           | Value                        |
 | ----------- | ------------- | ---------------------------- |
@@ -119,7 +119,22 @@ Input:  {"operation":"add","url":"https://api.mcp.dev","name":"dev"}
 Output: {"id":"uuid","enabled":true}
 ```
 
-Operations: `list` / `add` / `remove` / `update`.
+Operations: `list` / `add` / `remove` / `update` / `tail_log`.
+
+#### 8.3.1 `tail_log` Operation
+
+The `tail_log` operation allows LLMs to read recent log entries from a specific upstream server for debugging purposes:
+
+```jsonc
+Input:  {"operation":"tail_log","name":"dev","lines":50}
+Output: {"server":"dev","lines":50,"log_entries":[...]}
+```
+
+**Parameters:**
+- `name` (required): Server name to read logs from
+- `lines` (optional): Number of recent lines to return (default: 50, max: 500)
+
+**Use Case:** Enables AI agents to autonomously diagnose connection issues, authentication failures, and other upstream server problems by reading recent log entries.
 
 ### 8.4  `tools_stat`
 
@@ -134,10 +149,55 @@ Returns `{total_tools, top:[{tool_name,count}]}`.
 
 ## 10  CLI, Config & Tray
 
-* `mcpproxy [--listen :8080] [--data-dir ~/.mcpproxy] [--upstream "prod=https://api"]`
+* `mcpproxy [--listen :8080] [--log-dir ~/.mcpproxy/logs] [--upstream "prod=https://api"]`
 * Viper reads `$MCPP_` envs and `config.toml`.
 * Tray (systray): icon + menu items (Enable, Disable, Add…, Reindex, Quit).
 
+### 10.1 Logging System
+
+#### Per-Upstream Server Logging
+
+mcpproxy implements comprehensive per-upstream-server logging to facilitate debugging of connection issues and MCP communication problems.
+
+**Log File Structure:**
+```
+~/.mcpproxy/logs/
+├── main.log                    # Main application log
+├── server-github.log           # GitHub MCP server interactions
+├── server-filesystem.log       # Filesystem MCP server interactions
+└── server-database.log         # Database MCP server interactions
+```
+
+**Log Content:**
+- **MCP Protocol Messages**: All JSON-RPC messages between mcpproxy and upstream servers
+- **Connection Events**: Connect, disconnect, retry attempts, and failures
+- **Authentication**: OAuth flows, token refreshes, and auth errors
+- **Process Output**: STDERR from stdio-based MCP servers
+- **Timing Information**: Request/response latencies and timeout events
+
+**Example Log Format:**
+```
+2025-06-04T03:42:38.375Z [github] [info] Connecting to upstream server
+2025-06-04T03:42:38.630Z [github] [info] Connected successfully
+2025-06-04T03:42:38.663Z [github] [debug] [Client→Server] initialize
+2025-06-04T03:42:38.663Z [github] [debug] {"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"mcpproxy-go","version":"1.0.0"}},"jsonrpc":"2.0","id":0}
+2025-06-04T03:42:38.700Z [github] [debug] [Server→Client] 0
+2025-06-04T03:42:38.700Z [github] [debug] {"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"GitHub MCP Server","version":"1.0.0"}}}
+2025-06-04T03:42:41.670Z [github] [error] Connection error: HTTP 500 - Internal Server Error
+2025-06-04T03:42:41.671Z [github] [info] Attempting reconnection in 5 seconds...
+```
+
+**CLI Configuration:**
+- `--log-dir`: Specify custom log directory (default: OS-specific standard location)
+- `--log-level`: Set log level for all loggers (debug, info, warn, error)
+- Main application log: `main.log`
+- Per-server logs: `server-{name}.log`
+
+**Log Rotation:**
+- Automatic rotation based on file size (10MB default)
+- Configurable retention (5 backup files, 30 days default)
+- Optional compression for rotated files
+
 ## 11  Build & Packaging
 
 * Cross‑compile via `GOOS=darwin/windows/linux`.
@@ -171,7 +231,10 @@ The proxy supports dynamic management of upstream MCP servers through the `upstr
 ~/.mcpproxy/
 ├── mcp_config.json          # Main configuration file
 ├── data.bolt                # BoltDB storage (tool stats, metadata)
-└── index.bleve/             # Search index directory
+├── index.bleve/             # Search index directory
+└── logs/                    # Log files directory
+    ├── main.log             # Main application log
+    └── server-*.log         # Per-upstream server logs
 ```
 
 #### Configuration Flow

cmd/mcpproxy/main.go

@@ -25,7 +25,7 @@ var (
 	debugSearch       bool
 	toolResponseLimit int
 	logToFile         bool
-	logFile           string
+	logDir            string
 
 	// Security flags
 	readOnlyMode      bool
@@ -61,7 +61,7 @@ func main() {
 	rootCmd.PersistentFlags().BoolVar(&debugSearch, "debug-search", false, "Enable debug search tool for search relevancy debugging")
 	rootCmd.PersistentFlags().IntVar(&toolResponseLimit, "tool-response-limit", 0, "Tool response limit in characters (0 = disabled, default: 20000 from config)")
 	rootCmd.PersistentFlags().BoolVar(&logToFile, "log-to-file", true, "Enable logging to file in standard OS location")
-	rootCmd.PersistentFlags().StringVar(&logFile, "log-file", "", "Custom log file path (overrides standard OS location)")
+	rootCmd.PersistentFlags().StringVar(&logDir, "log-dir", "", "Custom log directory path (overrides standard OS location)")
 	rootCmd.PersistentFlags().BoolVar(&readOnlyMode, "read-only", false, "Enable read-only mode")
 	rootCmd.PersistentFlags().BoolVar(&disableManagement, "disable-management", false, "Disable management features")
 	rootCmd.PersistentFlags().BoolVar(&allowServerAdd, "allow-server-add", true, "Allow adding new servers")
@@ -87,7 +87,7 @@ func runServer(_ *cobra.Command, _ []string) error {
 			Level:         logLevel,
 			EnableFile:    logToFile,
 			EnableConsole: true,
-			Filename:      "mcpproxy.log",
+			Filename:      "main.log",
 			MaxSize:       10,
 			MaxBackups:    5,
 			MaxAge:        30,
@@ -98,11 +98,16 @@ func runServer(_ *cobra.Command, _ []string) error {
 		// Override specific fields from command line
 		cfg.Logging.Level = logLevel
 		cfg.Logging.EnableFile = logToFile
-		if logFile != "" {
-			cfg.Logging.Filename = logFile
+		if cfg.Logging.Filename == "" || cfg.Logging.Filename == "mcpproxy.log" {
+			cfg.Logging.Filename = "main.log"
 		}
 	}
 
+	// Override log directory if specified
+	if logDir != "" {
+		cfg.Logging.LogDir = logDir
+	}
+
 	// Setup logger with new logging system
 	logger, err := logs.SetupLogger(cfg.Logging)
 	if err != nil {

internal/config/config.go

@@ -39,9 +39,10 @@ type LogConfig struct {
 	EnableFile    bool   `json:"enable_file" mapstructure:"enable-file"`
 	EnableConsole bool   `json:"enable_console" mapstructure:"enable-console"`
 	Filename      string `json:"filename" mapstructure:"filename"`
-	MaxSize       int    `json:"max_size" mapstructure:"max-size"`       // MB
-	MaxBackups    int    `json:"max_backups" mapstructure:"max-backups"` // number of backup files
-	MaxAge        int    `json:"max_age" mapstructure:"max-age"`         // days
+	LogDir        string `json:"log_dir,omitempty" mapstructure:"log-dir"` // Custom log directory
+	MaxSize       int    `json:"max_size" mapstructure:"max-size"`         // MB
+	MaxBackups    int    `json:"max_backups" mapstructure:"max-backups"`   // number of backup files
+	MaxAge        int    `json:"max_age" mapstructure:"max-age"`           // days
 	Compress      bool   `json:"compress" mapstructure:"compress"`
 	JSONFormat    bool   `json:"json_format" mapstructure:"json-format"`
 }
@@ -158,7 +159,7 @@ func DefaultConfig() *Config {
 			Level:         "info",
 			EnableFile:    true,
 			EnableConsole: true,
-			Filename:      "mcpproxy.log",
+			Filename:      "main.log",
 			MaxSize:       10, // 10MB
 			MaxBackups:    5,  // 5 backup files
 			MaxAge:        30, // 30 days

internal/logs/logger.go

@@ -1,6 +1,7 @@
 package logs
 
 import (
+	"bufio"
 	"fmt"
 	"io"
 	"mcpproxy-go/internal/config"
@@ -85,8 +86,8 @@ func SetupLogger(config *config.LogConfig) (*zap.Logger, error) {
 
 // createFileCore creates a file-based logging core
 func createFileCore(config *config.LogConfig, level zapcore.Level) (zapcore.Core, error) {
-	// Get log file path
-	logFilePath, err := GetLogFilePath(config.Filename)
+	// Get log file path with custom directory support
+	logFilePath, err := GetLogFilePathWithDir(config.LogDir, config.Filename)
 	if err != nil {
 		return nil, fmt.Errorf("failed to get log file path: %w", err)
 	}
@@ -210,3 +211,89 @@ func CleanupTestWriter(file *os.File) error {
 	}
 	return nil
 }
+
+// CreateUpstreamServerLogger creates a logger for a specific upstream server
+func CreateUpstreamServerLogger(config *config.LogConfig, serverName string) (*zap.Logger, error) {
+	if config == nil {
+		config = DefaultLogConfig()
+	}
+
+	// Create a copy of the config for the upstream server
+	serverConfig := *config
+	serverConfig.Filename = fmt.Sprintf("server-%s.log", serverName)
+	serverConfig.EnableConsole = false // Upstream servers only log to file
+
+	// Parse log level
+	var level zapcore.Level
+	switch serverConfig.Level {
+	case "debug":
+		level = zap.DebugLevel
+	case "info":
+		level = zap.InfoLevel
+	case "warn":
+		level = zap.WarnLevel
+	case "error":
+		level = zap.ErrorLevel
+	default:
+		level = zap.InfoLevel
+	}
+
+	// Create file core for upstream server
+	fileCore, err := createFileCore(&serverConfig, level)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create file core for upstream server %s: %w", serverName, err)
+	}
+
+	// Create logger with server name prefix
+	logger := zap.New(fileCore, zap.AddCaller(), zap.AddCallerSkip(1))
+	logger = logger.With(zap.String("server", serverName))
+
+	return logger, nil
+}
+
+// ReadUpstreamServerLogTail reads the last N lines from an upstream server log file
+func ReadUpstreamServerLogTail(config *config.LogConfig, serverName string, lines int) ([]string, error) {
+	if lines <= 0 {
+		lines = 50
+	}
+	if lines > 500 {
+		lines = 500
+	}
+
+	// Get log file path
+	filename := fmt.Sprintf("server-%s.log", serverName)
+	logFilePath, err := GetLogFilePathWithDir(config.LogDir, filename)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get log file path for server %s: %w", serverName, err)
+	}
+
+	// Check if file exists
+	if _, err := os.Stat(logFilePath); os.IsNotExist(err) {
+		return []string{}, nil // Return empty slice if file doesn't exist
+	}
+
+	// Read file
+	file, err := os.Open(logFilePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open log file for server %s: %w", serverName, err)
+	}
+	defer file.Close()
+
+	// Read all lines
+	var allLines []string
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		allLines = append(allLines, scanner.Text())
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("failed to read log file for server %s: %w", serverName, err)
+	}
+
+	// Return last N lines
+	if len(allLines) <= lines {
+		return allLines, nil
+	}
+
+	return allLines[len(allLines)-lines:], nil
+}

internal/logs/paths.go

@@ -4,6 +4,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"strings"
 )
 
 const (
@@ -104,6 +105,28 @@ func GetLogFilePath(filename string) (string, error) {
 	return filepath.Join(logDir, filename), nil
 }
 
+// GetLogFilePathWithDir returns the full path for a log file in a custom log directory
+func GetLogFilePathWithDir(logDir, filename string) (string, error) {
+	if logDir == "" {
+		return GetLogFilePath(filename)
+	}
+
+	// Expand user home directory if needed
+	if strings.HasPrefix(logDir, "~/") {
+		homeDir, err := os.UserHomeDir()
+		if err != nil {
+			return "", err
+		}
+		logDir = filepath.Join(homeDir, logDir[2:])
+	}
+
+	if err := EnsureLogDir(logDir); err != nil {
+		return "", err
+	}
+
+	return filepath.Join(logDir, filename), nil
+}
+
 // LogDirInfo returns information about the log directory for different OS
 type LogDirInfo struct {
 	Path        string `json:"path"`