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

awslabs/__init__.py

@@ -1,3 +1,17 @@
+# 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.
+
 """
 AWS Labs Cost Explorer MCP Server package.
-"""
+"""

awslabs/cost_explorer_mcp_server/__init__.py

@@ -1,6 +1,20 @@
-"""
-Cost Explorer MCP Server module.
+# 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.
+
+"""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,10 +1,25 @@
+# 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.
+
 """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, Optional, Tuple
+
 
 # Set up logging
 logger = logging.getLogger(__name__)
@@ -12,96 +27,101 @@ logger = logging.getLogger(__name__)
 # Initialize AWS Cost Explorer client
 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):
         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')
-        return True, ""
+        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}
-    
+
     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}'"}
-    
+        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}
     except Exception as e:
-        logger.error(f"Error getting dimension values: {e}")
+        logger.error(f'Error getting dimension values: {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}
-    
+
     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}'"}
-    
+        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}
     except Exception as e:
-        logger.error(f"Error getting tag values: {e}")
+        logger.error(f'Error getting tag values: {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
     """
@@ -109,31 +129,42 @@ def validate_expression(expression: Dict[str, Any], billing_period_start: str, b
     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}'"}
-    
+        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 (
+                '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']
             valid_values_response = get_dimension_values(
-                dimension_key, billing_period_start, billing_period_end)
+                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']
@@ -143,34 +174,48 @@ def validate_expression(expression: Dict[str, Any], billing_period_start: str, b
             tag_key = tag['Key']
             tag_values = tag['Values']
             valid_tag_values_response = get_tag_values(
-                tag_key, billing_period_start, billing_period_end)
+                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 (
+                '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_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']:
                 result = validate_expression(
-                    sub_expression, billing_period_start, billing_period_end)
+                    sub_expression, billing_period_start, billing_period_end
+                )
                 if 'error' in result:
                     return result
 
@@ -179,7 +224,8 @@ def validate_expression(expression: Dict[str, Any], billing_period_start: str, b
                 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)
+                    sub_expression, billing_period_start, billing_period_end
+                )
                 if 'error' in result:
                     return result
 
@@ -187,35 +233,46 @@ def validate_expression(expression: Dict[str, Any], billing_period_start: str, b
             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)
+                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)}'}
 
 
-def validate_group_by(group_by: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Validate the group_by parameter.
-    
+def validate_group_by(group_by: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """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:
+        if (
+            group_by is None
+            or 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 {
+                '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)}'}

awslabs/cost_explorer_mcp_server/server.py

@@ -1,3 +1,17 @@
+# 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.
+
 """Cost Explorer MCP server implementation.
 
 This server provides tools for analyzing AWS costs and usage data through the AWS Cost Explorer API.
@@ -5,19 +19,19 @@ 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)
@@ -29,99 +43,106 @@ 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')
     @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')
     @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')
         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."
+        '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.',
     )
 
 
 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.',
     )
 
 
 # Create FastMCP server
-app = FastMCP(title="Cost Explorer MCP Server")
+app = FastMCP(title='Cost Explorer MCP Server')
 
 
-@app.tool("get_today_date")
+@app.tool('get_today_date')
 async def get_today_date(ctx: Context) -> Dict[str, str]:
     """Retrieve current date information.
 
     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')
+        'current_month': datetime.now().strftime('%Y-%m'),
     }
 
 
-@app.tool("get_dimension_values")
+@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 +151,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 +160,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}")
+        logger.error(f'Error getting dimension values: {e}')
         return {'error': f'Error getting dimension values: {str(e)}'}
 
 
-@app.tool("get_tag_values")
+@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 +180,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,37 +188,33 @@ 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}")
+        logger.error(f'Error getting tag values: {e}')
         return {'error': f'Error getting tag values: {str(e)}'}
 
 
-@app.tool("get_cost_and_usage")
+@app.tool('get_cost_and_usage')
 async def get_cost_and_usage(
     ctx: Context,
     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."
+        '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."
-    )
+        'UnblendedCost',
+        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 +222,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 +267,44 @@ 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."}
-            
+        if isinstance(granularity, str):
+            granularity = granularity.upper()
+        else:
+            # Handle case where granularity is a Pydantic FieldInfo object
+            granularity = str(granularity).upper()
+
+        if granularity not in ['DAILY', 'MONTHLY', '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}
+            '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},
+            'UnblendedCost': {'has_unit': True, 'is_cost': True},
+            '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,15 +313,16 @@ 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)
+                filter_criteria, billing_period_start, billing_period_end_adj
+            )
             if 'error' in validation_result:
                 return validation_result
 
         # Process group_by
         if not group_by:
-            group_by = {"Type": "DIMENSION", "Key": "SERVICE"}
+            group_by = {'Type': 'DIMENSION', 'Key': 'SERVICE'}
         elif isinstance(group_by, str):
-            group_by = {"Type": "DIMENSION", "Key": group_by}
+            group_by = {'Type': 'DIMENSION', 'Key': group_by}
 
         # Validate group_by using the existing validate_group_by function
         validation_result = validate_group_by(group_by)
@@ -277,11 +333,11 @@ async def get_cost_and_usage(
         common_params = {
             'TimePeriod': {
                 'Start': billing_period_start,
-                'End': billing_period_end_adj
+                'End': billing_period_end_adj,
             },
             'Granularity': granularity,
             'GroupBy': [{'Type': group_by['Type'].upper(), 'Key': group_by['Key']}],
-            'Metrics': [metric]
+            'Metrics': [metric],
         }
 
         if filter_criteria:
@@ -297,55 +353,69 @@ async def get_cost_and_usage(
             try:
                 response = ce.get_cost_and_usage(**common_params)
             except Exception as e:
-                logger.error(f"Error calling Cost Explorer API: {e}")
+                logger.error(f'Error calling Cost Explorer API: {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:
-                        logger.warning(f"Skipping group with no keys: {group}")
+                        logger.warning(f'Skipping group with no keys: {group}')
                         continue
-                        
+
                     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}"}
-                    
+                        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"}
-                    
+                        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]
-                        
+
                         # 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"}
-                        
+                            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"]:
+                        if metric_config['is_cost']:
                             # Handle cost metrics
                             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")
+                            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'])
                             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)}"}
+                        logger.error(f'Error processing metric data: {e}, data: {metric_data}')
+                        return {'error': f'Error processing metric data: {str(e)}'}
 
             next_token = response.get('NextPageToken')
             if not next_token:
@@ -353,11 +423,14 @@ async def get_cost_and_usage(
 
         # 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': {}}
-            
+            logger.info('No cost data found for the specified parameters')
+            return {
+                'message': 'No cost data found for the specified parameters',
+                'GroupedCosts': {},
+            }
+
         try:
-            if metric_config["is_cost"]:
+            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)
@@ -365,25 +438,36 @@ async def get_cost_and_usage(
                 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()}
         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}
+            logger.error(f'Error processing cost data into DataFrame: {e}')
+            return {
+                'error': f'Error processing cost data: {str(e)}',
+                'raw_data': grouped_costs,
+            }
 
         result = {'GroupedCosts': df.to_dict()}
 
         # Convert all keys to strings for JSON serialization
-        def stringify_keys(d):
+        def stringify_keys(d: Any) -> Any:
             if isinstance(d, dict):
                 return {str(k): stringify_keys(v) for k, v in d.items()}
             elif isinstance(d, list):
-                return [stringify_keys(i) for i in d]
+                return [{} if i is None else stringify_keys(i) for i in d]  # Handle None values
             else:
                 return d
 
@@ -391,18 +475,21 @@ async def get_cost_and_usage(
             result = stringify_keys(result)
             return result
         except Exception as e:
-            logger.error(f"Error serializing result: {e}")
-            return {'error': f"Error serializing result: {str(e)}"}
+            logger.error(f'Error serializing result: {e}')
+            return {'error': f'Error serializing result: {str(e)}'}
 
     except Exception as e:
-        logger.error(f"Error generating cost report: {e}")
+        logger.error(f'Error generating cost report: {e}')
         import traceback
-        logger.error(f"Traceback: {traceback.format_exc()}")
+
+        logger.error(f'Traceback: {traceback.format_exc()}')
         return {'error': f'Error generating cost report: {str(e)}'}
 
+
 def main():
     """Run the MCP server with CLI argument support."""
     app.run()
 
-if __name__ == "__main__":
+
+if __name__ == '__main__':
     main()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.cost-explorer-mcp-server
-Version: 0.0.1
+Version: 0.0.4
 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,7 +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: fastmcp>=0.1.0
+Requires-Dist: mcp[cli]>=1.6.0
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: pydantic>=2.10.6
 Description-Content-Type: text/markdown
@@ -127,6 +127,18 @@ 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 +147,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.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+awslabs/__init__.py,sha256=XlNvbbm4JS0QaAK93MUCbMITZLOSkWkBilYvLI3rBpU,667
+awslabs/cost_explorer_mcp_server/__init__.py,sha256=jj08M9QRfjYVfiV85UhDzpEO4Vseafpeekg31d2DhfM,785
+awslabs/cost_explorer_mcp_server/helpers.py,sha256=8ldRc2TVFuE7-0Js4nQWw3v3e3Om48QgQgbTAXOecgI,10186
+awslabs/cost_explorer_mcp_server/server.py,sha256=joYtlqmNnjGm162Qe71sz_weDNUujAGS6-RvdG5wpT4,21007
+awslabs_cost_explorer_mcp_server-0.0.4.dist-info/METADATA,sha256=RrYXLshB_1ZL448HUxTxw7RZl1ktNgXbLkZXBtvJ4pY,6342
+awslabs_cost_explorer_mcp_server-0.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+awslabs_cost_explorer_mcp_server-0.0.4.dist-info/entry_points.txt,sha256=nkewGFi8GZCCtHhFofUmYii3OCeK_5qqgLXE4eUSFZg,98
+awslabs_cost_explorer_mcp_server-0.0.4.dist-info/licenses/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+awslabs_cost_explorer_mcp_server-0.0.4.dist-info/licenses/NOTICE,sha256=VL_gWrK0xFaHGFxxYj6BcZI30EkRxUH4Dv1u2Qsh3ao,92
+awslabs_cost_explorer_mcp_server-0.0.4.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,,