awslabs.cost-explorer-mcp-server 0.0.1__tar.gz → 0.0.2__tar.gz

awslabs_cost_explorer_mcp_server-0.0.2/Dockerfile

@@ -0,0 +1,82 @@
+# 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. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
+FROM public.ecr.aws/sam/build-python3.10@sha256:e78695db10ca8cb129e59e30f7dc9789b0dbd0181dba195d68419c72bac51ac1 AS uv
+
+# Install the project into `/app`
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Prefer the system python
+ENV UV_PYTHON_PREFERENCE=only-system
+
+# Run without updating the uv.lock file like running with `--frozen`
+ENV UV_FROZEN=true
+
+# Copy the required files first
+COPY pyproject.toml uv.lock ./
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+    pip install uv && \
+    uv sync --frozen --no-install-project --no-dev --no-editable
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+COPY . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-editable
+
+# Make the directory just in case it doesn't exist
+RUN mkdir -p /root/.local
+
+FROM public.ecr.aws/sam/build-python3.10@sha256:e78695db10ca8cb129e59e30f7dc9789b0dbd0181dba195d68419c72bac51ac1
+
+# Place executables in the environment at the front of the path and include other binaries
+ENV PATH="/app/.venv/bin:$PATH:/usr/sbin"
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    FASTMCP_LOG_LEVEL=INFO
+
+# Install lsof for the healthcheck
+# Install other tools as needed for the MCP server
+# Add non-root user and ability to change directory into /root
+RUN yum update -y && \
+    yum install -y lsof && \
+    yum clean all -y && \
+    rm -rf /var/cache/yum && \
+    groupadd --force --system app && \
+    useradd app -g app -d /app && \
+    chmod o+x /root
+
+# Get the project from the uv layer
+COPY --from=uv --chown=app:app /root/.local /root/.local
+COPY --from=uv --chown=app:app /app/.venv /app/.venv
+
+# Get healthcheck script
+COPY ./docker-healthcheck.sh /usr/local/bin/docker-healthcheck.sh
+RUN chmod +x /usr/local/bin/docker-healthcheck.sh
+
+# Run as non-root
+USER app
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 CMD [ "docker-healthcheck.sh" ]
+
+# Use entrypoint instead of CMD
+ENTRYPOINT ["awslabs.cost-explorer-mcp-server"]

{awslabs_cost_explorer_mcp_server-0.0.1 → awslabs_cost_explorer_mcp_server-0.0.2}/PKG-INFO

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

{awslabs_cost_explorer_mcp_server-0.0.1 → awslabs_cost_explorer_mcp_server-0.0.2}/README.md

@@ -98,6 +98,17 @@ The MCP server uses the AWS profile specified in the `AWS_PROFILE` environment v
 ```
 
 Make sure the AWS profile has permissions to access the AWS Cost Explorer API. The MCP server creates a boto3 session using the specified profile to authenticate with AWS services. Your AWS IAM credentials remain on your local machine and are strictly used for accessing AWS services.
+## Cost Considerations
+
+**Important:** AWS Cost Explorer API incurs charges on a per-request basis. Each API call made by this MCP server will result in charges to your AWS account.
+
+- **Cost Explorer API Pricing:** The AWS Cost Explorer API lets you directly access the interactive, ad-hoc query engine that powers AWS Cost Explorer. Each request will incur a cost of $0.01.
+- Each tool invocation that queries Cost Explorer (get_dimension_values, get_tag_values, get_cost_and_usage) will generate at least one billable API request
+- Complex queries with multiple filters or large date ranges may result in multiple API calls
+
+For current pricing information, please refer to the [AWS Cost Explorer Pricing page](https://aws.amazon.com/aws-cost-management/aws-cost-explorer/pricing/).
+
+
 ## Security Considerations
 
 ### Required IAM Permissions
@@ -106,22 +117,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.1 → awslabs_cost_explorer_mcp_server-0.0.2}/awslabs/__init__.py

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

{awslabs_cost_explorer_mcp_server-0.0.1 → awslabs_cost_explorer_mcp_server-0.0.2}/awslabs/cost_explorer_mcp_server/__init__.py

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

awslabs_cost_explorer_mcp_server-0.0.2/awslabs/cost_explorer_mcp_server/helpers.py

@@ -0,0 +1,259 @@
+"""Helper functions for the Cost Explorer MCP server."""
+
+import boto3
+import logging
+import re
+from datetime import datetime
+from typing import Any, Dict, Tuple
+
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+# Initialize AWS Cost Explorer client
+ce = boto3.client("ce")
+
+
+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.
+
+    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, ""
+    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)
+    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}'"
+        }
+
+    try:
+        response = ce.get_dimension_values(
+            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}")
+        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}'"
+        }
+
+    try:
+        response = ce.get_tags(
+            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}")
+        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.
+
+    Args:
+        expression: The filter expression to validate
+        billing_period_start: Start date of the billing period
+        billing_period_end: End date of the billing period
+
+    Returns:
+        Empty dictionary if valid, or an error dictionary
+    """
+    # Validate date formats
+    is_valid_start, error_start = validate_date_format(billing_period_start)
+    if not is_valid_start:
+        return {"error": error_start}
+
+    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}'"
+        }
+
+    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".'
+                }
+
+            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"]
+            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}"
+                    }
+
+        if "Tags" in expression:
+            tag = expression["Tags"]
+            if "Key" not in tag or "Values" not in tag or "MatchOptions" not in tag:
+                return {"error": 'Tags filter must include "Key", "Values", and "MatchOptions".'}
+
+            tag_key = tag["Key"]
+            tag_values = tag["Values"]
+            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"]
+            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}"
+                    }
+
+        if "CostCategories" in expression:
+            cost_category = expression["CostCategories"]
+            if (
+                "Key" not in cost_category
+                or "Values" not in cost_category
+                or "MatchOptions" not in cost_category
+            ):
+                return {
+                    "error": 'CostCategories filter must include "Key", "Values", and "MatchOptions".'
+                }
+
+        logical_operators = ["And", "Or", "Not"]
+        logical_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."
+            }
+
+        if logical_count == 0 and len(expression) > 1:
+            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
+                )
+                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"]:
+                result = validate_expression(
+                    sub_expression, billing_period_start, billing_period_end
+                )
+                if "error" in result:
+                    return result
+
+        if "Not" in expression:
+            if not isinstance(expression["Not"], dict):
+                return {"error": "Not expression must be a single expression."}
+            result = validate_expression(
+                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".'
+            }
+
+        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.
+
+    Args:
+        group_by: The group_by dictionary to validate
+
+    Returns:
+        Empty dictionary if valid, or an error dictionary
+    """
+    try:
+        if not isinstance(group_by, dict) or "Type" not in group_by or "Key" not in group_by:
+            return {"error": 'group_by must be a dictionary with "Type" and "Key" keys.'}
+
+        if group_by["Type"].upper() not in ["DIMENSION", "TAG", "COST_CATEGORY"]:
+            return {
+                "error": "Invalid group Type. Valid types are DIMENSION, TAG, and COST_CATEGORY."
+            }
+
+        return {}
+    except Exception as e:
+        return {"error": f"Error validating group_by: {str(e)}"}