awslabs.cost-explorer-mcp-server 0.0.4__tar.gz → 0.0.5__tar.gz

awslabs_cost_explorer_mcp_server-0.0.5/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [0.5.0] - 2025-06-16
+
+### Added
+- Enhanced documentation for UsageQuantity metric with specific filtering requirements
+- Dynamic labeling for cost metrics based on grouping dimension (e.g., "Region Total" vs "Service Total")
+- Metadata support for usage metrics including grouped_by, metric type, and period information
+- Optimized JSON serialization that only runs stringify_keys when needed
+- Added Match_Option Validation
+
+### Changed
+- Usage metrics now return clean nested structure instead of complex pandas tuples
+  - Old: `{("2025-01-01", "Amount"): {"EC2": 100}, ("2025-01-01", "Unit"): {"EC2": "Hours"}}`
+  - New: `{"GroupedUsage": {"2025-01-01": {"EC2": {"amount": 100, "unit": "Hours"}}}}`
+- Improved UsageQuantity documentation to emphasize need for SERVICE + USAGE_TYPE filtering
+- Enhanced error handling for metric data processing
+
+## [0.1.0] - 2025-06-01
+
+### Added
+- Initial release of the Cost Explorer MCP Server

{awslabs_cost_explorer_mcp_server-0.0.4 → awslabs_cost_explorer_mcp_server-0.0.5}/Dockerfile

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-FROM public.ecr.aws/sam/build-python3.10@sha256:e78695db10ca8cb129e59e30f7dc9789b0dbd0181dba195d68419c72bac51ac1 AS uv
+FROM public.ecr.aws/sam/build-python3.10@sha256:d821662474d65f3cf2fc97dba2fa807a3adb580d02895fc4545527812550ea65 AS uv
 
 # Install the project into `/app`
 WORKDIR /app
@@ -46,7 +46,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 # Make the directory just in case it doesn't exist
 RUN mkdir -p /root/.local
 
-FROM public.ecr.aws/sam/build-python3.10@sha256:e78695db10ca8cb129e59e30f7dc9789b0dbd0181dba195d68419c72bac51ac1
+FROM public.ecr.aws/sam/build-python3.10@sha256:d821662474d65f3cf2fc97dba2fa807a3adb580d02895fc4545527812550ea65
 
 # Place executables in the environment at the front of the path and include other binaries
 ENV PATH="/app/.venv/bin:$PATH:/usr/sbin"

{awslabs_cost_explorer_mcp_server-0.0.4 → awslabs_cost_explorer_mcp_server-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.cost-explorer-mcp-server
-Version: 0.0.4
+Version: 0.0.5
 Summary: MCP server for analyzing AWS costs and usage data through the AWS Cost Explorer API
 Project-URL: Homepage, https://awslabs.github.io/mcp/
 Project-URL: Documentation, https://awslabs.github.io/mcp/servers/cost-explorer-mcp-server/
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: boto3>=1.36.20
+Requires-Dist: loguru>=0.7.0
 Requires-Dist: mcp[cli]>=1.6.0
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: pydantic>=2.10.6
@@ -63,6 +64,8 @@ MCP server for analyzing AWS costs and usage data through the AWS Cost Explorer
 
 ## Installation
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=awslabs.cost-explorer-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuY29zdC1leHBsb3Jlci1tY3Atc2VydmVyQGxhdGVzdCIsImVudiI6eyJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIiwiQVdTX1BST0ZJTEUiOiJ5b3VyLWF3cy1wcm9maWxlIn0sImRpc2FibGVkIjpmYWxzZSwiYXV0b0FwcHJvdmUiOltdfQ%3D%3D)
+
 Here are some ways you can work with MCP across AWS, and we'll be adding support to more products including Amazon Q Developer CLI soon: (e.g. for Amazon Q Developer CLI MCP, `~/.aws/amazonq/mcp.json`):
 
 ```json

{awslabs_cost_explorer_mcp_server-0.0.4 → awslabs_cost_explorer_mcp_server-0.0.5}/README.md

@@ -34,6 +34,8 @@ MCP server for analyzing AWS costs and usage data through the AWS Cost Explorer
 
 ## Installation
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=awslabs.cost-explorer-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuY29zdC1leHBsb3Jlci1tY3Atc2VydmVyQGxhdGVzdCIsImVudiI6eyJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIiwiQVdTX1BST0ZJTEUiOiJ5b3VyLWF3cy1wcm9maWxlIn0sImRpc2FibGVkIjpmYWxzZSwiYXV0b0FwcHJvdmUiOltdfQ%3D%3D)
+
 Here are some ways you can work with MCP across AWS, and we'll be adding support to more products including Amazon Q Developer CLI soon: (e.g. for Amazon Q Developer CLI MCP, `~/.aws/amazonq/mcp.json`):
 
 ```json

{awslabs_cost_explorer_mcp_server-0.0.4 → awslabs_cost_explorer_mcp_server-0.0.5}/awslabs/cost_explorer_mcp_server/helpers.py

@@ -15,17 +15,47 @@
 """Helper functions for the Cost Explorer MCP server."""
 
 import boto3
-import logging
+import os
 import re
+import sys
 from datetime import datetime
+from loguru import logger
 from typing import Any, Dict, Optional, Tuple
 
 
-# Set up logging
-logger = logging.getLogger(__name__)
+# Configure Loguru logging
+logger.remove()
+logger.add(sys.stderr, level=os.getenv('FASTMCP_LOG_LEVEL', 'WARNING'))
 
-# Initialize AWS Cost Explorer client
-ce = boto3.client('ce')
+# Global client cache
+_cost_explorer_client = None
+
+
+def get_cost_explorer_client():
+    """Get Cost Explorer client with proper session management and caching.
+
+    Returns:
+        boto3.client: Configured Cost Explorer client (cached after first call)
+    """
+    global _cost_explorer_client
+
+    if _cost_explorer_client is None:
+        try:
+            # Read environment variables dynamically
+            aws_region = os.environ.get('AWS_REGION', 'us-east-1')
+            aws_profile = os.environ.get('AWS_PROFILE')
+
+            if aws_profile:
+                _cost_explorer_client = boto3.Session(
+                    profile_name=aws_profile, region_name=aws_region
+                ).client('ce')
+            else:
+                _cost_explorer_client = boto3.Session(region_name=aws_region).client('ce')
+        except Exception as e:
+            logger.error(f'Error creating Cost Explorer client: {str(e)}')
+            raise
+
+    return _cost_explorer_client
 
 
 def validate_date_format(date_str: str) -> Tuple[bool, str]:
@@ -49,26 +79,79 @@ def validate_date_format(date_str: str) -> Tuple[bool, str]:
         return False, f"Invalid date '{date_str}': {str(e)}"
 
 
-def get_dimension_values(
-    key: str, billing_period_start: str, billing_period_end: str
-) -> Dict[str, Any]:
-    """Get available values for a specific dimension."""
-    # Validate date formats
-    is_valid_start, error_start = validate_date_format(billing_period_start)
+def format_date_for_api(date_str: str, granularity: str) -> str:
+    """Format date string appropriately for AWS Cost Explorer API based on granularity.
+
+    Args:
+        date_str: Date string in YYYY-MM-DD format
+        granularity: The granularity (DAILY, MONTHLY, HOURLY)
+
+    Returns:
+        Formatted date string appropriate for the API call
+    """
+    if granularity.upper() == 'HOURLY':
+        # For hourly granularity, AWS expects datetime format
+        # Convert YYYY-MM-DD to YYYY-MM-DDTHH:MM:SSZ
+        dt = datetime.strptime(date_str, '%Y-%m-%d')
+        return dt.strftime('%Y-%m-%dT00:00:00Z')
+    else:
+        # For DAILY and MONTHLY, use the original date format
+        return date_str
+
+
+def validate_date_range(
+    start_date: str, end_date: str, granularity: Optional[str] = None
+) -> Tuple[bool, str]:
+    """Validate date range with format and logical checks.
+
+    Args:
+        start_date: The start date string in YYYY-MM-DD format
+        end_date: The end date string in YYYY-MM-DD format
+        granularity: Optional granularity to check specific constraints
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    # Validate start date format
+    is_valid_start, error_start = validate_date_format(start_date)
     if not is_valid_start:
-        return {'error': error_start}
+        return False, error_start
 
-    is_valid_end, error_end = validate_date_format(billing_period_end)
+    # Validate end date format
+    is_valid_end, error_end = validate_date_format(end_date)
     if not is_valid_end:
-        return {'error': error_end}
+        return False, error_end
+
+    # Validate date range logic
+    start_dt = datetime.strptime(start_date, '%Y-%m-%d')
+    end_dt = datetime.strptime(end_date, '%Y-%m-%d')
+    if start_dt > end_dt:
+        return False, f"Start date '{start_date}' cannot be after end date '{end_date}'"
+
+    # Validate granularity-specific constraints
+    if granularity and granularity.upper() == 'HOURLY':
+        # HOURLY granularity supports maximum 14 days
+        date_diff = (end_dt - start_dt).days
+        if date_diff > 14:
+            return (
+                False,
+                f'HOURLY granularity supports a maximum of 14 days. Current range is {date_diff} days ({start_date} to {end_date}). Please use a shorter date range.',
+            )
 
-    # Validate date range
-    if billing_period_start > billing_period_end:
-        return {
-            'error': f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
-        }
+    return True, ''
+
+
+def get_dimension_values(
+    key: str, billing_period_start: str, billing_period_end: str
+) -> Dict[str, Any]:
+    """Get available values for a specific dimension."""
+    # Validate date range (no granularity constraint for dimension values)
+    is_valid, error_message = validate_date_range(billing_period_start, billing_period_end)
+    if not is_valid:
+        return {'error': error_message}
 
     try:
+        ce = get_cost_explorer_client()
         response = ce.get_dimension_values(
             TimePeriod={'Start': billing_period_start, 'End': billing_period_end},
             Dimension=key.upper(),
@@ -77,7 +160,9 @@ def get_dimension_values(
         values = [value['Value'] for value in dimension_values]
         return {'dimension': key.upper(), 'values': values}
     except Exception as e:
-        logger.error(f'Error getting dimension values: {e}')
+        logger.error(
+            f'Error getting dimension values for {key.upper()} ({billing_period_start} to {billing_period_end}): {e}'
+        )
         return {'error': str(e)}
 
 
@@ -85,22 +170,13 @@ def get_tag_values(
     tag_key: str, billing_period_start: str, billing_period_end: str
 ) -> Dict[str, Any]:
     """Get available values for a specific tag key."""
-    # Validate date formats
-    is_valid_start, error_start = validate_date_format(billing_period_start)
-    if not is_valid_start:
-        return {'error': error_start}
-
-    is_valid_end, error_end = validate_date_format(billing_period_end)
-    if not is_valid_end:
-        return {'error': error_end}
-
-    # Validate date range
-    if billing_period_start > billing_period_end:
-        return {
-            'error': f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
-        }
+    # Validate date range (no granularity constraint for tag values)
+    is_valid, error_message = validate_date_range(billing_period_start, billing_period_end)
+    if not is_valid:
+        return {'error': error_message}
 
     try:
+        ce = get_cost_explorer_client()
         response = ce.get_tags(
             TimePeriod={'Start': billing_period_start, 'End': billing_period_end},
             TagKey=tag_key,
@@ -108,10 +184,38 @@ def get_tag_values(
         tag_values = response['Tags']
         return {'tag_key': tag_key, 'values': tag_values}
     except Exception as e:
-        logger.error(f'Error getting tag values: {e}')
+        logger.error(
+            f'Error getting tag values for {tag_key} ({billing_period_start} to {billing_period_end}): {e}'
+        )
         return {'error': str(e)}
 
 
+def validate_match_options(match_options: list, filter_type: str) -> Dict[str, Any]:
+    """Validate MatchOptions based on filter type.
+
+    Args:
+        match_options: List of match options to validate
+        filter_type: Type of filter ('Dimensions', 'Tags', 'CostCategories')
+
+    Returns:
+        Empty dictionary if valid, or an error dictionary
+    """
+    if filter_type == 'Dimensions':
+        valid_options = ['EQUALS', 'CASE_SENSITIVE']
+    elif filter_type in ['Tags', 'CostCategories']:
+        valid_options = ['EQUALS', 'ABSENT', 'CASE_SENSITIVE']
+    else:
+        return {'error': f'Unknown filter type: {filter_type}'}
+
+    for option in match_options:
+        if option not in valid_options:
+            return {
+                'error': f"Invalid MatchOption '{option}' for {filter_type}. Valid values are: {valid_options}"
+            }
+
+    return {}
+
+
 def validate_expression(
     expression: Dict[str, Any], billing_period_start: str, billing_period_end: str
 ) -> Dict[str, Any]:
@@ -125,20 +229,10 @@ def validate_expression(
     Returns:
         Empty dictionary if valid, or an error dictionary
     """
-    # Validate date formats
-    is_valid_start, error_start = validate_date_format(billing_period_start)
-    if not is_valid_start:
-        return {'error': error_start}
-
-    is_valid_end, error_end = validate_date_format(billing_period_end)
-    if not is_valid_end:
-        return {'error': error_end}
-
-    # Validate date range
-    if billing_period_start > billing_period_end:
-        return {
-            'error': f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
-        }
+    # Validate date range (no granularity constraint for filter validation)
+    is_valid, error_message = validate_date_range(billing_period_start, billing_period_end)
+    if not is_valid:
+        return {'error': error_message}
 
     try:
         if 'Dimensions' in expression:
@@ -152,6 +246,11 @@ def validate_expression(
                     'error': 'Dimensions filter must include "Key", "Values", and "MatchOptions".'
                 }
 
+            # Validate MatchOptions for Dimensions
+            match_options_result = validate_match_options(dimension['MatchOptions'], 'Dimensions')
+            if 'error' in match_options_result:
+                return match_options_result
+
             dimension_key = dimension['Key']
             dimension_values = dimension['Values']
             valid_values_response = get_dimension_values(
@@ -171,6 +270,11 @@ def validate_expression(
             if 'Key' not in tag or 'Values' not in tag or 'MatchOptions' not in tag:
                 return {'error': 'Tags filter must include "Key", "Values", and "MatchOptions".'}
 
+            # Validate MatchOptions for Tags
+            match_options_result = validate_match_options(tag['MatchOptions'], 'Tags')
+            if 'error' in match_options_result:
+                return match_options_result
+
             tag_key = tag['Key']
             tag_values = tag['Values']
             valid_tag_values_response = get_tag_values(
@@ -196,6 +300,13 @@ def validate_expression(
                     'error': 'CostCategories filter must include "Key", "Values", and "MatchOptions".'
                 }
 
+            # Validate MatchOptions for CostCategories
+            match_options_result = validate_match_options(
+                cost_category['MatchOptions'], 'CostCategories'
+            )
+            if 'error' in match_options_result:
+                return match_options_result
+
         logical_operators = ['And', 'Or', 'Not']
         logical_count = sum(1 for op in logical_operators if op in expression)