Merge origin/main into 013-structured-server-state

Author: Dumbris

CLAUDE.md

@@ -65,6 +65,7 @@ See [docs/cli-management-commands.md](docs/cli-management-commands.md) for compl
 ```bash
 mcpproxy activity list              # List recent activity
 mcpproxy activity list --type tool_call --status error  # Filter by type/status
+mcpproxy activity list --request-id <id>  # Filter by HTTP request ID (for error correlation)
 mcpproxy activity watch             # Real-time activity stream
 mcpproxy activity show <id>         # View activity details
 mcpproxy activity summary           # Show 24h statistics
@@ -201,6 +202,8 @@ See [docs/configuration.md](docs/configuration.md) for complete reference.
 
 **Authentication**: Use `X-API-Key` header or `?apikey=` query parameter.
 
+**Request ID Tracking**: All responses include `X-Request-Id` header. Error responses include `request_id` in JSON body. Use for log correlation: `mcpproxy activity list --request-id <id>`.
+
 **Real-time Updates**:
 - `GET /events` - Server-Sent Events (SSE) stream for live updates
 - Streams both status changes and runtime events (`servers.changed`, `config.reloaded`)
@@ -385,6 +388,9 @@ See `docs/prerelease-builds.md` for download instructions.
 - BBolt database (`~/.mcpproxy/config.db`) - ActivityRecord extended with intent metadata (018-intent-declaration)
 - TypeScript 5.9, Vue 3.5, Go 1.24 (backend already exists) + Vue 3, Vue Router 4, Pinia 2, Tailwind CSS 3, DaisyUI 4, Vite 5 (019-activity-webui)
 - N/A (frontend consumes REST API from backend) (019-activity-webui)
+- Go 1.24 (toolchain go1.24.10) + Cobra (CLI), Chi router (HTTP), Zap (logging), mark3labs/mcp-go (MCP protocol) (020-oauth-login-feedback)
+- Go 1.24 (toolchain go1.24.10) + Cobra (CLI), Chi router (HTTP), Zap (logging), google/uuid (ID generation) (021-request-id-logging)
+- BBolt database (`~/.mcpproxy/config.db`) - activity log extended with request_id field (021-request-id-logging)
 
 ## Recent Changes
 - 001-update-version-display: Added Go 1.24 (toolchain go1.24.10)

cmd/mcpproxy/activity_cmd.go

@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -37,6 +38,7 @@ var (
 	activityLimit      int
 	activityOffset     int
 	activityIntentType string // Spec 018: Filter by operation type (read, write, destructive)
+	activityRequestID  string // Spec 021: Filter by HTTP request ID for correlation
 	activityNoIcons    bool   // Disable emoji icons in output
 
 	// Show command flags
@@ -64,6 +66,7 @@ type ActivityFilter struct {
 	Limit      int
 	Offset     int
 	IntentType string // Spec 018: Filter by operation type (read, write, destructive)
+	RequestID  string // Spec 021: Filter by HTTP request ID for correlation
 }
 
 // Validate validates the filter options
@@ -168,6 +171,10 @@ func (f *ActivityFilter) ToQueryParams() url.Values {
 	if f.IntentType != "" {
 		q.Set("intent_type", f.IntentType)
 	}
+	// Spec 021: Add request_id filter for log correlation
+	if f.RequestID != "" {
+		q.Set("request_id", f.RequestID)
+	}
 	return q
 }
 
@@ -369,14 +376,30 @@ func outputActivityError(err error, code string) error {
 		return err
 	}
 
+	// T026: Extract request_id from APIError if available
+	var requestID string
+	var apiErr *cliclient.APIError
+	if errors.As(err, &apiErr) && apiErr.HasRequestID() {
+		requestID = apiErr.RequestID
+	}
+
 	if outputFormat == "json" || outputFormat == "yaml" {
 		structErr := output.NewStructuredError(code, err.Error()).
 			WithGuidance("Use 'mcpproxy activity list' to view recent activities").
 			WithRecoveryCommand("mcpproxy activity list --limit 10")
+		// T026: Add request_id to StructuredError if available
+		if requestID != "" {
+			structErr = structErr.WithRequestID(requestID)
+		}
 		result, _ := formatter.FormatError(structErr)
 		fmt.Println(result)
 	} else {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		// T026: Include request ID with log retrieval suggestion if available
+		if requestID != "" {
+			fmt.Fprintf(os.Stderr, "\nRequest ID: %s\n", requestID)
+			fmt.Fprintf(os.Stderr, "Use 'mcpproxy activity list --request-id %s' to find related logs.\n", requestID)
+		}
 		fmt.Fprintf(os.Stderr, "Hint: Use 'mcpproxy activity list' to view recent activities\n")
 	}
 	return err
@@ -405,6 +428,9 @@ Examples:
   # List errors from github server
   mcpproxy activity list --server github --status error
 
+  # List activity by request ID (for error correlation)
+  mcpproxy activity list --request-id abc123-def456
+
   # List activity as JSON
   mcpproxy activity list -o json`,
 		RunE: runActivityList,
@@ -501,6 +527,7 @@ func init() {
 	activityListCmd.Flags().IntVarP(&activityLimit, "limit", "n", 50, "Max records to return (1-100)")
 	activityListCmd.Flags().IntVar(&activityOffset, "offset", 0, "Pagination offset")
 	activityListCmd.Flags().StringVar(&activityIntentType, "intent-type", "", "Filter by intent operation type: read, write, destructive")
+	activityListCmd.Flags().StringVar(&activityRequestID, "request-id", "", "Filter by HTTP request ID for log correlation")
 	activityListCmd.Flags().BoolVar(&activityNoIcons, "no-icons", false, "Disable emoji icons in output (use text instead)")
 
 	// Watch command flags
@@ -585,6 +612,7 @@ func runActivityList(cmd *cobra.Command, _ []string) error {
 		Limit:      activityLimit,
 		Offset:     activityOffset,
 		IntentType: activityIntentType,
+		RequestID:  activityRequestID,
 	}
 
 	if err := filter.Validate(); err != nil {

cmd/mcpproxy/auth_cmd.go

@@ -486,7 +486,8 @@ func runAuthLoginClientMode(ctx context.Context, dataDir, serverName string) err
 
 	// Trigger OAuth via daemon
 	if err := client.TriggerOAuthLogin(ctx, serverName); err != nil {
-		return fmt.Errorf("failed to trigger OAuth login via daemon: %w", err)
+		// T025: Use cliError to include request_id in error output
+		return cliError("failed to trigger OAuth login via daemon", err)
 	}
 
 	fmt.Printf("✅ OAuth authentication flow initiated successfully for server: %s\n", serverName)
@@ -617,7 +618,8 @@ func runAuthLogoutClientMode(ctx context.Context, dataDir, serverName string) er
 
 	// Trigger OAuth logout via daemon
 	if err := client.TriggerOAuthLogout(ctx, serverName); err != nil {
-		return fmt.Errorf("failed to trigger OAuth logout via daemon: %w", err)
+		// T025: Use cliError to include request_id in error output
+		return cliError("failed to trigger OAuth logout via daemon", err)
 	}
 
 	fmt.Printf("✅ OAuth logout completed successfully for server: %s\n", serverName)

cmd/mcpproxy/call_cmd.go

@@ -435,7 +435,8 @@ func runCallToolVariantClientMode(dataDir, toolVariant string, args map[string]i
 	// For tool variants, we call the variant tool directly
 	result, err := client.CallTool(callCtx, toolVariant, args)
 	if err != nil {
-		return fmt.Errorf("failed to call tool via daemon: %w", err)
+		// T028: Use cliError to include request_id in error output
+		return cliError("failed to call tool via daemon", err)
 	}
 
 	// Output results based on format

cmd/mcpproxy/cmd_helpers.go

@@ -1,12 +1,44 @@
 package main
 
+import (
+	"errors"
+	"fmt"
+
+	"mcpproxy-go/internal/cliclient"
+)
+
 // cmd_helpers.go provides type-safe helper functions for extracting fields
 // from JSON-decoded map[string]interface{} responses from the MCPProxy API.
 //
 // These functions are used throughout the CLI commands to safely extract
 // typed values from API responses, handling missing keys and type mismatches
 // gracefully by returning zero values.
 
+// formatErrorWithRequestID formats an error for CLI output, including request_id if available.
+// T023: Helper for CLI error display with request ID suggestion.
+func formatErrorWithRequestID(err error) string {
+	if err == nil {
+		return ""
+	}
+
+	// Check if the error is an APIError with request_id
+	var apiErr *cliclient.APIError
+	if errors.As(err, &apiErr) && apiErr.HasRequestID() {
+		return apiErr.FormatWithRequestID()
+	}
+
+	// Fall back to standard error message
+	return err.Error()
+}
+
+// cliError returns a formatted error suitable for CLI output.
+// It includes request_id when available from API errors.
+// T023: Wrapper for CLI commands to display errors with request ID.
+func cliError(prefix string, err error) error {
+	formattedMsg := formatErrorWithRequestID(err)
+	return fmt.Errorf("%s: %s", prefix, formattedMsg)
+}
+
 func getStringField(m map[string]interface{}, key string) string {
 	if v, ok := m[key].(string); ok {
 		return v

cmd/mcpproxy/code_cmd.go

@@ -198,7 +198,8 @@ func runCodeExecClientMode(dataDir, code string, input map[string]interface{}, l
 		codeAllowedSrvs,
 	)
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error calling daemon: %v\n", err)
+		// T029: Use formatErrorWithRequestID to include request_id in error output
+		fmt.Fprintf(os.Stderr, "Error calling daemon: %s\n", formatErrorWithRequestID(err))
 		return exitError(1)
 	}
 

cmd/mcpproxy/tools_cmd.go

@@ -243,7 +243,8 @@ func runToolsListClientMode(ctx context.Context, dataDir, serverName string, log
 	// Fetch tools from daemon
 	tools, err := client.GetServerTools(ctx, serverName)
 	if err != nil {
-		return fmt.Errorf("failed to get server tools from daemon: %w", err)
+		// T027: Use cliError to include request_id in error output
+		return cliError("failed to get server tools from daemon", err)
 	}
 
 	// Output results

cmd/mcpproxy/upstream_cmd.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"os/exec"
@@ -399,9 +400,17 @@ func outputServers(servers []map[string]interface{}) error {
 // outputError formats and outputs an error based on the current output format.
 // For structured formats (json, yaml), it outputs a StructuredError.
 // For table format, it outputs a human-readable error message to stderr.
+// T023: Updated to extract request_id from APIError for log correlation
 func outputError(err error, code string) error {
 	outputFormat := ResolveOutputFormat()
 
+	// T023: Extract request_id from APIError if available
+	var requestID string
+	var apiErr *cliclient.APIError
+	if errors.As(err, &apiErr) && apiErr.HasRequestID() {
+		requestID = apiErr.RequestID
+	}
+
 	// Convert to StructuredError if not already
 	var structErr output.StructuredError
 	if se, ok := err.(output.StructuredError); ok {
@@ -410,6 +419,11 @@ func outputError(err error, code string) error {
 		structErr = output.NewStructuredError(code, err.Error())
 	}
 
+	// T023: Add request_id to StructuredError if available
+	if requestID != "" {
+		structErr = structErr.WithRequestID(requestID)
+	}
+
 	// For structured formats, output JSON/YAML error to stdout
 	if outputFormat == "json" || outputFormat == "yaml" {
 		formatter, fmtErr := GetOutputFormatter()
@@ -430,7 +444,14 @@ func outputError(err error, code string) error {
 	}
 
 	// For table format, output human-readable error to stderr
-	fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+	// T023: Include request ID with log retrieval suggestion if available
+	if requestID != "" {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		fmt.Fprintf(os.Stderr, "\nRequest ID: %s\n", requestID)
+		fmt.Fprintf(os.Stderr, "Use 'mcpproxy activity list --request-id %s' to find related logs.\n", requestID)
+	} else {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+	}
 	return err
 }