awslabs.finch-mcp-server 0.1.1__py3-none-any.whl

awslabs/finch_mcp_server/utils/common.py

@@ -0,0 +1,167 @@
+"""Common utility functions for the Finch MCP server.
+
+This module provides shared utility functions used across the Finch MCP server,
+including command execution and result formatting.
+
+Note: These tools are intended for development and prototyping purposes only
+and are not meant for production use cases.
+"""
+
+import os
+import re
+import subprocess
+import sys
+from loguru import logger
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+def get_dangerous_patterns() -> List[str]:
+    """Get a list of dangerous patterns for command injection detection.
+
+    Returns:
+        List of dangerous patterns to check for
+
+    """
+    # Dangerous patterns that could indicate command injection attempts
+    # Separated by platform for better organization and maintainability
+    patterns = [
+        '|',
+        ';',
+        '&',
+        '&&',
+        '||',  # Command chaining
+        '>',
+        '>>',
+        '<',  # Redirection
+        '`',
+        '$(',  # Command substitution
+        '--',  # Double dash options
+        '/bin/',
+        '/usr/bin/',  # Path references
+        '../',
+        './',  # Directory traversal
+        # Unix/Linux specific dangerous patterns
+        'sudo',  # Privilege escalation
+        'chmod',
+        'chown',  # File permission changes
+        'su',  # Switch user
+        'bash',
+        'sh',
+        'zsh',  # Shell execution
+        'curl',
+        'wget',  # Network access
+        'ssh',
+        'scp',  # Remote access
+        'eval',  # Command evaluation
+        'source',  # Script sourcing
+        # Windows specific dangerous patterns
+        'cmd',
+        'powershell',
+        'pwsh',  # Command shells
+        'net',  # Network commands
+        'reg',  # Registry access
+        'runas',  # Privilege escalation
+        'del',
+        'rmdir',  # File deletion
+        'taskkill',  # Process termination
+        'sc',  # Service control
+        'schtasks',  # Scheduled tasks
+        'wmic',  # WMI commands
+        '%SYSTEMROOT%',
+        '%WINDIR%',  # System directories
+        '.bat',
+        '.cmd',
+        '.ps1',  # Script files
+    ]
+    return patterns
+
+
+def execute_command(command: list, env=None) -> subprocess.CompletedProcess:
+    """Execute a command and return the result.
+
+    This is a utility function that handles the execution of CLI commands.
+    It sets up the proper environment variables (particularly HOME) and captures
+    both stdout and stderr output from the command.
+
+    Args:
+        command: List of command parts to execute (e.g., ['finch', 'vm', 'status'])
+               Note: Currently only 'finch' commands are allowed for security reasons.
+        env: Optional environment variables dictionary. If None, uses a copy of the
+             current environment with HOME set to the user's home directory.
+
+    Returns:
+        CompletedProcess object with command execution results, containing:
+        - returncode: The exit code of the command (0 typically means success)
+        - stdout: Standard output as text
+        - stderr: Standard error as text
+
+    Raises:
+        ValueError: If the command is not a finch command (doesn't start with 'finch')
+                   or if dangerous patterns are detected in the command
+
+    """
+    if env is None:
+        env = os.environ.copy()
+        path = Path('~')
+        home_path = str(Path('~').expanduser())
+
+        if sys.platform == 'win32':
+            drive, path = os.path.splitdrive(home_path)
+            env['HOMEDRIVE'] = drive
+            env['HOMEPATH'] = path
+        else:
+            env['HOME'] = str(home_path)
+
+    # Security check: Only allow finch commands
+    if not command or command[0] != 'finch':
+        error_msg = f'Security violation: Only finch commands are allowed. Received: {command}'
+        logger.error(error_msg)
+        raise ValueError(error_msg)
+
+    dangerous_patterns = get_dangerous_patterns()
+    logger.debug(f'Checking for {len(dangerous_patterns)} dangerous patterns')
+
+    for pattern in dangerous_patterns:
+        for part in command:
+            escaped_pattern = re.escape(pattern)
+            regex_pattern = r'^' + escaped_pattern + r'$'
+
+            if re.search(regex_pattern, part):
+                error_msg = f'Security violation: Potentially dangerous pattern "{pattern}" detected in command: {part}'
+                logger.error(error_msg)
+                raise ValueError(error_msg)
+
+    result = subprocess.run(command, capture_output=True, text=True, env=env)
+    cmd_str = ' '.join(command)
+    logger.debug(f'Command executed: {cmd_str}')
+    logger.debug(f'Return code: {result.returncode}')
+    if result.stdout:
+        logger.debug(f'STDOUT: {result.stdout}')
+    if result.stderr:
+        logger.debug(f'STDERR: {result.stderr}')
+
+    return result
+
+
+def format_result(status: str, message: str) -> Dict[str, Any]:
+    """Format a result dictionary with status and message.
+
+    This utility function creates a standardized response format used by
+    all the MCP tools. It ensures consistent response structure.
+
+    Args:
+        status: Status code string. Common values include:
+               - "success": Operation completed successfully
+               - "error": Operation failed
+               - "warn": Operation completed with warnings
+               - "info": Informational status
+               - "unknown": Status could not be determined
+        message: Descriptive message providing details about the result
+
+    Returns:
+        Dict[str, Any]: A dictionary with 'status', 'message'
+
+    """
+    result = {'status': status, 'message': message}
+    return result

awslabs/finch_mcp_server/utils/ecr.py

@@ -0,0 +1,87 @@
+"""Utility functions for working with Amazon ECR repositories.
+
+This module provides functions to check if an ECR repository exists and create it if needed.
+
+Note: These tools are intended for development and prototyping purposes only and are not meant
+for production use cases.
+"""
+
+import boto3
+from ..consts import STATUS_ERROR, STATUS_SUCCESS
+from .common import format_result
+from botocore.exceptions import ClientError
+from loguru import logger
+from typing import Dict, Optional
+
+
+def create_ecr_repository(
+    repository_name: str,
+    region: Optional[str] = None,
+) -> Dict[str, str]:
+    """Check if an ECR repository exists and create it if it doesn't.
+
+    This function first checks if the specified ECR repository exists using boto3.
+    If the repository doesn't exist, it creates a new one with the given name.
+
+    Args:
+        repository_name: The name of the repository to check or create in ECR
+        region: AWS region for the ECR repository. If not provided, uses the default region
+                from AWS configuration
+
+    Returns:
+        Dict[str, Any]: A dictionary containing:
+            - status: "success" if the operation succeeded, "error" otherwise
+            - message: Details about the result of the operation
+
+    """
+    try:
+        ecr_client = boto3.client('ecr', region_name=region) if region else boto3.client('ecr')
+
+        try:
+            response = ecr_client.describe_repositories(repositoryNames=[repository_name])
+
+            if 'repositories' in response and len(response['repositories']) > 0:
+                repository = response['repositories'][0]
+                repository_uri = repository.get('repositoryUri', '')
+
+                logger.debug(
+                    f"ECR repository '{repository_name}' already exists with URI: {repository_uri}"
+                )
+                return format_result(
+                    STATUS_SUCCESS,
+                    f"ECR repository '{repository_name}' already exists.",
+                )
+        except ClientError as e:
+            error_code = e.response.get('Error', {}).get('Code')
+
+            if error_code != 'RepositoryNotFoundException':
+                return format_result(
+                    STATUS_ERROR,
+                    f'Error checking ECR repository: {str(e)}',
+                )
+
+        response = ecr_client.create_repository(
+            repositoryName=repository_name,
+            imageScanningConfiguration={'scanOnPush': True},
+            imageTagMutability='IMMUTABLE',
+        )
+
+        repository = response.get('repository', {})
+        repository_uri = repository.get('repositoryUri', '')
+
+        logger.debug(f"Created ECR repository '{repository_name}' with URI: {repository_uri}")
+        return format_result(
+            STATUS_SUCCESS,
+            f"Successfully created ECR repository '{repository_name}' with URI: {repository_uri}.",
+        )
+
+    except ClientError as e:
+        return format_result(
+            STATUS_ERROR,
+            f"Failed to create ECR repository '{repository_name}': {str(e)}",
+        )
+    except Exception as e:
+        return format_result(
+            STATUS_ERROR,
+            f"Unexpected error creating ECR repository '{repository_name}': {str(e)}",
+        )

awslabs/finch_mcp_server/utils/push.py

@@ -0,0 +1,125 @@
+"""Utility functions for pushing container images to repositories.
+
+This module provides functions to push container images to repositories,
+including Amazon ECR, and handle image tagging with hash values.
+
+Note: These tools are intended for development and prototyping purposes only
+and are not meant for production use cases.
+"""
+
+import re
+from ..consts import ECR_REFERENCE_PATTERN, REGION_PATTERN, STATUS_ERROR, STATUS_SUCCESS
+from .common import execute_command, format_result
+from loguru import logger
+from typing import Dict
+
+
+def is_ecr_repository(repository: str) -> bool:
+    """Validate if the provided repository URL is an ECR repository.
+
+    ECR repository URLs typically follow the pattern:
+    <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<repository_name>:<tag>
+
+    Args:
+        repository: The repository URL to validate
+
+    Returns:
+        bool: True if the repository is an ECR repository, False otherwise
+
+    """
+    match = re.search(ECR_REFERENCE_PATTERN, repository)
+    if not match:
+        return False
+
+    # Validate that the region is a valid AWS region format (e.g., us-west-2, eu-central-1)
+    region = match.group(3)
+    return bool(re.match(REGION_PATTERN, region))
+
+
+def get_image_short_hash(image: str) -> tuple[Dict[str, str], str]:
+    """Get the short hash (digest) of a container image.
+
+    Args:
+        image: The image name to get the hash for
+
+    Returns:
+        A tuple containing:
+        - Dict with status and message
+        - The short hash as a string (empty string if operation failed)
+
+    """
+    inspect_result = execute_command(['finch', 'image', 'inspect', image])
+
+    if inspect_result.returncode != 0:
+        # Log stderr for debugging
+        logger.debug(f'STDERR from image inspect: {inspect_result.stderr}')
+        error_result = format_result(
+            STATUS_ERROR,
+            f'Failed to get hash for image {image}: {inspect_result.stderr}',
+        )
+        return error_result, ''
+
+    hash_match = re.search(r'"Id":\s*"(sha256:[a-f0-9]+)"', inspect_result.stdout)
+
+    if not hash_match:
+        error_result = format_result(
+            STATUS_ERROR, f'Could not find hash in image inspect output for {image}'
+        )
+        return error_result, ''
+
+    image_hash = hash_match.group(1)
+    short_hash = image_hash[7:19] if image_hash.startswith('sha256:') else image_hash[:12]
+    logger.debug(f'Retrieved hash for image {image}: {image_hash}')
+    return format_result(
+        STATUS_SUCCESS,
+        f'Successfully retrieved hash for image {image}',
+    ), short_hash
+
+
+def push_image(image: str) -> Dict[str, str]:
+    """Push an image to a repository, replacing the tag with the image hash.
+
+    Args:
+        image: The image to push
+
+    Returns:
+        Result of the push task
+
+    """
+    hash_result, short_hash = get_image_short_hash(image)
+
+    if hash_result['status'] != STATUS_SUCCESS:
+        return hash_result
+
+    tag_separator_index = image.rfind(':')
+    if tag_separator_index > 0:
+        repository = image[:tag_separator_index]
+    else:
+        repository = image
+
+    hash_tagged_image = f'{repository}:{short_hash}'
+
+    tag_result = execute_command(['finch', 'image', 'tag', image, hash_tagged_image])
+
+    if tag_result.returncode != 0:
+        # Log stderr for debugging
+        logger.debug(f'STDERR from image tag: {tag_result.stderr}')
+        return format_result(
+            STATUS_ERROR,
+            f'Failed to tag image with hash: {tag_result.stderr}',
+        )
+
+    push_result = execute_command(['finch', 'image', 'push', hash_tagged_image])
+
+    if push_result.returncode == 0:
+        logger.debug(f'STDOUT from image push: {push_result.stdout}')
+        return format_result(
+            STATUS_SUCCESS,
+            f'Successfully pushed image {hash_tagged_image} (original: {image}).',
+        )
+    else:
+        logger.debug(f'STDERR from image push: {push_result.stderr}')
+        return format_result(
+            STATUS_ERROR,
+            f'Failed to push image {hash_tagged_image}: {push_result.stderr}',
+        )