awslabs.cost-explorer-mcp-server 0.0.2__py3-none-any.whl → 0.0.5__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 @@
+# 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,17 +1,61 @@
+# 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 os
 import re
+import sys
 from datetime import datetime
-from typing import Any, Dict, Tuple
+from loguru import logger
+from typing import Any, Dict, Optional, Tuple
+
+
+# Configure Loguru logging
+logger.remove()
+logger.add(sys.stderr, level=os.getenv('FASTMCP_LOG_LEVEL', 'WARNING'))
+
+# Global client cache
+_cost_explorer_client = None
 
 
-# Set up logging
-logger = logging.getLogger(__name__)
+def get_cost_explorer_client():
+    """Get Cost Explorer client with proper session management and caching.
+
+    Returns:
+        boto3.client: Configured Cost Explorer client (cached after first call)
+    """
+    global _cost_explorer_client
+
+    if _cost_explorer_client is None:
+        try:
+            # Read environment variables dynamically
+            aws_region = os.environ.get('AWS_REGION', 'us-east-1')
+            aws_profile = os.environ.get('AWS_PROFILE')
 
-# Initialize AWS Cost Explorer client
-ce = boto3.client("ce")
+            if aws_profile:
+                _cost_explorer_client = boto3.Session(
+                    profile_name=aws_profile, region_name=aws_region
+                ).client('ce')
+            else:
+                _cost_explorer_client = boto3.Session(region_name=aws_region).client('ce')
+        except Exception as e:
+            logger.error(f'Error creating Cost Explorer client: {str(e)}')
+            raise
+
+    return _cost_explorer_client
 
 
 def validate_date_format(date_str: str) -> Tuple[bool, str]:
@@ -24,78 +68,152 @@ def validate_date_format(date_str: str) -> Tuple[bool, str]:
         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")
-        return True, ""
+        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]:
-    """Get available values for a specific dimension."""
-    # Validate date formats
-    is_valid_start, error_start = validate_date_format(billing_period_start)
+def format_date_for_api(date_str: str, granularity: str) -> str:
+    """Format date string appropriately for AWS Cost Explorer API based on granularity.
+
+    Args:
+        date_str: Date string in YYYY-MM-DD format
+        granularity: The granularity (DAILY, MONTHLY, HOURLY)
+
+    Returns:
+        Formatted date string appropriate for the API call
+    """
+    if granularity.upper() == 'HOURLY':
+        # For hourly granularity, AWS expects datetime format
+        # Convert YYYY-MM-DD to YYYY-MM-DDTHH:MM:SSZ
+        dt = datetime.strptime(date_str, '%Y-%m-%d')
+        return dt.strftime('%Y-%m-%dT00:00:00Z')
+    else:
+        # For DAILY and MONTHLY, use the original date format
+        return date_str
+
+
+def validate_date_range(
+    start_date: str, end_date: str, granularity: Optional[str] = None
+) -> Tuple[bool, str]:
+    """Validate date range with format and logical checks.
+
+    Args:
+        start_date: The start date string in YYYY-MM-DD format
+        end_date: The end date string in YYYY-MM-DD format
+        granularity: Optional granularity to check specific constraints
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    # Validate start date format
+    is_valid_start, error_start = validate_date_format(start_date)
     if not is_valid_start:
-        return {"error": error_start}
+        return False, error_start
 
-    is_valid_end, error_end = validate_date_format(billing_period_end)
+    # Validate end date format
+    is_valid_end, error_end = validate_date_format(end_date)
     if not is_valid_end:
-        return {"error": error_end}
+        return False, error_end
+
+    # Validate date range logic
+    start_dt = datetime.strptime(start_date, '%Y-%m-%d')
+    end_dt = datetime.strptime(end_date, '%Y-%m-%d')
+    if start_dt > end_dt:
+        return False, f"Start date '{start_date}' cannot be after end date '{end_date}'"
+
+    # Validate granularity-specific constraints
+    if granularity and granularity.upper() == 'HOURLY':
+        # HOURLY granularity supports maximum 14 days
+        date_diff = (end_dt - start_dt).days
+        if date_diff > 14:
+            return (
+                False,
+                f'HOURLY granularity supports a maximum of 14 days. Current range is {date_diff} days ({start_date} to {end_date}). Please use a shorter date range.',
+            )
 
-    # Validate date range
-    if billing_period_start > billing_period_end:
-        return {
-            "error": f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
-        }
+    return True, ''
+
+
+def get_dimension_values(
+    key: str, billing_period_start: str, billing_period_end: str
+) -> Dict[str, Any]:
+    """Get available values for a specific dimension."""
+    # Validate date range (no granularity constraint for dimension values)
+    is_valid, error_message = validate_date_range(billing_period_start, billing_period_end)
+    if not is_valid:
+        return {'error': error_message}
 
     try:
+        ce = get_cost_explorer_client()
         response = ce.get_dimension_values(
-            TimePeriod={"Start": billing_period_start, "End": billing_period_end},
+            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)}
+        logger.error(
+            f'Error getting dimension values for {key.upper()} ({billing_period_start} to {billing_period_end}): {e}'
+        )
+        return {'error': str(e)}
 
 
 def get_tag_values(
     tag_key: str, billing_period_start: str, billing_period_end: str
 ) -> Dict[str, Any]:
     """Get available values for a specific tag key."""
-    # Validate date formats
-    is_valid_start, error_start = validate_date_format(billing_period_start)
-    if not is_valid_start:
-        return {"error": error_start}
-
-    is_valid_end, error_end = validate_date_format(billing_period_end)
-    if not is_valid_end:
-        return {"error": error_end}
-
-    # Validate date range
-    if billing_period_start > billing_period_end:
-        return {
-            "error": f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
-        }
+    # Validate date range (no granularity constraint for tag values)
+    is_valid, error_message = validate_date_range(billing_period_start, billing_period_end)
+    if not is_valid:
+        return {'error': error_message}
 
     try:
+        ce = get_cost_explorer_client()
         response = ce.get_tags(
-            TimePeriod={"Start": billing_period_start, "End": billing_period_end},
+            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)}
+        logger.error(
+            f'Error getting tag values for {tag_key} ({billing_period_start} to {billing_period_end}): {e}'
+        )
+        return {'error': str(e)}
+
+
+def validate_match_options(match_options: list, filter_type: str) -> Dict[str, Any]:
+    """Validate MatchOptions based on filter type.
+
+    Args:
+        match_options: List of match options to validate
+        filter_type: Type of filter ('Dimensions', 'Tags', 'CostCategories')
+
+    Returns:
+        Empty dictionary if valid, or an error dictionary
+    """
+    if filter_type == 'Dimensions':
+        valid_options = ['EQUALS', 'CASE_SENSITIVE']
+    elif filter_type in ['Tags', 'CostCategories']:
+        valid_options = ['EQUALS', 'ABSENT', 'CASE_SENSITIVE']
+    else:
+        return {'error': f'Unknown filter type: {filter_type}'}
+
+    for option in match_options:
+        if option not in valid_options:
+            return {
+                'error': f"Invalid MatchOption '{option}' for {filter_type}. Valid values are: {valid_options}"
+            }
+
+    return {}
 
 
 def validate_expression(
@@ -111,132 +229,139 @@ def validate_expression(
     Returns:
         Empty dictionary if valid, or an error dictionary
     """
-    # Validate date formats
-    is_valid_start, error_start = validate_date_format(billing_period_start)
-    if not is_valid_start:
-        return {"error": error_start}
-
-    is_valid_end, error_end = validate_date_format(billing_period_end)
-    if not is_valid_end:
-        return {"error": error_end}
-
-    # Validate date range
-    if billing_period_start > billing_period_end:
-        return {
-            "error": f"Start date '{billing_period_start}' cannot be after end date '{billing_period_end}'"
-        }
+    # Validate date range (no granularity constraint for filter validation)
+    is_valid, error_message = validate_date_range(billing_period_start, billing_period_end)
+    if not is_valid:
+        return {'error': error_message}
 
     try:
-        if "Dimensions" in expression:
-            dimension = expression["Dimensions"]
+        if 'Dimensions' in expression:
+            dimension = expression['Dimensions']
             if (
-                "Key" not in dimension
-                or "Values" not in dimension
-                or "MatchOptions" not in dimension
+                'Key' not in dimension
+                or 'Values' not in dimension
+                or 'MatchOptions' not in dimension
             ):
                 return {
-                    "error": 'Dimensions filter must include "Key", "Values", and "MatchOptions".'
+                    'error': 'Dimensions filter must include "Key", "Values", and "MatchOptions".'
                 }
 
-            dimension_key = dimension["Key"]
-            dimension_values = dimension["Values"]
+            # Validate MatchOptions for Dimensions
+            match_options_result = validate_match_options(dimension['MatchOptions'], 'Dimensions')
+            if 'error' in match_options_result:
+                return match_options_result
+
+            dimension_key = dimension['Key']
+            dimension_values = dimension['Values']
             valid_values_response = get_dimension_values(
                 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"]
+            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}"
+                        '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".'}
+
+            # Validate MatchOptions for Tags
+            match_options_result = validate_match_options(tag['MatchOptions'], 'Tags')
+            if 'error' in match_options_result:
+                return match_options_result
 
-            tag_key = tag["Key"]
-            tag_values = tag["Values"]
+            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"]
+            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}"
+                        'error': f"Invalid value '{value}' for tag '{tag_key}'. Valid values are: {valid_tag_values}"
                     }
 
-        if "CostCategories" in expression:
-            cost_category = expression["CostCategories"]
+        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
+                '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".'
+                    'error': 'CostCategories filter must include "Key", "Values", and "MatchOptions".'
                 }
 
-        logical_operators = ["And", "Or", "Not"]
+            # Validate MatchOptions for CostCategories
+            match_options_result = validate_match_options(
+                cost_category['MatchOptions'], 'CostCategories'
+            )
+            if 'error' in match_options_result:
+                return match_options_result
+
+        logical_operators = ['And', 'Or', 'Not']
         logical_count = sum(1 for op in logical_operators if op in expression)
 
         if logical_count > 1:
             return {
-                "error": "Only one logical operator (And, Or, Not) is allowed per expression in filter parameter."
+                '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)."
+                '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:
+                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:
+                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
+                expression['Not'], billing_period_start, billing_period_end
             )
-            if "error" in result:
+            if 'error' in result:
                 return result
 
         if not any(
-            k in expression for k in ["Dimensions", "Tags", "CostCategories", "And", "Or", "Not"]
+            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".'
+                '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]:
+def validate_group_by(group_by: Optional[Dict[str, Any]]) -> Dict[str, Any]:
     """Validate the group_by parameter.
 
     Args:
@@ -246,14 +371,19 @@ def validate_group_by(group_by: Dict[str, Any]) -> Dict[str, Any]:
         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 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"]:
+        if group_by['Type'].upper() not in ['DIMENSION', 'TAG', 'COST_CATEGORY']:
             return {
-                "error": "Invalid group Type. Valid types are DIMENSION, TAG, and COST_CATEGORY."
+                '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

@@ -1,30 +1,49 @@
+# 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.
 """
 
-import boto3
-import logging
+import json
+import os
 import pandas as pd
+import sys
 from awslabs.cost_explorer_mcp_server.helpers import (
+    format_date_for_api,
+    get_cost_explorer_client,
     get_dimension_values,
     get_tag_values,
     validate_date_format,
+    validate_date_range,
     validate_expression,
     validate_group_by,
 )
 from datetime import datetime, timedelta
+from loguru import logger
 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__)
+# Configure Loguru logging
+logger.remove()
+logger.add(sys.stderr, level=os.getenv('FASTMCP_LOG_LEVEL', 'WARNING'))
 
-# Initialize AWS Cost Explorer client
-ce = boto3.client("ce")
+# Constants
+COST_EXPLORER_END_DATE_OFFSET = 1
 
 
 class DateRange(BaseModel):
@@ -32,66 +51,32 @@ class DateRange(BaseModel):
 
     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', 'end_date')
     @classmethod
-    def validate_start_date(cls, v):
-        """Validate that start_date is in YYYY-MM-DD format and is a valid date."""
+    def validate_individual_dates(cls, v):
+        """Validate that individual dates are in YYYY-MM-DD format and are valid dates."""
         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)
+    def model_post_init(self, __context):
+        """Validate the date range after both dates are set."""
+        is_valid, error = validate_date_range(self.start_date, self.end_date)
         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.",
-    )
-    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.",
-    )
-
-
-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']}}]}.",
-    )
-
-
-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.",
-    )
+    def validate_with_granularity(self, granularity: str):
+        """Validate the date range with granularity-specific constraints."""
+        is_valid, error = validate_date_range(self.start_date, self.end_date, granularity)
+        if not is_valid:
+            raise ValueError(error)
 
 
 class DimensionKey(BaseModel):
@@ -99,20 +84,20 @@ class DimensionKey(BaseModel):
 
     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.
+    It's useful for calculating relevent date when user ask last N months/days.
 
     Args:
         ctx: MCP context
@@ -121,12 +106,12 @@ async def get_today_date(ctx: Context) -> Dict[str, str]:
         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")
+@app.tool('get_dimension_values')
 async def get_dimension_values_tool(
     ctx: Context, date_range: DateRange, dimension: DimensionKey
 ) -> Dict[str, Any]:
@@ -150,15 +135,15 @@ async def get_dimension_values_tool(
         )
         return response
     except Exception as e:
-        logger.error(f"Error getting dimension values: {e}")
-        return {"error": f"Error getting dimension values: {str(e)}"}
+        logger.error(f'Error getting dimension values for {dimension.dimension_key}: {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.
 
@@ -177,29 +162,29 @@ async def get_tag_values_tool(
         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)}"}
+        logger.error(f'Error getting tag values for {tag_key}: {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,
+        '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. MatchOptions validation: For Dimensions, valid values are EQUALS and CASE_SENSITIVE. For Tags and CostCategories, valid values are EQUALS, ABSENT, and CASE_SENSITIVE (defaults to EQUALS and CASE_SENSITIVE). 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. IMPORTANT: For UsageQuantity, the service aggregates usage numbers without considering units, making results meaningless when mixing different unit types (e.g., compute hours + data transfer GB). To get meaningful UsageQuantity metrics, you MUST filter by USAGE_TYPE or group by USAGE_TYPE/USAGE_TYPE_GROUP to ensure consistent units.',
     ),
 ) -> Dict[str, Any]:
     """Retrieve AWS cost and usage data.
@@ -212,6 +197,10 @@ async def get_cost_and_usage(
     "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.
 
+    IMPORTANT: When using UsageQuantity metric, AWS aggregates usage numbers without considering units.
+    This makes results meaningless when different usage types have different units (e.g., EC2 compute hours
+    vs data transfer GB). For meaningful UsageQuantity results, you MUST be very specific with filtering, including USAGE_TYPE or USAGE_TYPE_GROUP.
+
     Example: Get monthly costs for EC2 and S3 services in us-east-1 for May 2025
         await get_cost_and_usage(
             ctx=context,
@@ -242,6 +231,45 @@ async def get_cost_and_usage(
             metric="UnblendedCost"
         )
 
+    Example: Get meaningful UsageQuantity for specific EC2 instance usage
+        await get_cost_and_usage(
+            ctx=context,
+            {
+            "date_range": {
+                "end_date": "2025-05-01",
+                "start_date": "2025-05-31"
+            },
+            "filter_expression": {
+                "And": [
+                {
+                    "Dimensions": {
+                    "Values": [
+                        "Amazon Elastic Compute Cloud - Compute"
+                    ],
+                    "Key": "SERVICE",
+                    "MatchOptions": [
+                        "EQUALS"
+                    ]
+                    }
+                },
+                {
+                    "Dimensions": {
+                    "Values": [
+                        "EC2: Running Hours"
+                    ],
+                    "Key": "USAGE_TYPE_GROUP",
+                    "MatchOptions": [
+                        "EQUALS"
+                    ]
+                    }
+                }
+                ]
+            },
+            "metric": "UsageQuantity",
+            "group_by": "USAGE_TYPE",
+            "granularity": "MONTHLY"
+            }
+
     Args:
         ctx: MCP context
         date_range: The billing period start and end dates in YYYY-MM-DD format (end date is inclusive)
@@ -253,30 +281,38 @@ async def get_cost_and_usage(
     Returns:
         Dictionary containing cost report data grouped according to the specified parameters
     """
+    # Initialize variables at function scope to avoid unbound variable issues
+    billing_period_start = date_range.start_date
+    billing_period_end = date_range.end_date
+
     try:
-        # Process inputs
-        granularity = granularity.upper()
-        if granularity not in ["DAILY", "MONTHLY", "HOURLY"]:
+        # Process inputs - simplified granularity validation
+        granularity = str(granularity).upper()
+
+        if granularity not in ['DAILY', 'MONTHLY', 'HOURLY']:
             return {
-                "error": f"Invalid granularity: {granularity}. Valid values are DAILY, MONTHLY, and HOURLY."
+                '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
+        # Validate date range with granularity-specific constraints
+        try:
+            date_range.validate_with_granularity(granularity)
+        except ValueError as e:
+            return {'error': str(e)}
 
         # 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},
-            "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())}."
+                'error': f'Invalid metric: {metric}. Valid values are {", ".join(valid_metrics.keys())}.'
             }
 
         metric_config = valid_metrics[metric]
@@ -284,8 +320,9 @@ async def get_cost_and_usage(
         # 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")
+            datetime.strptime(billing_period_end, '%Y-%m-%d')
+            + timedelta(days=COST_EXPLORER_END_DATE_OFFSET)
+        ).strftime('%Y-%m-%d')
 
         # Process filter
         filter_criteria = filter_expression
@@ -296,175 +333,179 @@ async def get_cost_and_usage(
             validation_result = validate_expression(
                 filter_criteria, billing_period_start, billing_period_end_adj
             )
-            if "error" in validation_result:
+            if 'error' in validation_result:
                 return validation_result
 
         # Process group_by
-        if not group_by:
-            group_by = {"Type": "DIMENSION", "Key": "SERVICE"}
+        if group_by is None:
+            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)
-        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': format_date_for_api(billing_period_start, granularity),
+                'End': format_date_for_api(billing_period_end_adj, granularity),
             },
-            "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
+        ce = get_cost_explorer_client()
+
         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)}"}
-
-            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.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}')
                         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", {}):
+                    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": "Invalid response format: 'Amount' not found in metric data"
+                            'error': f"Metric '{metric}' not found in response for group {group_key}"
                         }
 
                     try:
-                        metric_data = group["Metrics"][metric]
+                        metric_data = group['Metrics'][metric]
 
                         # Validate metric data structure
-                        if "Amount" not in metric_data:
+                        if 'Amount' not in metric_data:
                             logger.error(
-                                f"Amount not found in metric data for {group_key}: {metric_data}"
+                                f'Amount not found in metric data for {group_key}: {metric_data}'
                             )
                             return {
-                                "error": "Invalid response format: 'Amount' not found in metric data"
+                                '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"])
+                            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"]:
+                            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"
+                                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)}"}
+                        logger.error(f'Error processing metric data: {e}, group: {group_key}')
+                        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")
+            logger.info(
+                f'No cost data found for the specified parameters: {billing_period_start} to {billing_period_end}'
+            )
             return {
-                "message": "No cost data found for the specified parameters",
-                "GroupedCosts": {},
+                '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)
-                df.loc["Total Costs"] = df.sum().round(2)
-                df = df.sort_values(by="Service total", ascending=False)
+
+                # Dynamic labeling based on group dimension
+                group_dimension = group_by['Key'].lower().replace('_', ' ')
+                df[f'{group_dimension.title()} Total'] = df.sum(axis=1).round(2)
+                df.loc[f'Total {metric}'] = df.sum().round(2)
+                df = df.sort_values(by=f'{group_dimension.title()} Total', ascending=False)
+
+                result = {'GroupedCosts': df.to_dict()}
             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()
-                    }
-                )
-                units_df = pd.DataFrame(
-                    {
-                        (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)
+                # Process usage metrics with cleaner structure
+                result_data = {}
+                for date, groups in grouped_costs.items():
+                    result_data[date] = {}
+                    for group_key, (amount, unit) in groups.items():
+                        result_data[date][group_key] = {
+                            'amount': round(float(amount), 2),
+                            'unit': unit,
+                        }
 
-            result = {"GroupedCosts": df.to_dict()}
+                # Add metadata for usage metrics
+                result = {
+                    'metadata': {
+                        'grouped_by': group_by['Key'],
+                        'metric': metric,
+                        'period': f'{billing_period_start} to {billing_period_end}',
+                    },
+                    'GroupedUsage': result_data,
+                }
         except Exception as e:
-            logger.error(f"Error processing cost data into DataFrame: {e}")
+            logger.error(f'Error processing cost data into DataFrame: {e}')
             return {
-                "error": f"Error processing cost data: {str(e)}",
-                "raw_data": grouped_costs,
+                '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):
-            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]
-            else:
-                return d
-
+        # Test JSON serialization first, only stringify if needed
         try:
-            result = stringify_keys(result)
+            json.dumps(result)
             return result
-        except Exception as e:
-            logger.error(f"Error serializing result: {e}")
-            return {"error": f"Error serializing result: {str(e)}"}
+        except (TypeError, ValueError):
+            # Only stringify if JSON serialization fails
+            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) if i is not None else None for i in d]
+                else:
+                    return d
+
+            try:
+                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)}'}
 
     except Exception as e:
-        logger.error(f"Error generating cost report: {e}")
-        import traceback
+        logger.error(
+            f'Error generating cost report for period {billing_period_start} to {billing_period_end}: {e}'
+        )
 
-        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():
@@ -472,5 +513,5 @@ def main():
     app.run()
 
 
-if __name__ == "__main__":
+if __name__ == '__main__':
     main()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.cost-explorer-mcp-server
-Version: 0.0.2
+Version: 0.0.5
 Summary: MCP server for analyzing AWS costs and usage data through the AWS Cost Explorer API
 Project-URL: Homepage, https://awslabs.github.io/mcp/
 Project-URL: Documentation, https://awslabs.github.io/mcp/servers/cost-explorer-mcp-server/
@@ -22,7 +22,8 @@ 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: loguru>=0.7.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
@@ -63,6 +64,8 @@ MCP server for analyzing AWS costs and usage data through the AWS Cost Explorer
 
 ## Installation
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=awslabs.cost-explorer-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuY29zdC1leHBsb3Jlci1tY3Atc2VydmVyQGxhdGVzdCIsImVudiI6eyJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIiwiQVdTX1BST0ZJTEUiOiJ5b3VyLWF3cy1wcm9maWxlIn0sImRpc2FibGVkIjpmYWxzZSwiYXV0b0FwcHJvdmUiOltdfQ%3D%3D)
+
 Here are some ways you can work with MCP across AWS, and we'll be adding support to more products including Amazon Q Developer CLI soon: (e.g. for Amazon Q Developer CLI MCP, `~/.aws/amazonq/mcp.json`):
 
 ```json
@@ -127,6 +130,7 @@ 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.

awslabs_cost_explorer_mcp_server-0.0.5.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=p1iMZ_OlKY0bpgT2HR2oEfpeAAERmqQLBFVkVPyIUOE,14418
+awslabs/cost_explorer_mcp_server/server.py,sha256=MEoZpUb104v06VZXnw1CYTpubMnyWveMuCwDvfOMD5g,21806
+awslabs_cost_explorer_mcp_server-0.0.5.dist-info/METADATA,sha256=f7u_oUsGy-ePY3Wm_JH7S8gngvB7kkBCEEYf49Ycq_c,6745
+awslabs_cost_explorer_mcp_server-0.0.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+awslabs_cost_explorer_mcp_server-0.0.5.dist-info/entry_points.txt,sha256=nkewGFi8GZCCtHhFofUmYii3OCeK_5qqgLXE4eUSFZg,98
+awslabs_cost_explorer_mcp_server-0.0.5.dist-info/licenses/LICENSE,sha256=CeipvOyAZxBGUsFoaFqwkx54aPnIKEtm9a5u2uXxEws,10142
+awslabs_cost_explorer_mcp_server-0.0.5.dist-info/licenses/NOTICE,sha256=VL_gWrK0xFaHGFxxYj6BcZI30EkRxUH4Dv1u2Qsh3ao,92
+awslabs_cost_explorer_mcp_server-0.0.5.dist-info/RECORD,,

awslabs_cost_explorer_mcp_server-0.0.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-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,,