feat(cloudwatch-mcp-server): Add Anomaly Detection Alarm recommendation to AWS CloudWatch MCP server

[abarkley123]

feat(cloudwatch-mcp-server): Add Anomaly Detection Alarm recommendation to AWS CloudWatch MCP server

Summary

This PR enhances the CloudWatch MCP server with a new metric analysis tool, allowing customers to better understand their metrics. The existing alarm recommendation system leverages these new metric analysis capabilities, allowing the tool to provide CloudWatch Anomaly Detection Alarm recommendations. These Anomaly Detection alarm recommendations also come with CloudFormation templates to make customer's lives easier when onboarding.

Changes

This PR enhances the server with metric analysis tooling and enhanced alarm recommendation capabilities:

Architecture:

• New analyze_metric tool added that performs metric analysis. The results identify a metric's trend, seasonality, data quality, and statistical measures.
• Existing get_recommended_metric_alarms tool leverages analyze_metric tool to provide Anomaly Detection Alarm recommendations.

Anomaly Detection Alarm Recommendations:

• Automatically recommends CloudWatch Anomaly Detection Alarms for metrics with strong seasonality
• Generates CloudFormation templates for alarm deployment
• Maintains backward compatibility with existing pre-baked recommendations. Existing recommendations are not overridden

Metric Analyser:

• Built SeasonalDetector component using STL decomposition to detect multiple patterns (e.g. hourly, daily, weekly)
• Implemented trend detection using Ordinary Least Squares (OLS) regression with statistical significance
  testing
• Added data density analysis using metric period to assess metric publishing consistency and identify gaps
• Calculated statistical measures using standard Python libraries including min/max, median, standard deviation, and
  coefficient of variation

CloudFormation Template Generation:

• Generates valid CloudFormation YAML for Anomaly Detection Alarms based on the metric definition
• Limited to Anomaly Detection Alarms in this PR; future PRs can extend template generation to static alarms.

User experience

Before this change:

• Metric data could be retrieved via GetMetricData
• Static Alarm recommendations could be generated for specific set of AWS Vended metrics
  • No recommendations for custom metrics
  • No recommendations suggesting Anomaly Detection Alarms

After this change:

• Intelligent Metric Analysis: Users can analyze any CloudWatch metric to understand its behavior patterns, including:

  • Seasonality detection (identifies daily, weekly, or other periodic patterns)
  • Trend analysis (detects increasing, decreasing, or stable trends)
  • Data quality assessment (evaluates metric publishing consistency)
  • Statistical properties (min, max, median, standard deviation, coefficient of variation)

• Metric characteristic based Alarm Recommendations: The server automatically recommends:

  • Backwards compatible: Static threshold alarms for a set of non-seasonal AWS Vended metrics
  • Anomaly Detection alarms for metrics with strong seasonal patterns, including custom metric
  • Context-aware alarm descriptions explaining the detected patterns

• CloudFormation templates: Users receive:

  • Valid CloudFormation templates ready for deployment
  • Pre-configured anomaly detectors with optimised default settings
  • Alarms with appropriate evaluation periods and comparison operators

Example workflow (backwards compatible):

1. User requests analysis of an AWS vended metric: analyze_metric for AWS/DynamoDB/UserErrors
2. Server matches metric namespace and dimensions to existing recommendation
3. Server recommends static alarm, with threshold guidance:

• Set the threshold according to the expected write traffic for the DynamoDB table

Example workflow:

1. User requests analysis of a custom metric: analyze_metric for CustomNamespace/MCP/NewMetric
2. Server detects weekly seasonality pattern with high confidence, trend, statistical measures etc.
3. User requests alarm generation: get_recommended_metric_alarms for AWS/EC2/CPUUtilization
4. Server recommends CloudWatch Anomaly Detection alarm based on the weekly seasonality pattern
5. User receives CloudFormation template ready to deploy
6. Alarm automatically adapts to metric's seasonal behavior

Checklist

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested (277 tests passing, 115+ new tests added)
• Changes are documented

Is this a breaking change? N

The changes maintain backward compatibility. All existing CloudWatch MCP server functionality remains unchanged. New analysis and recommendation capabilities are additive enhancements.

RFC issue number: 1453

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[codecov]

Codecov Report

❌ Patch coverage is 99.18033% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.90%. Comparing base (35c21f3) to head (995b095).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...erver/cloudwatch_metrics/metric_data_decomposer.py	97.93%	1 Missing and 1 partial ⚠️
.../cloudwatch_mcp_server/cloudwatch_metrics/tools.py	98.70%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1454      +/-   ##
==========================================
+ Coverage   89.83%   89.90%   +0.06%     
==========================================
  Files         741      745       +4     
  Lines       52968    53322     +354     
  Branches     8512     8551      +39     
==========================================
+ Hits        47586    47938     +352     
- Misses       3447     3448       +1     
- Partials     1935     1936       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.