awslabs.ccapi-mcp-server 1.0.1__py3-none-any.whl

awslabs/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+
+# This file is part of the awslabs namespace.
+# It is intentionally minimal to support PEP 420 namespace packages.

awslabs/ccapi_mcp_server/__init__.py

@@ -0,0 +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.
+
+"""awslabs.ccapi-mcp-server"""
+
+__version__ = '1.0.1'

awslabs/ccapi_mcp_server/aws_client.py

@@ -0,0 +1,62 @@
+# 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.
+
+import botocore.config
+from awslabs.ccapi_mcp_server import __version__
+from awslabs.ccapi_mcp_server.errors import ClientError
+from boto3 import Session
+from os import environ
+
+
+session_config = botocore.config.Config(
+    user_agent_extra=f'ccapi-mcp-server/{__version__}',
+)
+
+
+def get_aws_client(service_name, region_name=None):
+    """Create and return an AWS service client using boto3's default credential chain.
+
+    Args:
+        service_name: AWS service name (e.g., 'cloudcontrol', 'logs', 'marketplace-catalog')
+        region_name: AWS region name (defaults to boto3's default region resolution)
+
+    Returns:
+        Boto3 client for the specified service
+    """
+    # Handle FieldInfo objects (from pydantic)
+    if hasattr(region_name, 'default') and region_name is not None:
+        region_name = region_name.default
+
+    # AWS Region Resolution Order (highest to lowest priority):
+    # 1. region_name argument passed to this function
+    # 2. AWS_REGION environment variable
+    # 3. region setting in ~/.aws/config for the active profile
+    # 4. "us-east-1" as the final fallback
+    #
+    # This follows boto3's standard region resolution chain, ensuring consistent
+    # behavior with other AWS tools and SDKs.
+    profile_name = environ.get('AWS_PROFILE')
+    session = Session(profile_name=profile_name) if profile_name else Session()
+
+    try:
+        return session.client(service_name, region_name=region_name, config=session_config)
+    except Exception as e:
+        if 'ExpiredToken' in str(e):
+            raise ClientError('Your AWS credentials have expired. Please refresh them.')
+        elif 'NoCredentialProviders' in str(e):
+            raise ClientError(
+                'No AWS credentials found. Please configure credentials using environment variables or AWS configuration.'
+            )
+        else:
+            raise ClientError('Got an error when loading your client.')

awslabs/ccapi_mcp_server/cloud_control_utils.py

@@ -0,0 +1,120 @@
+# 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.
+
+from awslabs.ccapi_mcp_server.errors import ClientError
+from typing import Any, Dict
+
+
+def add_default_tags(properties: Dict, schema: Dict) -> Dict:
+    """Add default tags to resource properties. Always tries to add tags - let AWS reject if unsupported."""
+    # Return empty dict when properties is None or empty dict {}
+    # This prevents processing invalid/missing resource properties
+    if not properties:
+        return {}
+
+    properties_with_tags = properties.copy()
+
+    # Always try to add tags - don't check schema since it can be unreliable
+    # Ensure Tags array exists
+    if 'Tags' not in properties_with_tags:
+        properties_with_tags['Tags'] = []
+
+    tags = properties_with_tags['Tags']
+    # Add default tags if they don't exist
+    managed_by_exists = any(tag.get('Key') == 'MANAGED_BY' for tag in tags)
+    source_exists = any(tag.get('Key') == 'MCP_SERVER_SOURCE_CODE' for tag in tags)
+    version_exists = any(tag.get('Key') == 'MCP_SERVER_VERSION' for tag in tags)
+
+    if not managed_by_exists:
+        tags.append({'Key': 'MANAGED_BY', 'Value': 'CCAPI-MCP-SERVER'})
+    if not source_exists:
+        tags.append(
+            {
+                'Key': 'MCP_SERVER_SOURCE_CODE',
+                'Value': 'https://github.com/awslabs/mcp/tree/main/src/ccapi-mcp-server',
+            }
+        )
+    if not version_exists:
+        from awslabs.ccapi_mcp_server import __version__
+
+        tags.append({'Key': 'MCP_SERVER_VERSION', 'Value': __version__})
+
+    properties_with_tags['Tags'] = tags
+
+    return properties_with_tags
+
+
+def validate_patch(patch_document: Any):
+    """A best effort check that makes sure that the format of a patch document is valid before sending it to CloudControl."""
+    if not isinstance(patch_document, list):
+        raise ClientError('Patch document must be a list')
+
+    for patch_op in patch_document:
+        if not isinstance(patch_op, dict):
+            raise ClientError('Each patch operation must be a dictionary')
+        if 'op' not in patch_op:
+            raise ClientError("Each patch operation must include an 'op' field")
+        if patch_op['op'] not in ['add', 'remove', 'replace', 'move', 'copy', 'test']:
+            raise ClientError(
+                f"Operation '{patch_op['op']}' is not supported. Must be one of: add, remove, replace, move, copy, test"
+            )
+        if 'path' not in patch_op:
+            raise ClientError("Each patch operation must include a 'path' field")
+        # Value is required for add, replace, and test operations
+        if patch_op['op'] in ['add', 'replace', 'test'] and 'value' not in patch_op:
+            raise ClientError(f"The '{patch_op['op']}' operation requires a 'value' field")
+        # From is required for move and copy operations
+        if patch_op['op'] in ['move', 'copy'] and 'from' not in patch_op:
+            raise ClientError(f"The '{patch_op['op']}' operation requires a 'from' field")
+
+
+def progress_event(response_event, hooks_events) -> Dict[str, Any]:
+    """Map a CloudControl API response to a standard output format for the MCP."""
+    response = {
+        'status': response_event['OperationStatus'],
+        'resource_type': response_event['TypeName'],
+        'is_complete': response_event['OperationStatus'] == 'SUCCESS'
+        or response_event['OperationStatus'] == 'FAILED',
+        'request_token': response_event['RequestToken'],
+    }
+
+    if response_event.get('Identifier', None):
+        response['identifier'] = response_event['Identifier']
+    if response_event.get('ResourceModel', None):
+        response['resource_info'] = response_event['ResourceModel']
+    if response_event.get('ErrorCode', None):
+        response['error_code'] = response_event['ErrorCode']
+    if response_event.get('EventTime', None):
+        response['event_time'] = response_event['EventTime']
+    if response_event.get('RetryAfter', None):
+        response['retry_after'] = response_event['RetryAfter']
+
+    # CloudControl returns a list of hooks events which may also contain a message which should
+    # take precedent over the status message returned from CloudControl directly
+    hooks_status_message = None
+    if hooks_events:
+        failed_hook_event_messages = (
+            hook_event['HookStatusMessage']
+            for hook_event in hooks_events
+            if hook_event.get('HookStatus', None) == 'HOOK_COMPLETE_FAILED'
+            or hook_event.get('HookStatus', None) == 'HOOK_FAILED'
+        )
+        hooks_status_message = next(failed_hook_event_messages, None)
+
+    if hooks_status_message:
+        response['status_message'] = hooks_status_message
+    elif response_event.get('StatusMessage', None):
+        response['status_message'] = response_event['StatusMessage']
+
+    return response

awslabs/ccapi_mcp_server/context.py

@@ -0,0 +1,37 @@
+# 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.
+
+from awslabs.ccapi_mcp_server.errors import ServerError
+
+
+class Context:
+    """A singleton which includes context for the MCP server such as startup parameters."""
+
+    _instance = None
+
+    def __init__(self, readonly_mode: bool):
+        """Initializes the context."""
+        self._readonly_mode = readonly_mode
+
+    @classmethod
+    def readonly_mode(cls) -> bool:
+        """If a the server was started up with the argument --readonly True, this will be set to True."""
+        if cls._instance is None:
+            raise ServerError('Context was not initialized')
+        return cls._instance._readonly_mode
+
+    @classmethod
+    def initialize(cls, readonly_mode: bool):
+        """Create the singleton instance of the type."""
+        cls._instance = cls(readonly_mode)

awslabs/ccapi_mcp_server/errors.py

@@ -0,0 +1,67 @@
+# 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.
+
+
+def handle_aws_api_error(e: Exception) -> Exception:
+    """Handle AWS API errors using boto3's built-in exception information.
+
+    Leverages boto3's structured error handling as documented at:
+    https://boto3.amazonaws.com/v1/documentation/api/latest/guide/error-handling.html
+
+    Args:
+        e: The exception that was raised
+
+    Returns:
+        Standardized ClientError with AWS error details
+    """
+    # Import boto3 exceptions for proper type checking
+    from botocore.exceptions import ClientError as BotocoreClientError
+    from botocore.exceptions import NoCredentialsError, PartialCredentialsError
+
+    # Handle boto3's structured exceptions directly
+    if isinstance(e, BotocoreClientError):
+        # boto3 ClientError already has structured error information
+        error_code = e.response['Error']['Code']
+        error_message = e.response['Error']['Message']
+        return ClientError(f'AWS API Error ({error_code}): {error_message}')
+    elif isinstance(e, NoCredentialsError):
+        return ClientError('AWS credentials not found. Please configure your AWS credentials.')
+    elif isinstance(e, PartialCredentialsError):
+        return ClientError(
+            'Incomplete AWS credentials. Please check your AWS credential configuration.'
+        )
+    else:
+        # Fallback for other exceptions
+        return ClientError(f'An error occurred: {str(e)}')
+
+
+class ClientError(Exception):
+    """An error that indicates that the request was malformed or incorrect in some way. There was no issue on the server side."""
+
+    def __init__(self, message):
+        """Call super and set message."""
+        # Call the base class constructor with the parameters it needs
+        super().__init__(message)
+        self.type = 'client'
+        self.message = message
+
+
+class ServerError(Exception):
+    """An error that indicates that there was an issue processing the request."""
+
+    def __init__(self, message: str):
+        """Initialize ServerError with message."""
+        super().__init__(message)
+        self.type = 'server'
+        self.message = message

awslabs/ccapi_mcp_server/iac_generator.py

@@ -0,0 +1,203 @@
+# 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.
+
+"""CloudFormation IaC Generator tool implementation."""
+
+import os
+from awslabs.ccapi_mcp_server.aws_client import get_aws_client
+from awslabs.ccapi_mcp_server.errors import ClientError, handle_aws_api_error
+from typing import Dict, List, Optional
+
+
+async def create_template(
+    template_name: Optional[str] = None,
+    resources: Optional[List[Dict[str, str]]] = None,
+    output_format: str = 'YAML',
+    deletion_policy: str = 'RETAIN',
+    update_replace_policy: str = 'RETAIN',
+    template_id: Optional[str] = None,
+    save_to_file: Optional[str] = None,
+    region_name: Optional[str] = None,
+) -> Dict:
+    """Create a CloudFormation template from existing resources using the IaC Generator API.
+
+    This function handles three main scenarios:
+    1. Starting a new template generation process
+    2. Checking the status of an existing template generation process
+    3. Retrieving a generated template
+
+    Args:
+        template_name: Name for the generated template
+        resources: List of resources to include in the template, each with 'ResourceType' and 'ResourceIdentifier'
+        output_format: Output format for the template (JSON or YAML)
+        deletion_policy: Default DeletionPolicy for resources in the template (RETAIN, DELETE, or SNAPSHOT)
+        update_replace_policy: Default UpdateReplacePolicy for resources in the template (RETAIN, DELETE, or SNAPSHOT)
+        template_id: ID of an existing template generation process to check status or retrieve template
+        save_to_file: Path to save the generated template to a file
+        region_name: AWS region name
+
+    Returns:
+        A dictionary containing information about the template generation process or the generated template
+    """
+    # Validate parameters
+    if not template_id and not template_name:
+        raise ClientError('Either template_name or template_id must be provided')
+
+    if output_format not in ['JSON', 'YAML']:
+        raise ClientError("output_format must be either 'JSON' or 'YAML'")
+
+    if deletion_policy not in ['RETAIN', 'DELETE', 'SNAPSHOT']:
+        raise ClientError("deletion_policy must be one of 'RETAIN', 'DELETE', or 'SNAPSHOT'")
+
+    if update_replace_policy not in ['RETAIN', 'DELETE', 'SNAPSHOT']:
+        raise ClientError("update_replace_policy must be one of 'RETAIN', 'DELETE', or 'SNAPSHOT'")
+
+    # Get CloudFormation client
+    cfn_client = get_aws_client('cloudformation', region_name)
+
+    # Case 1: Check status or retrieve template for an existing template generation process
+    if template_id:
+        return await _handle_existing_template(
+            cfn_client, template_id, save_to_file, output_format
+        )
+
+    # Case 2: Start a new template generation process
+    return await _start_template_generation(
+        cfn_client, template_name, resources, deletion_policy, update_replace_policy
+    )
+
+
+async def _start_template_generation(
+    cfn_client,
+    template_name: str | None,
+    resources: Optional[List[Dict[str, str]]],
+    deletion_policy: str,
+    update_replace_policy: str,
+) -> Dict:
+    """Start a new template generation process.
+
+    Args:
+        cfn_client: Boto3 CloudFormation client
+        template_name: Name for the generated template
+        resources: List of resources to include in the template
+        output_format: Output format for the template (JSON or YAML)
+        deletion_policy: DeletionPolicy for resources in the template
+        update_replace_policy: UpdateReplacePolicy for resources in the template
+
+    Returns:
+        A dictionary containing information about the template generation process
+    """
+    # Prepare parameters for the API call
+    params = {
+        'GeneratedTemplateName': template_name,
+        'TemplateConfiguration': {
+            'DeletionPolicy': deletion_policy,
+            'UpdateReplacePolicy': update_replace_policy,
+        },
+    }
+
+    # Add resources if provided
+    if resources:
+        resource_identifiers = []
+        for resource in resources:
+            if 'ResourceType' not in resource or 'ResourceIdentifier' not in resource:
+                raise ClientError(
+                    "Each resource must have 'ResourceType' and 'ResourceIdentifier'"
+                )
+            resource_identifiers.append(
+                {
+                    'ResourceType': resource['ResourceType'],
+                    'ResourceIdentifier': resource['ResourceIdentifier'],
+                }
+            )
+        params['Resources'] = resource_identifiers
+
+    # Call the API
+    try:
+        response = cfn_client.create_generated_template(**params)
+        return {
+            'status': 'INITIATED',
+            'template_id': response['GeneratedTemplateId'],
+            'message': 'Template generation initiated. Use the template_id to check status.',
+        }
+    except Exception as e:
+        raise handle_aws_api_error(e)
+
+
+async def _handle_existing_template(
+    cfn_client, template_id: str, save_to_file: Optional[str], output_format: str = 'YAML'
+) -> Dict:
+    """Handle an existing template generation process - check status or retrieve template.
+
+    Args:
+        cfn_client: Boto3 CloudFormation client
+        template_id: ID of the template generation process
+        save_to_file: Path to save the generated template to a file
+        output_format: Format of generated template. Either JSON or YAML
+
+    Returns:
+        A dictionary containing information about the template generation process or the generated template
+    """
+    # Check the status of the template generation process
+    try:
+        status_response = cfn_client.describe_generated_template(GeneratedTemplateName=template_id)
+
+        status = status_response['Status']
+
+        # Return status information if the template is not yet complete
+        if status != 'COMPLETE':
+            return {
+                'status': status,
+                'template_id': template_id,
+                'message': f'Template generation {status.lower()}.',
+            }
+
+        # If the template is complete, retrieve it
+        template_response = cfn_client.get_generated_template(
+            GeneratedTemplateName=template_id, Format=output_format
+        )
+
+        template_content = template_response['TemplateBody']
+        resources = status_response.get('ResourceIdentifiers', [])
+
+        # Save the template to a file if requested
+        file_path = None
+        if save_to_file:
+            try:
+                # Ensure the directory exists
+                os.makedirs(os.path.dirname(os.path.abspath(save_to_file)), exist_ok=True)
+
+                # Write the template to the file
+                with open(save_to_file, 'w') as f:
+                    f.write(template_content)
+                file_path = save_to_file
+            except Exception as e:
+                raise ClientError(f'Failed to save template to file: {str(e)}')
+
+        # Return the template and related information
+        result = {
+            'status': 'COMPLETED',
+            'template_id': template_id,
+            'template': template_content,
+            'resources': resources,
+            'message': 'Template generation completed.',
+        }
+
+        if file_path:
+            result['file_path'] = file_path
+
+        return result
+
+    except Exception as e:
+        raise handle_aws_api_error(e)

awslabs/ccapi_mcp_server/impl/__init__.py

@@ -0,0 +1,13 @@
+# 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.

awslabs/ccapi_mcp_server/impl/tools/__init__.py

@@ -0,0 +1,13 @@
+# 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.