Document MCP support in OpenCost

[peatey]

Summary

Adds a new get_cost_recommendations MCP tool that generates actionable cost optimization recommendations by analyzing Kubernetes resource allocation data. The tool identifies idle resources, oversized workloads, and rightsizing opportunities, returning prioritized recommendations sorted by potential savings.

Key features:

• Idle resource detection - Identifies resources with <5% CPU and memory utilization

• Oversized resource detection - Finds workloads with <30% efficiency (high priority if <10%)

• Rightsizing recommendations - Suggests optimal resource requests based on actual usage

• Compact mode - Reduces response size by ~40% for token-efficient AI agent interactions

Changes

New MCP Tool: get_cost_recommendations

| Parameter | Type | Description |

|-----------|------|-------------|

| window | string | Time window (e.g., "24h", "7d", "lastweek") |

| aggregate | string | Aggregation level: "pod", "namespace", "controller" |

| filter | string | Allocation filter expression |

| buffer_multiplier | float | Headroom multiplier for recommendations (default: 1.2) |

| min_savings | float | Minimum savings threshold (default: $0.01) |

| include_idle | bool | Include idle resource detection |

| include_oversized | bool | Include oversized resource detection |

| include_rightsize | bool | Include rightsizing recommendations |

| top_n | int | Limit to top N recommendations by savings |

| compact | bool | New: Reduce response size for token efficiency |

Compact Mode

When compact=true, responses are optimized for AI agent token consumption:

• Omits verbose fields: id, description, action, start, end

• Rounds floats to appropriate precision (CPU: 4dp, costs: 2dp, percentages: 1dp)

• Uses shorter JSON field names (e.g., cpuReq, ramEff, savings)

Security & Input Validation

• Buffer multiplier clamped to 1.0-10.0 range

• Minimum savings clamped to non-negative values

• TopN clamped to max 10,000 results

• Nil costModel check prevents panics

Example Response

{

  "recommendations": [

    {

      "type": "oversized",

      "priority": "high",

      "resourceName": "api-server",

      "cpuReq": 4.0,

      "cpuUse": 0.8,

      "cpuEff": 0.2,

      "recCpuReq": 0.96,

      "savings": 45.50,

      "savingsPct": 75.0

    }

  ],

  "summary": {

    "totalRecommendations": 15,

    "totalPotentialSavings": 1250.00,

    "byType": {"idle": 2, "oversized": 8, "rightsize": 5},

    "byPriority": {"high": 5, "medium": 7, "low": 3}

  },

  "window": {"start": "...", "end": "..."}

}

Test plan

• [x] Unit tests for recommendation generation logic

• [x] Unit tests for idle/oversized/rightsize detection thresholds

• [x] Unit tests for input validation bounds

• [x] Unit tests for compact mode (field omission, float rounding)

• [x] Unit tests for roundFloat helper function

• [x] Syntax validation with gofmt