awslabs.cloudwatch-mcp-server 0.0.11__tar.gz → 0.0.14__tar.gz

{awslabs_cloudwatch_mcp_server-0.0.11 → awslabs_cloudwatch_mcp_server-0.0.14}/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+
+## [0.0.5] - 2025-10-06
+
+### Added
+
+- Added tool to analyze CloudWatch Metric data
+
+### Changed
+
+- Updated Alarm recommendation tool to support CloudWatch Anomaly Detection Alarms
+
 ## [0.0.4] - 2025-07-11
 
 ### Changed

{awslabs_cloudwatch_mcp_server-0.0.11 → awslabs_cloudwatch_mcp_server-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.cloudwatch-mcp-server
-Version: 0.0.11
+Version: 0.0.14
 Summary: An AWS Labs Model Context Protocol (MCP) server for cloudwatch
 Project-URL: homepage, https://awslabs.github.io/mcp/
 Project-URL: docs, https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/
@@ -23,8 +23,11 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: boto3>=1.38.22
 Requires-Dist: loguru>=0.7.0
-Requires-Dist: mcp[cli]>=1.11.0
+Requires-Dist: mcp[cli]>=1.23.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pandas>=2.2.3
 Requires-Dist: pydantic>=2.10.6
+Requires-Dist: statsmodels>=0.14.0
 Description-Content-Type: text/markdown
 
 # AWS Labs cloudwatch MCP Server
@@ -57,7 +60,8 @@ Alarm Recommendations - Suggests recommended alarm configurations for CloudWatch
 ### Tools for CloudWatch Metrics
 * `get_metric_data` - Retrieves detailed CloudWatch metric data for any CloudWatch metric. Use this for general CloudWatch metrics that aren't specific to Application Signals. Provides ability to query any metric namespace, dimension, and statistic
 * `get_metric_metadata` - Retrieves comprehensive metadata about a specific CloudWatch metric
-* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric
+* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric based on best practice, and trend, seasonality and statistical analysis.
+* `analyze_metric` - Analyzes CloudWatch metric data to determine trend, seasonality, and statistical properties
 
 ### Tools for CloudWatch Alarms
 * `get_active_alarms` - Identifies currently active CloudWatch alarms across the account

{awslabs_cloudwatch_mcp_server-0.0.11 → awslabs_cloudwatch_mcp_server-0.0.14}/README.md

@@ -28,7 +28,8 @@ Alarm Recommendations - Suggests recommended alarm configurations for CloudWatch
 ### Tools for CloudWatch Metrics
 * `get_metric_data` - Retrieves detailed CloudWatch metric data for any CloudWatch metric. Use this for general CloudWatch metrics that aren't specific to Application Signals. Provides ability to query any metric namespace, dimension, and statistic
 * `get_metric_metadata` - Retrieves comprehensive metadata about a specific CloudWatch metric
-* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric
+* `get_recommended_metric_alarms` - Gets recommended alarms for a CloudWatch metric based on best practice, and trend, seasonality and statistical analysis.
+* `analyze_metric` - Analyzes CloudWatch metric data to determine trend, seasonality, and statistical properties
 
 ### Tools for CloudWatch Alarms
 * `get_active_alarms` - Identifies currently active CloudWatch alarms across the account

{awslabs_cloudwatch_mcp_server-0.0.11 → awslabs_cloudwatch_mcp_server-0.0.14}/awslabs/cloudwatch_mcp_server/__init__.py

@@ -14,4 +14,5 @@
 
 """awslabs.cloudwatch-mcp-server"""
 
-MCP_SERVER_VERSION = '0.0.1'
+__version__ = '0.0.14'
+MCP_SERVER_VERSION = __version__

{awslabs_cloudwatch_mcp_server-0.0.11 → awslabs_cloudwatch_mcp_server-0.0.14}/awslabs/cloudwatch_mcp_server/cloudwatch_alarms/models.py

@@ -54,7 +54,7 @@ class CompositeAlarmSummary(BaseModel):
 
 
 class ActiveAlarmsResponse(BaseModel):
-    """Response containing active CloudWatch alarms."""
+    """Response containing active CloudWatch Alarms."""
 
     metric_alarms: List[MetricAlarmSummary] = Field(
         default_factory=list, description='List of active metric alarms'

{awslabs_cloudwatch_mcp_server-0.0.11 → awslabs_cloudwatch_mcp_server-0.0.14}/awslabs/cloudwatch_mcp_server/cloudwatch_alarms/tools.py

@@ -80,9 +80,9 @@ class CloudWatchAlarmsTools:
             Field(description='AWS region to query. Defaults to us-east-1.'),
         ] = 'us-east-1',
     ) -> ActiveAlarmsResponse:
-        """Gets all CloudWatch alarms currently in ALARM state.
+        """Gets all CloudWatch Alarms currently in ALARM state.
 
-        This tool retrieves all CloudWatch alarms that are currently in the ALARM state,
+        This tool retrieves all CloudWatch Alarms that are currently in the ALARM state,
         including both metric alarms and composite alarms. Results are optimized for
         LLM reasoning with summary-level information.
 

awslabs_cloudwatch_mcp_server-0.0.14/awslabs/cloudwatch_mcp_server/cloudwatch_metrics/cloudformation_template_generator.py

@@ -0,0 +1,162 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.constants import COMPARISON_OPERATOR_ANOMALY
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.models import AnomalyDetectionAlarmThreshold
+from typing import Any, Dict
+
+
+logger = logging.getLogger(__name__)
+
+
+class CloudFormationTemplateGenerator:
+    """Generate CloudFormation JSON for CloudWatch Anomaly Detection Alarms."""
+
+    def generate_metric_alarm_template(self, alarm_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Generate CFN template for a single CloudWatch Alarm."""
+        if not self._is_anomaly_detection_alarm(alarm_data):
+            return {}
+
+        # Validate required fields
+        if not alarm_data.get('metricName'):
+            raise ValueError(
+                'Metric Name is required to generate CloudFormation templates for Cloudwatch Alarms'
+            )
+        if not alarm_data.get('namespace'):
+            raise ValueError(
+                'Metric Namespace is required to generate CloudFormation templates for Cloudwatch Alarms'
+            )
+
+        # Process alarm data and add computed fields
+        formatted_data = self._format_anomaly_detection_alarm_data(alarm_data)
+
+        # Build resources dict
+        anomaly_detector_key = f'{formatted_data["resourceKey"]}AnomalyDetector'
+        alarm_key = f'{formatted_data["resourceKey"]}Alarm'
+
+        resources = {
+            anomaly_detector_key: {
+                'Type': 'AWS::CloudWatch::AnomalyDetector',
+                'Properties': {
+                    'MetricName': formatted_data['metricName'],
+                    'Namespace': formatted_data['namespace'],
+                    'Stat': formatted_data['statistic'],
+                    'Dimensions': formatted_data['dimensions'],
+                },
+            },
+            alarm_key: {
+                'Type': 'AWS::CloudWatch::Alarm',
+                'DependsOn': anomaly_detector_key,
+                'Properties': {
+                    'AlarmDescription': formatted_data['alarmDescription'],
+                    'Metrics': [
+                        {
+                            'Expression': f'ANOMALY_DETECTION_BAND(m1, {formatted_data["sensitivity"]})',
+                            'Id': 'ad1',
+                        },
+                        {
+                            'Id': 'm1',
+                            'MetricStat': {
+                                'Metric': {
+                                    'MetricName': formatted_data['metricName'],
+                                    'Namespace': formatted_data['namespace'],
+                                    'Dimensions': formatted_data['dimensions'],
+                                },
+                                'Stat': formatted_data['statistic'],
+                                'Period': formatted_data['period'],
+                            },
+                        },
+                    ],
+                    'EvaluationPeriods': formatted_data['evaluationPeriods'],
+                    'DatapointsToAlarm': formatted_data['datapointsToAlarm'],
+                    'ThresholdMetricId': 'ad1',
+                    'ComparisonOperator': formatted_data['comparisonOperator'],
+                    'TreatMissingData': formatted_data['treatMissingData'],
+                },
+            },
+        }
+
+        final_template = {
+            'AWSTemplateFormatVersion': '2010-09-09',
+            'Description': 'CloudWatch Alarms and Anomaly Detectors',
+            'Resources': resources,
+        }
+
+        return final_template
+
+    def _is_anomaly_detection_alarm(self, alarm_data: Dict[str, Any]) -> bool:
+        return alarm_data.get('comparisonOperator') == COMPARISON_OPERATOR_ANOMALY
+
+    def _format_anomaly_detection_alarm_data(self, alarm_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Sanitize alarm data and add computed fields."""
+        formatted_data = alarm_data.copy()
+
+        # Generate resource key from metric name and namespace
+        formatted_data['resourceKey'] = self._generate_resource_key(
+            metric_name=alarm_data.get('metricName', ''),
+            namespace=alarm_data.get('namespace', ''),
+            dimensions=alarm_data.get('dimensions', []),
+        )
+
+        # Process threshold value
+        threshold = alarm_data.get('threshold', {})
+        formatted_data['sensitivity'] = threshold.get(
+            'sensitivity', AnomalyDetectionAlarmThreshold.DEFAULT_SENSITIVITY
+        )
+
+        # Set defaults
+        formatted_data.setdefault(
+            'alarmDescription', 'CloudWatch Alarm generated by CloudWatch MCP server.'
+        )
+        formatted_data.setdefault('statistic', 'Average')
+        formatted_data.setdefault('period', 300)
+        formatted_data.setdefault('evaluationPeriods', 2)
+        formatted_data.setdefault('datapointsToAlarm', 2)
+        formatted_data.setdefault('comparisonOperator', COMPARISON_OPERATOR_ANOMALY)
+        formatted_data.setdefault('treatMissingData', 'missing')
+        formatted_data.setdefault('dimensions', [])
+
+        return formatted_data
+
+    def _generate_resource_key(self, metric_name: str, namespace: str, dimensions: list) -> str:
+        """Generate CloudFormation resource key from metric components to act as logical id."""
+        # Strip AWS/ prefix from namespace (AWS CDK style)
+        clean_namespace = namespace.replace('AWS/', '')
+
+        # Add first dimension key and value for uniqueness if present
+        dimension_suffix = ''
+        if dimensions:
+            first_dim = dimensions[0]
+            dim_name = first_dim.get('Name', '')
+            dim_value = first_dim.get('Value', '')
+            dimension_suffix = f'{dim_name}{dim_value}'
+
+        resource_base = f'{clean_namespace}{metric_name}{dimension_suffix}'
+        return self._sanitize_resource_name(resource_base)
+
+    def _sanitize_resource_name(self, name: str) -> str:
+        """Sanitize name for CloudFormation resource key."""
+        # Remove non-alphanumeric characters
+        sanitized = ''.join(c for c in name if c.isalnum())
+
+        # Ensure it starts with letter
+        if not sanitized or not sanitized[0].isalpha():
+            sanitized = 'Resource' + sanitized
+
+        # Truncate if too long
+        if len(sanitized) > 255:
+            sanitized = sanitized[:255]
+
+        return sanitized

awslabs_cloudwatch_mcp_server-0.0.14/awslabs/cloudwatch_mcp_server/cloudwatch_metrics/constants.py

@@ -0,0 +1,30 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# CloudWatch MCP Server Constants
+
+# Time constants
+SECONDS_PER_MINUTE = 60
+MINUTES_PER_HOUR = 60
+HOURS_PER_DAY = 24
+DAYS_PER_WEEK = 7
+
+# Analysis constants
+DEFAULT_ANALYSIS_PERIOD_MINUTES = 20160  # 2 weeks
+
+# Threshold constants
+COMPARISON_OPERATOR_ANOMALY = 'LessThanLowerOrGreaterThanUpperThreshold'
+
+# Numerical stability
+NUMERICAL_STABILITY_THRESHOLD = 1e-10

awslabs_cloudwatch_mcp_server-0.0.14/awslabs/cloudwatch_mcp_server/cloudwatch_metrics/metric_analyzer.py

@@ -0,0 +1,192 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.constants import (
+    NUMERICAL_STABILITY_THRESHOLD,
+)
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.metric_data_decomposer import (
+    MetricDataDecomposer,
+)
+from awslabs.cloudwatch_mcp_server.cloudwatch_metrics.models import (
+    DecompositionResult,
+    MetricData,
+    Seasonality,
+    Trend,
+)
+from collections import Counter
+from loguru import logger
+from typing import Any, Dict, Optional
+
+
+class MetricAnalyzer:
+    """Metric analysis including trend, density, seasonality, and statistical measures."""
+
+    def __init__(self):
+        """Initialize the metric analyzer."""
+        self.decomposer = MetricDataDecomposer()
+
+    def analyze_metric_data(self, metric_data: MetricData) -> Dict[str, Any]:
+        """Analyze metric data and return comprehensive analysis results.
+
+        Args:
+            metric_data: MetricData object containing timestamps and values
+
+        Returns:
+            Dict containing analysis results including seasonality, trend, statistics, and message
+        """
+        if not metric_data.timestamps or not metric_data.values:
+            return {'message': 'No metric data available for analysis'}
+
+        clean_data = [
+            (ts, val)
+            for ts, val in zip(metric_data.timestamps, metric_data.values)
+            if val is not None and not (np.isnan(val) or np.isinf(val))
+        ]
+
+        if len(clean_data) < 2:
+            return {'message': 'Insufficient valid data points for analysis'}
+
+        clean_timestamps, clean_values = zip(*clean_data)
+        clean_timestamps = list(clean_timestamps)
+        clean_values = list(clean_values)
+
+        try:
+            # Compute detailed analysis
+            publishing_period_seconds = self._compute_publishing_period(clean_timestamps)
+            density_ratio = self._compute_density_ratio(
+                clean_timestamps, publishing_period_seconds or 0.0
+            )
+            decomposition = self._compute_seasonality_and_trend(
+                clean_timestamps, clean_values, density_ratio, publishing_period_seconds
+            )
+            statistics = self._compute_statistics(clean_values)
+
+            return {
+                'data_points_found': len(metric_data.values),
+                'seasonality_seconds': decomposition.seasonality.value,
+                'trend': decomposition.trend,
+                'statistics': statistics,
+                'data_quality': {
+                    'total_points': len(metric_data.values),
+                    'density_ratio': density_ratio,
+                    'publishing_period_seconds': publishing_period_seconds,
+                },
+                'message': 'Metric analysis completed successfully',
+            }
+        except Exception as e:
+            logger.error(f'Error during metric analysis: {str(e)}')
+            return {'message': 'Unable to analyze metric data'}
+
+    def _compute_seasonality_and_trend(
+        self,
+        timestamps_ms: list[int],
+        values: list[float],
+        density_ratio: Optional[float],
+        publishing_period_seconds: Optional[float],
+    ):
+        """Compute seasonality and trend using decomposition.
+
+        Returns:
+            DecompositionResult with seasonality and trend
+        """
+        if density_ratio is None or publishing_period_seconds is None:
+            return DecompositionResult(seasonality=Seasonality.NONE, trend=Trend.NONE)
+
+        try:
+            return self.decomposer.detect_seasonality_and_trend(
+                timestamps_ms, values, density_ratio, int(publishing_period_seconds)
+            )
+        except Exception as e:
+            logger.error(f'Error computing seasonality and trend: {e}')
+            raise
+
+    def _compute_publishing_period(self, timestamps_ms: list[int]) -> Optional[float]:
+        """Compute the publishing period in seconds from timestamp gaps."""
+        try:
+            gaps = [timestamps_ms[i + 1] - timestamps_ms[i] for i in range(len(timestamps_ms) - 1)]
+            gap_counts = Counter(gaps)
+
+            if not gap_counts:
+                return None
+
+            most_common_gap_ms, _ = gap_counts.most_common(1)[0]
+            return self._get_closest_cloudwatch_period(most_common_gap_ms / 1000)
+        except Exception as e:
+            logger.warning(f'Error computing publishing period: {e}')
+            return None
+
+    def _get_closest_cloudwatch_period(self, period_seconds: float) -> float:
+        """Validate and normalize period to CloudWatch valid values."""
+        valid_periods = [1, 5, 10, 30] + [
+            i * 60 for i in range(1, 3601)
+        ]  # 1min to 1hour multiples
+
+        # Find closest valid period
+        closest_period = min(valid_periods, key=lambda x: abs(x - period_seconds))
+
+        # Only return if within 10% tolerance
+        if abs(closest_period - period_seconds) / closest_period <= 0.1:
+            return closest_period
+
+        return period_seconds  # Return original if no close match
+
+    def _compute_density_ratio(
+        self, timestamps_ms: list[int], publishing_period_seconds: float
+    ) -> Optional[float]:
+        """Calculate density ratio based on perfect timeline."""
+        if (
+            not publishing_period_seconds
+            or publishing_period_seconds <= 0
+            or len(timestamps_ms) < 2
+        ):
+            return None
+
+        try:
+            start_time = timestamps_ms[0]
+            publishing_period_ms = publishing_period_seconds * 1000
+            perfect_end_time = start_time + (publishing_period_ms * (len(timestamps_ms) - 1))
+            actual_points_in_range = sum(1 for ts in timestamps_ms if ts <= perfect_end_time)
+            return actual_points_in_range / len(timestamps_ms)
+        except Exception as e:
+            logger.error(f'Error calculating density ratio: {e}', exc_info=True)
+            raise
+
+    def _compute_statistics(self, values: list[float]) -> Dict[str, Any]:
+        """Compute essential statistical measures for LLM consumption."""
+        if not values:
+            return {
+                'min': None,
+                'max': None,
+                'std_deviation': None,
+                'coefficient_of_variation': None,
+                'median': None,
+            }
+
+        try:
+            values_array = np.array(values)
+            mean_val = np.mean(values_array)
+            std_dev = np.std(values_array, ddof=0)
+            cv = std_dev / abs(mean_val) if abs(mean_val) > NUMERICAL_STABILITY_THRESHOLD else None
+
+            return {
+                'min': float(np.min(values_array)),
+                'max': float(np.max(values_array)),
+                'std_deviation': float(std_dev),
+                'coefficient_of_variation': float(cv) if cv is not None else None,
+                'median': float(np.median(values_array)),
+            }
+        except Exception as e:
+            logger.warning(f'Error computing statistics: {e}')
+            raise