[plan] Add debug logging for MCP configuration flow

[github-actions]

Objective

Add strategic debug logging throughout MCP configuration and compilation to improve troubleshooting. Currently only 35 debug loggers exist across 10,979 LOC (0.3% coverage). Focus on key decision points: mode selection, toolset resolution, validation, and server startup.

Context

From the MCP Server Integration Quality analysis:

• Minimal debug logging makes MCP configuration issues difficult to diagnose
• No debug logging for critical paths: server startup, toolset resolution, mode selection, validation
• Need visibility into configuration decisions for troubleshooting

Approach

1. Create loggers following naming convention: pkg:filename
2. Add logging at key decision points throughout MCP flow
3. Use existing logger package infrastructure
4. Enable with DEBUG=workflow:mcp* gh aw compile

Files to Modify

• pkg/workflow/mcp_config_validation.go - Validation decisions
• pkg/workflow/mcp_github_config.go - Toolset expansion
• pkg/workflow/mcp_setup_generator.go - Setup generation
• pkg/workflow/mcp_gateway_config.go - Gateway configuration
• pkg/workflow/mcp_renderer.go - YAML rendering decisions

Logging Patterns

Create logger:

import "github.com/githubnext/gh-aw/pkg/logger"

var log = logger.New("workflow:mcp_config_validation")

Mode selection:

if mcpServer.Mode == "" {
    log.Printf("MCP server '%s' missing mode, defaulting to 'remote'", serverName)
    mcpServer.Mode = "remote"
} else {
    log.Printf("MCP server '%s' using explicit mode: %s", serverName, mcpServer.Mode)
}

Toolset resolution:

log.Printf("Resolving GitHub toolsets for server '%s': %v", serverName, toolsets)
if len(toolsets) == 0 {
    log.Printf("Empty toolsets, defaulting to [default]")
}
expandedTools := expandToolsets(toolsets)
log.Printf("Expanded to %d tools: %v", len(expandedTools), expandedTools)

Validation entry/exit:

log.Printf("Starting MCP configuration validation for %d servers", len(servers))
// ... validation logic ...
log.Printf("Validation complete: %d errors, %d warnings", len(errors), len(warnings))

Server setup:

log.Printf("Generating MCP setup for %d servers", len(config.Servers))
for name, server := range config.Servers {
    log.Printf("Configuring server '%s': mode=%s, type=%s", name, server.Mode, server.Type)
}

Testing

After implementation, test with:

DEBUG=workflow:mcp* ./gh-aw compile test-workflow.md

Acceptance Criteria

• Debug logging added for mode selection logic
• Toolset resolution decisions logged
• Validation entry/exit points logged
• Server configuration steps logged
• Follows logger naming convention (pkg:filename)
• Uses existing logger package infrastructure
• Debug logs can be enabled with DEBUG=workflow:mcp* gh aw compile
• make agent-finish passes without errors

Related

• Discussion: 🎯 Repository Quality: MCP Server Integration Quality #11508 (MCP Server Integration Quality)
• Priority: Medium
• Effort: Small

AI generated by Plan Command for discussion #11508