k8s-gpu-mcp-server: Instructions file for GitHub Copilot

GitHub Copilot Instructions for k8s-gpu-mcp-server

This file provides context and guidelines for GitHub Copilot when generating code, reviews, and suggestions for the k8s-gpu-mcp-server project.

Project Context

k8s-gpu-mcp-server is an ephemeral diagnostic agent that provides surgical, real-time NVIDIA GPU hardware introspection for Kubernetes clusters via the Model Context Protocol (MCP). It is designed for AI-assisted troubleshooting by SREs debugging complex hardware failures.

Key Architectural Principles

1. Ephemeral Injection Pattern: No DaemonSets, no standing infrastructure
2. Stdio Transport Only: JSON-RPC 2.0 over kubectl debug SPDY tunneling
3. Read-Only Default: Safe operations with explicit operator mode for destructive actions
4. Minimal Dependencies: Prefer standard library over third-party packages
5. Hardware Safety: Isolate CGO/NVML calls, never panic on missing hardware

Code Generation Guidelines

Go Style and Conventions

• Follow Effective Go principles strictly
• Use gofmt -s (simplify) formatting
• Documentation comments limited to 80 characters; wrap to multiple lines if needed
• Always use context.Context as first parameter for I/O operations
• Error wrapping with fmt.Errorf("context: %w", err) - preserve error chains
• NO PANIC in production code (except main() initialization failures)

Error Handling Pattern

// Good: Contextual error with wrapping
if err := nvml.Init(); err != nil {
    return fmt.Errorf("failed to initialize NVML: %w", err)
}

// Bad: Silent failure or generic error
if err := nvml.Init(); err != nil {
    return err
}

Concurrency and Context

// Always pass context as first parameter
func GetGPUHealth(ctx context.Context, deviceIndex int) (*Health, error) {
    // Respect context cancellation
    select {
    case <-ctx.Done():
        return nil, ctx.Err()
    default:
    }
    
    // Use timeouts for hardware calls
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    
    // ... implementation
}