awslabs.cost-explorer-mcp-server 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

awslabs/__init__.py

@@ -1,3 +1,3 @@
 """
 AWS Labs Cost Explorer MCP Server package.
-"""
+"""

awslabs/cost_explorer_mcp_server/__init__.py

@@ -1,6 +1,6 @@
-"""
-Cost Explorer MCP Server module.
+"""Cost Explorer MCP Server module.
 
 This module provides MCP tools for analyzing AWS costs and usage data through the AWS Cost Explorer API.
 """
-__version__ = '0.0.0'
+
+__version__ = "0.0.0"

awslabs/cost_explorer_mcp_server/helpers.py

@@ -1,221 +1,259 @@
 """Helper functions for the Cost Explorer MCP server."""
 
+import boto3
 import logging
 import re
-from typing import Dict, Any, List, Tuple
-import boto3
 from datetime import datetime
+from typing import Any, Dict, Tuple
+
 
 # Set up logging
 logger = logging.getLogger(__name__)
 
 # Initialize AWS Cost Explorer client
-ce = boto3.client('ce')
+ce = boto3.client("ce")
+
 
 def validate_date_format(date_str: str) -> Tuple[bool, str]:
-    """
-    Validate that a date string is in YYYY-MM-DD format and is a valid date.
-    
+    """Validate that a date string is in YYYY-MM-DD format and is a valid date.
+
     Args:
         date_str: The date string to validate
-        
+
     Returns:
         Tuple of (is_valid, error_message)
     """
     # Check format with regex
-    if not re.match(r'^\d{4}-\d{2}-\d{2}$', date_str):
+    if not re.match(r"^\d{4}-\d{2}-\d{2}$", date_str):
         return False, f"Date '{date_str}' is not in YYYY-MM-DD format"
-    
+
     # Check if it's a valid date
     try:
-        datetime.strptime(date_str, '%Y-%m-%d')
+        datetime.strptime(date_str, "%Y-%m-%d")
         return True, ""
     except ValueError as e:
         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]:
+
+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)
     if not is_valid_start:
-        return {'error': error_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}
-    
+        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}'"}
-    
+        return {
+            "error": f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
+        }
+
     try:
         response = ce.get_dimension_values(
-            TimePeriod={
-                'Start': billing_period_start,
-                'End': billing_period_end
-            },
-            Dimension=key.upper()
+            TimePeriod={"Start": billing_period_start, "End": billing_period_end},
+            Dimension=key.upper(),
         )
-        dimension_values = response['DimensionValues']
-        values = [value['Value'] for value in dimension_values]
-        return {'dimension': key.upper(), 'values': values}
+        dimension_values = response["DimensionValues"]
+        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}")
-        return {'error': str(e)}
+        return {"error": str(e)}
 
 
-def get_tag_values(tag_key: str, billing_period_start: str, billing_period_end: str) -> Dict[str, Any]:
+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}
-    
+        return {"error": error_start}
+
     is_valid_end, error_end = validate_date_format(billing_period_end)
     if not is_valid_end:
-        return {'error': error_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}'"}
-    
+        return {
+            "error": f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
+        }
+
     try:
         response = ce.get_tags(
-            TimePeriod={'Start': billing_period_start,
-                        'End': billing_period_end},
-            TagKey=tag_key
+            TimePeriod={"Start": billing_period_start, "End": billing_period_end},
+            TagKey=tag_key,
         )
-        tag_values = response['Tags']
-        return {'tag_key': tag_key, 'values': 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}")
-        return {'error': str(e)}
+        return {"error": str(e)}
 
 
+def validate_expression(
+    expression: Dict[str, Any], billing_period_start: str, billing_period_end: str
+) -> Dict[str, Any]:
+    """Recursively validate the filter expression.
 
-def validate_expression(expression: Dict[str, Any], billing_period_start: str, billing_period_end: str) -> Dict[str, Any]:
-    """
-    Recursively validate the filter expression.
-    
     Args:
         expression: The filter expression to validate
         billing_period_start: Start date of the billing period
         billing_period_end: End date of the billing period
-        
+
     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}
-    
+        return {"error": error_start}
+
     is_valid_end, error_end = validate_date_format(billing_period_end)
     if not is_valid_end:
-        return {'error': error_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}'"}
-    
+        return {
+            "error": f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
+        }
+
     try:
-        if 'Dimensions' in expression:
-            dimension = expression['Dimensions']
-            if 'Key' not in dimension or 'Values' not in dimension or 'MatchOptions' not in dimension:
-                return {'error': 'Dimensions filter must include "Key", "Values", and "MatchOptions".'}
+        if "Dimensions" in expression:
+            dimension = expression["Dimensions"]
+            if (
+                "Key" not in dimension
+                or "Values" not in dimension
+                or "MatchOptions" not in dimension
+            ):
+                return {
+                    "error": 'Dimensions filter must include "Key", "Values", and "MatchOptions".'
+                }
 
-            dimension_key = dimension['Key']
-            dimension_values = dimension['Values']
+            dimension_key = dimension["Key"]
+            dimension_values = dimension["Values"]
             valid_values_response = get_dimension_values(
-                dimension_key, billing_period_start, billing_period_end)
-            if 'error' in valid_values_response:
-                return {'error': valid_values_response['error']}
-            valid_values = valid_values_response['values']
+                dimension_key, billing_period_start, billing_period_end
+            )
+            if "error" in valid_values_response:
+                return {"error": valid_values_response["error"]}
+            valid_values = valid_values_response["values"]
             for value in dimension_values:
                 if value not in valid_values:
-                    return {'error': f"Invalid value '{value}' for dimension '{dimension_key}'. Valid values are: {valid_values}"}
+                    return {
+                        "error": f"Invalid value '{value}' for dimension '{dimension_key}'. Valid values are: {valid_values}"
+                    }
 
-        if 'Tags' in expression:
-            tag = expression['Tags']
-            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".'}
+        if "Tags" in expression:
+            tag = expression["Tags"]
+            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".'}
 
-            tag_key = tag['Key']
-            tag_values = tag['Values']
+            tag_key = tag["Key"]
+            tag_values = tag["Values"]
             valid_tag_values_response = get_tag_values(
-                tag_key, billing_period_start, billing_period_end)
-            if 'error' in valid_tag_values_response:
-                return {'error': valid_tag_values_response['error']}
-            valid_tag_values = valid_tag_values_response['values']
+                tag_key, billing_period_start, billing_period_end
+            )
+            if "error" in valid_tag_values_response:
+                return {"error": valid_tag_values_response["error"]}
+            valid_tag_values = valid_tag_values_response["values"]
             for value in tag_values:
                 if value not in valid_tag_values:
-                    return {'error': f"Invalid value '{value}' for tag '{tag_key}'. Valid values are: {valid_tag_values}"}
+                    return {
+                        "error": f"Invalid value '{value}' for tag '{tag_key}'. Valid values are: {valid_tag_values}"
+                    }
 
-        if 'CostCategories' in expression:
-            cost_category = expression['CostCategories']
-            if 'Key' not in cost_category or 'Values' not in cost_category or 'MatchOptions' not in cost_category:
-                return {'error': 'CostCategories filter must include "Key", "Values", and "MatchOptions".'}
+        if "CostCategories" in expression:
+            cost_category = expression["CostCategories"]
+            if (
+                "Key" not in cost_category
+                or "Values" not in cost_category
+                or "MatchOptions" not in cost_category
+            ):
+                return {
+                    "error": 'CostCategories filter must include "Key", "Values", and "MatchOptions".'
+                }
 
-        logical_operators = ['And', 'Or', 'Not']
+        logical_operators = ["And", "Or", "Not"]
         logical_count = sum(1 for op in logical_operators if op in expression)
 
         if logical_count > 1:
-            return {'error': 'Only one logical operator (And, Or, Not) is allowed per expression in filter parameter.'}
+            return {
+                "error": "Only one logical operator (And, Or, Not) is allowed per expression in filter parameter."
+            }
 
         if logical_count == 0 and len(expression) > 1:
-            return {'error': 'Filter parameter with multiple expressions require a logical operator (And, Or, Not).'}
+            return {
+                "error": "Filter parameter with multiple expressions require a logical operator (And, Or, Not)."
+            }
 
-        if 'And' in expression:
-            if not isinstance(expression['And'], list):
-                return {'error': 'And expression must be a list of expressions.'}
-            for sub_expression in expression['And']:
+        if "And" in expression:
+            if not isinstance(expression["And"], list):
+                return {"error": "And expression must be a list of expressions."}
+            for sub_expression in expression["And"]:
                 result = validate_expression(
-                    sub_expression, billing_period_start, billing_period_end)
-                if 'error' in result:
+                    sub_expression, billing_period_start, billing_period_end
+                )
+                if "error" in result:
                     return result
 
-        if 'Or' in expression:
-            if not isinstance(expression['Or'], list):
-                return {'error': 'Or expression must be a list of expressions.'}
-            for sub_expression in expression['Or']:
+        if "Or" in expression:
+            if not isinstance(expression["Or"], list):
+                return {"error": "Or expression must be a list of expressions."}
+            for sub_expression in expression["Or"]:
                 result = validate_expression(
-                    sub_expression, billing_period_start, billing_period_end)
-                if 'error' in result:
+                    sub_expression, billing_period_start, billing_period_end
+                )
+                if "error" in result:
                     return result
 
-        if 'Not' in expression:
-            if not isinstance(expression['Not'], dict):
-                return {'error': 'Not expression must be a single expression.'}
+        if "Not" in expression:
+            if not isinstance(expression["Not"], dict):
+                return {"error": "Not expression must be a single expression."}
             result = validate_expression(
-                expression['Not'], billing_period_start, billing_period_end)
-            if 'error' in result:
+                expression["Not"], billing_period_start, billing_period_end
+            )
+            if "error" in result:
                 return result
 
-        if not any(k in expression for k in ['Dimensions', 'Tags', 'CostCategories', 'And', 'Or', 'Not']):
-            return {'error': 'Filter Expression must include at least one of the following keys: "Dimensions", "Tags", "CostCategories", "And", "Or", "Not".'}
+        if not any(
+            k in expression for k in ["Dimensions", "Tags", "CostCategories", "And", "Or", "Not"]
+        ):
+            return {
+                "error": 'Filter Expression must include at least one of the following keys: "Dimensions", "Tags", "CostCategories", "And", "Or", "Not".'
+            }
 
         return {}
     except Exception as e:
-        return {'error': f'Error validating expression: {str(e)}'}
+        return {"error": f"Error validating expression: {str(e)}"}
 
 
 def validate_group_by(group_by: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Validate the group_by parameter.
-    
+    """Validate the group_by parameter.
+
     Args:
         group_by: The group_by dictionary to validate
-        
+
     Returns:
         Empty dictionary if valid, or an error dictionary
     """
     try:
-        if not isinstance(group_by, dict) or 'Type' not in group_by or 'Key' not in group_by:
-            return {'error': 'group_by must be a dictionary with "Type" and "Key" keys.'}
-        
-        if group_by['Type'].upper() not in ['DIMENSION', 'TAG', 'COST_CATEGORY']:
-            return {'error': 'Invalid group Type. Valid types are DIMENSION, TAG, and COST_CATEGORY.'}
-        
+        if not isinstance(group_by, dict) or "Type" not in group_by or "Key" not in group_by:
+            return {"error": 'group_by must be a dictionary with "Type" and "Key" keys.'}
+
+        if group_by["Type"].upper() not in ["DIMENSION", "TAG", "COST_CATEGORY"]:
+            return {
+                "error": "Invalid group Type. Valid types are DIMENSION, TAG, and COST_CATEGORY."
+            }
+
         return {}
     except Exception as e:
-        return {'error': f'Error validating group_by: {str(e)}'}
+        return {"error": f"Error validating group_by: {str(e)}"}

awslabs/cost_explorer_mcp_server/server.py

@@ -5,95 +5,101 @@ This server provides tools for analyzing AWS costs and usage data through the AW
 
 import boto3
 import logging
-from datetime import datetime, timedelta
 import pandas as pd
-from mcp.server.fastmcp import Context, FastMCP
-from pydantic import BaseModel, Field, field_validator
-from typing import Any, Dict, Optional, Union
-
 from awslabs.cost_explorer_mcp_server.helpers import (
     get_dimension_values,
     get_tag_values,
+    validate_date_format,
     validate_expression,
     validate_group_by,
-    validate_date_format
 )
+from datetime import datetime, timedelta
+from mcp.server.fastmcp import Context, FastMCP
+from pydantic import BaseModel, Field, field_validator
+from typing import Any, Dict, Optional, Union
+
 
 # Set up logging
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 # Initialize AWS Cost Explorer client
-ce = boto3.client('ce')
+ce = boto3.client("ce")
 
 
 class DateRange(BaseModel):
     """Date range model for cost queries."""
+
     start_date: str = Field(
         ...,
-        description="The start date of the billing period in YYYY-MM-DD format. Defaults to last month, if not provided."
+        description="The start date of the billing period in YYYY-MM-DD format. Defaults to last month, if not provided.",
     )
     end_date: str = Field(
-        ...,
-        description="The end date of the billing period in YYYY-MM-DD format."
+        ..., description="The end date of the billing period in YYYY-MM-DD format."
     )
-    
-    @field_validator('start_date')
+
+    @field_validator("start_date")
     @classmethod
     def validate_start_date(cls, v):
+        """Validate that start_date is in YYYY-MM-DD format and is a valid date."""
         is_valid, error = validate_date_format(v)
         if not is_valid:
             raise ValueError(error)
         return v
-    
-    @field_validator('end_date')
+
+    @field_validator("end_date")
     @classmethod
     def validate_end_date(cls, v, info):
+        """Validate that end_date is in YYYY-MM-DD format and is a valid date, and not before start_date."""
         is_valid, error = validate_date_format(v)
         if not is_valid:
             raise ValueError(error)
-        
+
         # Access the start_date from the data dictionary
-        start_date = info.data.get('start_date')
+        start_date = info.data.get("start_date")
         if start_date and v < start_date:
             raise ValueError(f"End date '{v}' cannot be before start date '{start_date}'")
-        
+
         return v
 
 
 class GroupBy(BaseModel):
     """Group by model for cost queries."""
+
     type: str = Field(
         ...,
-        description="Type of grouping. Valid values are DIMENSION, TAG, and COST_CATEGORY."
+        description="Type of grouping. Valid values are DIMENSION, TAG, and COST_CATEGORY.",
     )
     key: str = Field(
         ...,
-        description="Key to group by. For DIMENSION type, valid values include AZ, INSTANCE_TYPE, LEGAL_ENTITY_NAME, INVOICING_ENTITY, LINKED_ACCOUNT, OPERATION, PLATFORM, PURCHASE_TYPE, SERVICE, TENANCY, RECORD_TYPE, and USAGE_TYPE."
+        description="Key to group by. For DIMENSION type, valid values include AZ, INSTANCE_TYPE, LEGAL_ENTITY_NAME, INVOICING_ENTITY, LINKED_ACCOUNT, OPERATION, PLATFORM, PURCHASE_TYPE, SERVICE, TENANCY, RECORD_TYPE, and USAGE_TYPE.",
     )
 
 
 class FilterExpression(BaseModel):
     """Filter expression model for cost queries."""
+
     filter_json: str = Field(
         ...,
-        description="Filter criteria as a Python dictionary to narrow down AWS costs. Supports filtering by Dimensions (SERVICE, REGION, etc.), Tags, or CostCategories. You can use logical operators (And, Or, Not) for complex filters. Examples: 1) Simple service filter: {'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute', 'Amazon Simple Storage Service'], 'MatchOptions': ['EQUALS']}}. 2) Region filter: {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}. 3) Combined filter: {'And': [{'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute'], 'MatchOptions': ['EQUALS']}}, {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}]}."
+        description="Filter criteria as a Python dictionary to narrow down AWS costs. Supports filtering by Dimensions (SERVICE, REGION, etc.), Tags, or CostCategories. You can use logical operators (And, Or, Not) for complex filters. Examples: 1) Simple service filter: {'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute', 'Amazon Simple Storage Service'], 'MatchOptions': ['EQUALS']}}. 2) Region filter: {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}. 3) Combined filter: {'And': [{'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute'], 'MatchOptions': ['EQUALS']}}, {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}]}.",
     )
 
 
 class CostMetric(BaseModel):
     """Cost metric model."""
+
     metric: str = Field(
         "UnblendedCost",
-        description="The metric to return in the query. Valid values are AmortizedCost, BlendedCost, NetAmortizedCost, NetUnblendedCost, NormalizedUsageAmount, UnblendedCost, and UsageQuantity. Note: For UsageQuantity, the service aggregates usage numbers without considering units. To get meaningful UsageQuantity metrics, filter by UsageType or UsageTypeGroups."
+        description="The metric to return in the query. Valid values are AmortizedCost, BlendedCost, NetAmortizedCost, NetUnblendedCost, NormalizedUsageAmount, UnblendedCost, and UsageQuantity. Note: For UsageQuantity, the service aggregates usage numbers without considering units. To get meaningful UsageQuantity metrics, filter by UsageType or UsageTypeGroups.",
     )
 
 
 class DimensionKey(BaseModel):
     """Dimension key model."""
+
     dimension_key: str = Field(
         ...,
-        description="The name of the dimension to retrieve values for. Valid values are AZ, INSTANCE_TYPE, LINKED_ACCOUNT, OPERATION, PURCHASE_TYPE, SERVICE, USAGE_TYPE, PLATFORM, TENANCY, RECORD_TYPE, LEGAL_ENTITY_NAME, INVOICING_ENTITY, DEPLOYMENT_OPTION, DATABASE_ENGINE, CACHE_ENGINE, INSTANCE_TYPE_FAMILY, REGION, BILLING_ENTITY, RESERVATION_ID, SAVINGS_PLANS_TYPE, SAVINGS_PLAN_ARN, OPERATING_SYSTEM."
+        description="The name of the dimension to retrieve values for. Valid values are AZ, INSTANCE_TYPE, LINKED_ACCOUNT, OPERATION, PURCHASE_TYPE, SERVICE, USAGE_TYPE, PLATFORM, TENANCY, RECORD_TYPE, LEGAL_ENTITY_NAME, INVOICING_ENTITY, DEPLOYMENT_OPTION, DATABASE_ENGINE, CACHE_ENGINE, INSTANCE_TYPE_FAMILY, REGION, BILLING_ENTITY, RESERVATION_ID, SAVINGS_PLANS_TYPE, SAVINGS_PLAN_ARN, OPERATING_SYSTEM.",
     )
 
 
@@ -108,20 +114,21 @@ async def get_today_date(ctx: Context) -> Dict[str, str]:
     This tool retrieves the current date in YYYY-MM-DD format and the current month in YYYY-MM format.
     It's useful for comparing if the billing period requested by the user is not in the future.
 
+    Args:
+        ctx: MCP context
+
     Returns:
         Dictionary containing today's date and current month
     """
     return {
-        'today_date': datetime.now().strftime('%Y-%m-%d'),
-        'current_month': datetime.now().strftime('%Y-%m')
+        "today_date": datetime.now().strftime("%Y-%m-%d"),
+        "current_month": datetime.now().strftime("%Y-%m"),
     }
 
 
 @app.tool("get_dimension_values")
 async def get_dimension_values_tool(
-    ctx: Context,
-    date_range: DateRange,
-    dimension: DimensionKey
+    ctx: Context, date_range: DateRange, dimension: DimensionKey
 ) -> Dict[str, Any]:
     """Retrieve available dimension values for AWS Cost Explorer.
 
@@ -130,6 +137,7 @@ async def get_dimension_values_tool(
     for cost analysis.
 
     Args:
+        ctx: MCP context
         date_range: The billing period start and end dates in YYYY-MM-DD format
         dimension: The dimension key to retrieve values for (e.g., SERVICE, REGION, LINKED_ACCOUNT)
 
@@ -138,21 +146,19 @@ async def get_dimension_values_tool(
     """
     try:
         response = get_dimension_values(
-            dimension.dimension_key,
-            date_range.start_date,
-            date_range.end_date
+            dimension.dimension_key, date_range.start_date, date_range.end_date
         )
         return response
     except Exception as e:
         logger.error(f"Error getting dimension values: {e}")
-        return {'error': f'Error getting dimension values: {str(e)}'}
+        return {"error": f"Error getting dimension values: {str(e)}"}
 
 
 @app.tool("get_tag_values")
 async def get_tag_values_tool(
     ctx: Context,
     date_range: DateRange,
-    tag_key: str = Field(..., description="The tag key to retrieve values for")
+    tag_key: str = Field(..., description="The tag key to retrieve values for"),
 ) -> Dict[str, Any]:
     """Retrieve available tag values for AWS Cost Explorer.
 
@@ -160,6 +166,7 @@ async def get_tag_values_tool(
     This is useful for validating tag filter values or exploring available tag options for cost analysis.
 
     Args:
+        ctx: MCP context
         date_range: The billing period start and end dates in YYYY-MM-DD format
         tag_key: The tag key to retrieve values for
 
@@ -167,15 +174,11 @@ async def get_tag_values_tool(
         Dictionary containing the tag key and list of available values
     """
     try:
-        response = get_tag_values(
-            tag_key,
-            date_range.start_date,
-            date_range.end_date
-        )
+        response = get_tag_values(tag_key, date_range.start_date, date_range.end_date)
         return response
     except Exception as e:
         logger.error(f"Error getting tag values: {e}")
-        return {'error': f'Error getting tag values: {str(e)}'}
+        return {"error": f"Error getting tag values: {str(e)}"}
 
 
 @app.tool("get_cost_and_usage")
@@ -184,20 +187,20 @@ async def get_cost_and_usage(
     date_range: DateRange,
     granularity: str = Field(
         "MONTHLY",
-        description="The granularity at which cost data is aggregated. Valid values are DAILY, MONTHLY, and HOURLY. If not provided, defaults to MONTHLY."
+        description="The granularity at which cost data is aggregated. Valid values are DAILY, MONTHLY, and HOURLY. If not provided, defaults to MONTHLY.",
     ),
     group_by: Optional[Union[Dict[str, str], str]] = Field(
         None,
-        description="Either a dictionary with Type and Key for grouping costs, or simply a string key to group by (which will default to DIMENSION type). Example dictionary: {'Type': 'DIMENSION', 'Key': 'SERVICE'}. Example string: 'SERVICE'."
+        description="Either a dictionary with Type and Key for grouping costs, or simply a string key to group by (which will default to DIMENSION type). Example dictionary: {'Type': 'DIMENSION', 'Key': 'SERVICE'}. Example string: 'SERVICE'.",
     ),
     filter_expression: Optional[Dict[str, Any]] = Field(
         None,
-        description="Filter criteria as a Python dictionary to narrow down AWS costs. Supports filtering by Dimensions (SERVICE, REGION, etc.), Tags, or CostCategories. You can use logical operators (And, Or, Not) for complex filters. Examples: 1) Simple service filter: {'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute', 'Amazon Simple Storage Service'], 'MatchOptions': ['EQUALS']}}. 2) Region filter: {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}. 3) Combined filter: {'And': [{'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute'], 'MatchOptions': ['EQUALS']}}, {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}]}."
+        description="Filter criteria as a Python dictionary to narrow down AWS costs. Supports filtering by Dimensions (SERVICE, REGION, etc.), Tags, or CostCategories. You can use logical operators (And, Or, Not) for complex filters. Examples: 1) Simple service filter: {'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute', 'Amazon Simple Storage Service'], 'MatchOptions': ['EQUALS']}}. 2) Region filter: {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}. 3) Combined filter: {'And': [{'Dimensions': {'Key': 'SERVICE', 'Values': ['Amazon Elastic Compute Cloud - Compute'], 'MatchOptions': ['EQUALS']}}, {'Dimensions': {'Key': 'REGION', 'Values': ['us-east-1'], 'MatchOptions': ['EQUALS']}}]}.",
     ),
     metric: str = Field(
         "UnblendedCost",
-        description="The metric to return in the query. Valid values are AmortizedCost, BlendedCost, NetAmortizedCost, NetUnblendedCost, NormalizedUsageAmount, UnblendedCost, and UsageQuantity."
-    )
+        description="The metric to return in the query. Valid values are AmortizedCost, BlendedCost, NetAmortizedCost, NetUnblendedCost, NormalizedUsageAmount, UnblendedCost, and UsageQuantity.",
+    ),
 ) -> Dict[str, Any]:
     """Retrieve AWS cost and usage data.
 
@@ -205,12 +208,42 @@ async def get_cost_and_usage(
     with optional filtering and grouping. It dynamically generates cost reports tailored to specific needs
     by specifying parameters such as granularity, billing period dates, and filter criteria.
 
-    Note: The end_date is treated as inclusive in this tool, meaning if you specify an end_date of 
-    "2025-01-31", the results will include data for January 31st. This differs from the AWS Cost Explorer 
+    Note: The end_date is treated as inclusive in this tool, meaning if you specify an end_date of
+    "2025-01-31", the results will include data for January 31st. This differs from the AWS Cost Explorer
     API which treats end_date as exclusive.
 
+    Example: Get monthly costs for EC2 and S3 services in us-east-1 for May 2025
+        await get_cost_and_usage(
+            ctx=context,
+            date_range={
+                "start_date": "2025-05-01",
+                "end_date": "2025-05-31"
+            },
+            granularity="MONTHLY",
+            group_by={"Type": "DIMENSION", "Key": "SERVICE"},
+            filter_expression={
+                "And": [
+                    {
+                        "Dimensions": {
+                            "Key": "SERVICE",
+                            "Values": ["Amazon Elastic Compute Cloud - Compute", "Amazon Simple Storage Service"],
+                            "MatchOptions": ["EQUALS"]
+                        }
+                    },
+                    {
+                        "Dimensions": {
+                            "Key": "REGION",
+                            "Values": ["us-east-1"],
+                            "MatchOptions": ["EQUALS"]
+                        }
+                    }
+                ]
+            },
+            metric="UnblendedCost"
+        )
 
     Args:
+        ctx: MCP context
         date_range: The billing period start and end dates in YYYY-MM-DD format (end date is inclusive)
         granularity: The granularity at which cost data is aggregated (DAILY, MONTHLY, HOURLY)
         group_by: Either a dictionary with Type and Key, or simply a string key to group by
@@ -220,36 +253,39 @@ async def get_cost_and_usage(
     Returns:
         Dictionary containing cost report data grouped according to the specified parameters
     """
-
     try:
         # Process inputs
         granularity = granularity.upper()
         if granularity not in ["DAILY", "MONTHLY", "HOURLY"]:
-            return {'error': f"Invalid granularity: {granularity}. Valid values are DAILY, MONTHLY, and HOURLY."}
-            
+            return {
+                "error": f"Invalid granularity: {granularity}. Valid values are DAILY, MONTHLY, and HOURLY."
+            }
+
         billing_period_start = date_range.start_date
         billing_period_end = date_range.end_date
-        
+
         # Define valid metrics and their expected data structure
         valid_metrics = {
             "AmortizedCost": {"has_unit": True, "is_cost": True},
             "BlendedCost": {"has_unit": True, "is_cost": True},
             "NetAmortizedCost": {"has_unit": True, "is_cost": True},
             "NetUnblendedCost": {"has_unit": True, "is_cost": True},
-            "NormalizedUsageAmount": {"has_unit": True, "is_cost": False},
             "UnblendedCost": {"has_unit": True, "is_cost": True},
-            "UsageQuantity": {"has_unit": True, "is_cost": False}
+            "UsageQuantity": {"has_unit": True, "is_cost": False},
         }
-        
+
         if metric not in valid_metrics:
-            return {'error': f"Invalid metric: {metric}. Valid values are {', '.join(valid_metrics.keys())}."}
-            
+            return {
+                "error": f"Invalid metric: {metric}. Valid values are {', '.join(valid_metrics.keys())}."
+            }
+
         metric_config = valid_metrics[metric]
 
         # Adjust end date for Cost Explorer API (exclusive)
         # Add one day to make the end date inclusive for the user
-        billing_period_end_adj = (datetime.strptime(
-            billing_period_end, '%Y-%m-%d') + timedelta(days=1)).strftime('%Y-%m-%d')
+        billing_period_end_adj = (
+            datetime.strptime(billing_period_end, "%Y-%m-%d") + timedelta(days=1)
+        ).strftime("%Y-%m-%d")
 
         # Process filter
         filter_criteria = filter_expression
@@ -258,8 +294,9 @@ async def get_cost_and_usage(
         if filter_criteria:
             # This validates both structure and values against AWS Cost Explorer
             validation_result = validate_expression(
-                filter_criteria, billing_period_start, billing_period_end_adj)
-            if 'error' in validation_result:
+                filter_criteria, billing_period_start, billing_period_end_adj
+            )
+            if "error" in validation_result:
                 return validation_result
 
         # Process group_by
@@ -270,113 +307,141 @@ async def get_cost_and_usage(
 
         # Validate group_by using the existing validate_group_by function
         validation_result = validate_group_by(group_by)
-        if 'error' in validation_result:
+        if "error" in validation_result:
             return validation_result
 
         # Prepare API call parameters
         common_params = {
-            'TimePeriod': {
-                'Start': billing_period_start,
-                'End': billing_period_end_adj
+            "TimePeriod": {
+                "Start": billing_period_start,
+                "End": billing_period_end_adj,
             },
-            'Granularity': granularity,
-            'GroupBy': [{'Type': group_by['Type'].upper(), 'Key': group_by['Key']}],
-            'Metrics': [metric]
+            "Granularity": granularity,
+            "GroupBy": [{"Type": group_by["Type"].upper(), "Key": group_by["Key"]}],
+            "Metrics": [metric],
         }
 
         if filter_criteria:
-            common_params['Filter'] = filter_criteria
+            common_params["Filter"] = filter_criteria
 
         # Get cost data
         grouped_costs = {}
         next_token = None
         while True:
             if next_token:
-                common_params['NextPageToken'] = next_token
+                common_params["NextPageToken"] = next_token
 
             try:
                 response = ce.get_cost_and_usage(**common_params)
             except Exception as e:
                 logger.error(f"Error calling Cost Explorer API: {e}")
-                return {'error': f'AWS Cost Explorer API error: {str(e)}'}
+                return {"error": f"AWS Cost Explorer API error: {str(e)}"}
 
-            for result_by_time in response['ResultsByTime']:
-                date = result_by_time['TimePeriod']['Start']
-                for group in result_by_time.get('Groups', []):
-                    if not group.get('Keys') or len(group['Keys']) == 0:
+            for result_by_time in response["ResultsByTime"]:
+                date = result_by_time["TimePeriod"]["Start"]
+                for group in result_by_time.get("Groups", []):
+                    if not group.get("Keys") or len(group["Keys"]) == 0:
                         logger.warning(f"Skipping group with no keys: {group}")
                         continue
-                        
-                    group_key = group['Keys'][0]
-                    
+
+                    group_key = group["Keys"][0]
+
                     # Validate that the metric exists in the response
-                    if metric not in group.get('Metrics', {}):
-                        logger.error(f"Metric '{metric}' not found in response for group {group_key}")
-                        return {'error': f"Metric '{metric}' not found in response for group {group_key}"}
-                    
-                    metric_data = group['Metrics'][metric]
-                    
+                    if metric not in group.get("Metrics", {}):
+                        logger.error(
+                            f"Metric '{metric}' not found in response for group {group_key}"
+                        )
+                        return {
+                            "error": f"Metric '{metric}' not found in response for group {group_key}"
+                        }
+
+                    metric_data = group["Metrics"][metric]
+
                     # Validate metric data structure
-                    if 'Amount' not in metric_data:
-                        logger.error(f"Amount not found in metric data for {group_key}: {metric_data}")
-                        return {'error': f"Invalid response format: 'Amount' not found in metric data"}
-                    
+                    if "Amount" not in metric_data:
+                        logger.error(
+                            f"Amount not found in metric data for {group_key}: {metric_data}"
+                        )
+                        return {
+                            "error": "Invalid response format: 'Amount' not found in metric data"
+                        }
+
                     try:
-                        metric_data = group['Metrics'][metric]
-                        
+                        metric_data = group["Metrics"][metric]
+
                         # Validate metric data structure
-                        if 'Amount' not in metric_data:
-                            logger.error(f"Amount not found in metric data for {group_key}: {metric_data}")
-                            return {'error': f"Invalid response format: 'Amount' not found in metric data"}
-                        
+                        if "Amount" not in metric_data:
+                            logger.error(
+                                f"Amount not found in metric data for {group_key}: {metric_data}"
+                            )
+                            return {
+                                "error": "Invalid response format: 'Amount' not found in metric data"
+                            }
+
                         # Process based on metric type
                         if metric_config["is_cost"]:
                             # Handle cost metrics
-                            cost = float(metric_data['Amount'])
+                            cost = float(metric_data["Amount"])
                             grouped_costs.setdefault(date, {}).update({group_key: cost})
                         else:
                             # Handle usage metrics (UsageQuantity, NormalizedUsageAmount)
-                            if 'Unit' not in metric_data and metric_config["has_unit"]:
-                                logger.warning(f"Unit not found in {metric} data for {group_key}, using 'Unknown' as unit")
-                                unit = 'Unknown'
+                            if "Unit" not in metric_data and metric_config["has_unit"]:
+                                logger.warning(
+                                    f"Unit not found in {metric} data for {group_key}, using 'Unknown' as unit"
+                                )
+                                unit = "Unknown"
                             else:
-                                unit = metric_data.get('Unit', 'Count')
-                            amount = float(metric_data['Amount'])
+                                unit = metric_data.get("Unit", "Count")
+                            amount = float(metric_data["Amount"])
                             grouped_costs.setdefault(date, {}).update({group_key: (amount, unit)})
                     except (ValueError, TypeError) as e:
                         logger.error(f"Error processing metric data: {e}, data: {metric_data}")
-                        return {'error': f"Error processing metric data: {str(e)}"}
+                        return {"error": f"Error processing metric data: {str(e)}"}
 
-            next_token = response.get('NextPageToken')
+            next_token = response.get("NextPageToken")
             if not next_token:
                 break
 
         # Process results
         if not grouped_costs:
             logger.info("No cost data found for the specified parameters")
-            return {'message': 'No cost data found for the specified parameters', 'GroupedCosts': {}}
-            
+            return {
+                "message": "No cost data found for the specified parameters",
+                "GroupedCosts": {},
+            }
+
         try:
             if metric_config["is_cost"]:
                 # Process cost metrics
                 df = pd.DataFrame.from_dict(grouped_costs).round(2)
-                df['Service total'] = df.sum(axis=1).round(2)
-                df.loc['Total Costs'] = df.sum().round(2)
-                df = df.sort_values(by='Service total', ascending=False)
+                df["Service total"] = df.sum(axis=1).round(2)
+                df.loc["Total Costs"] = df.sum().round(2)
+                df = df.sort_values(by="Service total", ascending=False)
             else:
                 # Process usage metrics (UsageQuantity, NormalizedUsageAmount)
-                usage_df = pd.DataFrame({(k, 'Amount'): {
-                                        k1: v1[0] for k1, v1 in v.items()} for k, v in grouped_costs.items()})
+                usage_df = pd.DataFrame(
+                    {
+                        (k, "Amount"): {k1: v1[0] for k1, v1 in v.items()}
+                        for k, v in grouped_costs.items()
+                    }
+                )
                 units_df = pd.DataFrame(
-                    {(k, 'Unit'): {k1: v1[1] for k1, v1 in v.items()} for k, v in grouped_costs.items()})
+                    {
+                        (k, "Unit"): {k1: v1[1] for k1, v1 in v.items()}
+                        for k, v in grouped_costs.items()
+                    }
+                )
                 df = pd.concat([usage_df, units_df], axis=1)
 
-            result = {'GroupedCosts': df.to_dict()}
+            result = {"GroupedCosts": df.to_dict()}
         except Exception as e:
             logger.error(f"Error processing cost data into DataFrame: {e}")
-            return {'error': f"Error processing cost data: {str(e)}", 'raw_data': grouped_costs}
+            return {
+                "error": f"Error processing cost data: {str(e)}",
+                "raw_data": grouped_costs,
+            }
 
-        result = {'GroupedCosts': df.to_dict()}
+        result = {"GroupedCosts": df.to_dict()}
 
         # Convert all keys to strings for JSON serialization
         def stringify_keys(d):
@@ -392,17 +457,20 @@ async def get_cost_and_usage(
             return result
         except Exception as e:
             logger.error(f"Error serializing result: {e}")
-            return {'error': f"Error serializing result: {str(e)}"}
+            return {"error": f"Error serializing result: {str(e)}"}
 
     except Exception as e:
         logger.error(f"Error generating cost report: {e}")
         import traceback
+
         logger.error(f"Traceback: {traceback.format_exc()}")
-        return {'error': f'Error generating cost report: {str(e)}'}
+        return {"error": f"Error generating cost report: {str(e)}"}
+
 
 def main():
     """Run the MCP server with CLI argument support."""
     app.run()
 
+
 if __name__ == "__main__":
     main()

{awslabs_cost_explorer_mcp_server-0.0.1.dist-info → awslabs_cost_explorer_mcp_server-0.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.cost-explorer-mcp-server
-Version: 0.0.1
+Version: 0.0.2
 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/
@@ -127,6 +127,17 @@ The MCP server uses the AWS profile specified in the `AWS_PROFILE` environment v
 ```
 
 Make sure the AWS profile has permissions to access the AWS Cost Explorer API. The MCP server creates a boto3 session using the specified profile to authenticate with AWS services. Your AWS IAM credentials remain on your local machine and are strictly used for accessing AWS services.
+## Cost Considerations
+
+**Important:** AWS Cost Explorer API incurs charges on a per-request basis. Each API call made by this MCP server will result in charges to your AWS account.
+
+- **Cost Explorer API Pricing:** The AWS Cost Explorer API lets you directly access the interactive, ad-hoc query engine that powers AWS Cost Explorer. Each request will incur a cost of $0.01.
+- Each tool invocation that queries Cost Explorer (get_dimension_values, get_tag_values, get_cost_and_usage) will generate at least one billable API request
+- Complex queries with multiple filters or large date ranges may result in multiple API calls
+
+For current pricing information, please refer to the [AWS Cost Explorer Pricing page](https://aws.amazon.com/aws-cost-management/aws-cost-explorer/pricing/).
+
+
 ## Security Considerations
 
 ### Required IAM Permissions
@@ -135,22 +146,7 @@ The following IAM permissions are required for this MCP server:
 - ce:GetDimensionValues
 - ce:GetTags
 
-Example IAM policy:
-json
-{
-   "Version": "2012-10-17",
-   "Statement": [
-       {
-           "Effect": "Allow",
-           "Action": [
-               "ce:GetCostAndUsage",
-               "ce:GetDimensionValues",
-               "ce:GetTags"
-           ],
-           "Resource": "*"
-       }
-   ]
-}
+
 
 ## Available Tools
 

awslabs_cost_explorer_mcp_server-0.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+awslabs/__init__.py,sha256=vi9O_PzTkEpojELcg0v9esQUWLbseZTynQB4YpNYzA8,51
+awslabs/cost_explorer_mcp_server/__init__.py,sha256=DkDBVzhBu0iM3Y6ZrDi6zTydT3mtgKtwjavEhmLBnl0,169
+awslabs/cost_explorer_mcp_server/helpers.py,sha256=Snc2rhsNFbl7WmLBbrIYR21jmKU7QAjshLiv26RyilU,9470
+awslabs/cost_explorer_mcp_server/server.py,sha256=MTHU04Wm0izmrk52fWAQw-y9TpG2O-ACKzfcA_-2Rp0,20150
+awslabs_cost_explorer_mcp_server-0.0.2.dist-info/METADATA,sha256=kUuzyv89t_LOq1UNDfcinZc97ZcAfR9mnEc162kK7iM,6340
+awslabs_cost_explorer_mcp_server-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+awslabs_cost_explorer_mcp_server-0.0.2.dist-info/entry_points.txt,sha256=nkewGFi8GZCCtHhFofUmYii3OCeK_5qqgLXE4eUSFZg,98
+awslabs_cost_explorer_mcp_server-0.0.2.dist-info/licenses/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+awslabs_cost_explorer_mcp_server-0.0.2.dist-info/licenses/NOTICE,sha256=VL_gWrK0xFaHGFxxYj6BcZI30EkRxUH4Dv1u2Qsh3ao,92
+awslabs_cost_explorer_mcp_server-0.0.2.dist-info/RECORD,,

awslabs_cost_explorer_mcp_server-0.0.1.dist-info/RECORD

@@ -1,10 +0,0 @@
-awslabs/__init__.py,sha256=4CPNxIm93Eam4qERUKxlLe0tSv0h8nd0ldA40H6lRtI,50
-awslabs/cost_explorer_mcp_server/__init__.py,sha256=hzMRqVmpxqoFbtkSW8Xl6RNRwS_sVKktrHyZM2o9KJ4,168
-awslabs/cost_explorer_mcp_server/helpers.py,sha256=Rt7oVmU3TEVOF8wq4CWb8yJFLjeoSlwKLwSrHb4YA6s,9054
-awslabs/cost_explorer_mcp_server/server.py,sha256=OztURecVW8JOtJZLu6WX97YYOK_GPH-CUgImodI25qE,18388
-awslabs_cost_explorer_mcp_server-0.0.1.dist-info/METADATA,sha256=SUGpDEksg1cJj60shYmdiHtkgVZXAF1NJzPxFPknqGY,5848
-awslabs_cost_explorer_mcp_server-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-awslabs_cost_explorer_mcp_server-0.0.1.dist-info/entry_points.txt,sha256=nkewGFi8GZCCtHhFofUmYii3OCeK_5qqgLXE4eUSFZg,98
-awslabs_cost_explorer_mcp_server-0.0.1.dist-info/licenses/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
-awslabs_cost_explorer_mcp_server-0.0.1.dist-info/licenses/NOTICE,sha256=VL_gWrK0xFaHGFxxYj6BcZI30EkRxUH4Dv1u2Qsh3ao,92
-awslabs_cost_explorer_mcp_server-0.0.1.dist-info/RECORD,,