awslabs.terraform-mcp-server 0.0.11__py3-none-any.whl → 0.0.12__py3-none-any.whl

awslabs/terraform_mcp_server/impl/tools/__init__.py

@@ -2,6 +2,7 @@
 
 from .search_user_provided_module import search_user_provided_module_impl
 from .execute_terraform_command import execute_terraform_command_impl
+from .execute_terragrunt_command import execute_terragrunt_command_impl
 from .search_aws_provider_docs import search_aws_provider_docs_impl
 from .search_awscc_provider_docs import search_awscc_provider_docs_impl
 from .search_specific_aws_ia_modules import search_specific_aws_ia_modules_impl
@@ -10,6 +11,7 @@ from .run_checkov_scan import run_checkov_scan_impl
 __all__ = [
     'search_user_provided_module_impl',
     'execute_terraform_command_impl',
+    'execute_terragrunt_command_impl',
     'search_aws_provider_docs_impl',
     'search_awscc_provider_docs_impl',
     'search_specific_aws_ia_modules_impl',

awslabs/terraform_mcp_server/impl/tools/execute_terragrunt_command.py

@@ -0,0 +1,303 @@
+"""Implementation of Terragrunt command execution tool."""
+
+import json
+import os
+import re
+import subprocess
+from awslabs.terraform_mcp_server.impl.tools.utils import get_dangerous_patterns
+from awslabs.terraform_mcp_server.models import (
+    TerragruntExecutionRequest,
+    TerragruntExecutionResult,
+)
+from loguru import logger
+
+
+async def execute_terragrunt_command_impl(
+    request: TerragruntExecutionRequest,
+) -> TerragruntExecutionResult:
+    """Execute Terragrunt workflow commands against an AWS account.
+
+    This tool runs Terragrunt commands (init, plan, validate, apply, destroy, run-all) in the
+    specified working directory, with optional variables and region settings.
+
+    Parameters:
+        request: Details about the Terragrunt command to execute
+
+    Returns:
+        A TerragruntExecutionResult object containing command output and status
+    """
+    logger.info(f"Executing 'terragrunt {request.command}' in {request.working_directory}")
+
+    # Helper function to clean output text
+    def clean_output_text(text: str) -> str:
+        """Clean output text by removing or replacing problematic Unicode characters.
+
+        Args:
+            text: The text to clean
+
+        Returns:
+            Cleaned text with ASCII-friendly replacements
+        """
+        if not text:
+            return text
+
+        # First remove ANSI escape sequences (color codes, cursor movement)
+        ansi_escape = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])')
+        text = ansi_escape.sub('', text)
+
+        # Remove C0 and C1 control characters (except common whitespace)
+        control_chars = re.compile(r'[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F-\x9F]')
+        text = control_chars.sub('', text)
+
+        # Replace HTML entities
+        html_entities = {
+            '->': '->',  # Replace HTML arrow
+            '&lt;': '<',  # Less than
+            '&gt;': '>',  # Greater than
+            '&amp;': '&',  # Ampersand
+        }
+        for entity, replacement in html_entities.items():
+            text = text.replace(entity, replacement)
+
+        # Replace box-drawing and other special Unicode characters with ASCII equivalents
+        unicode_chars = {
+            '\u2500': '-',  # Horizontal line
+            '\u2502': '|',  # Vertical line
+            '\u2514': '+',  # Up and right
+            '\u2518': '+',  # Up and left
+            '\u2551': '|',  # Double vertical
+            '\u2550': '-',  # Double horizontal
+            '\u2554': '+',  # Double down and right
+            '\u2557': '+',  # Double down and left
+            '\u255a': '+',  # Double up and right
+            '\u255d': '+',  # Double up and left
+            '\u256c': '+',  # Double cross
+            '\u2588': '#',  # Full block
+            '\u25cf': '*',  # Black circle
+            '\u2574': '-',  # Left box drawing
+            '\u2576': '-',  # Right box drawing
+            '\u2577': '|',  # Down box drawing
+            '\u2575': '|',  # Up box drawing
+        }
+        for char, replacement in unicode_chars.items():
+            text = text.replace(char, replacement)
+
+        return text
+
+    # Set environment variables for AWS region if provided
+    env = os.environ.copy()
+    if request.aws_region:
+        env['AWS_REGION'] = request.aws_region
+
+    # Security check for command injection
+    allowed_commands = ['init', 'plan', 'validate', 'apply', 'destroy', 'output', 'run-all']
+    if request.command not in allowed_commands:
+        logger.error(f'Invalid Terragrunt command: {request.command}')
+        return TerragruntExecutionResult(
+            command=f'terragrunt {request.command}',
+            status='error',
+            error_message=f'Invalid Terragrunt command: {request.command}. Allowed commands are: {", ".join(allowed_commands)}',
+            working_directory=request.working_directory,
+            outputs=None,
+            affected_dirs=None,
+        )
+
+    # Validate that terragrunt_config is not used with run-all
+    if request.terragrunt_config and request.command == 'run-all':
+        logger.error('terragrunt_config cannot be used with run-all command')
+        return TerragruntExecutionResult(
+            command=f'terragrunt {request.command}',
+            status='error',
+            error_message='Invalid configuration: --terragrunt-config cannot be used with run-all command',
+            working_directory=request.working_directory,
+            outputs=None,
+            affected_dirs=None,
+        )
+
+    # Check for potentially dangerous characters or command injection attempts
+    dangerous_patterns = get_dangerous_patterns()
+    logger.debug(f'Checking for {len(dangerous_patterns)} dangerous patterns')
+
+    for pattern in dangerous_patterns:
+        if request.variables:
+            # Check if the pattern is in any of the variable values
+            for var_name, var_value in request.variables.items():
+                if pattern in str(var_value) or pattern in str(var_name):
+                    logger.error(
+                        f'Potentially dangerous pattern detected in variable {var_name}: {pattern}'
+                    )
+                    return TerragruntExecutionResult(
+                        command=f'terragrunt {request.command}',
+                        status='error',
+                        error_message=f"Security violation: Potentially dangerous pattern '{pattern}' detected in variable '{var_name}'",
+                        working_directory=request.working_directory,
+                        outputs=None,
+                        affected_dirs=None,
+                    )
+
+        # Check terragrunt_config for dangerous patterns
+        if request.terragrunt_config and pattern in str(request.terragrunt_config):
+            logger.error(f'Potentially dangerous pattern detected in terragrunt_config: {pattern}')
+            return TerragruntExecutionResult(
+                command=f'terragrunt {request.command}',
+                status='error',
+                error_message=f"Security violation: Potentially dangerous pattern '{pattern}' detected in terragrunt_config",
+                working_directory=request.working_directory,
+                outputs=None,
+                affected_dirs=None,
+            )
+
+        # Also check include_dirs and exclude_dirs for dangerous patterns
+        if request.include_dirs:
+            for dir_path in request.include_dirs:
+                if pattern in str(dir_path):
+                    logger.error(
+                        f'Potentially dangerous pattern detected in include_dirs: {pattern}'
+                    )
+                    return TerragruntExecutionResult(
+                        command=f'terragrunt {request.command}',
+                        status='error',
+                        error_message=f"Security violation: Potentially dangerous pattern '{pattern}' detected in include_dirs",
+                        working_directory=request.working_directory,
+                        outputs=None,
+                        affected_dirs=None,
+                    )
+
+        if request.exclude_dirs:
+            for dir_path in request.exclude_dirs:
+                if pattern in str(dir_path):
+                    logger.error(
+                        f'Potentially dangerous pattern detected in exclude_dirs: {pattern}'
+                    )
+                    return TerragruntExecutionResult(
+                        command=f'terragrunt {request.command}',
+                        status='error',
+                        error_message=f"Security violation: Potentially dangerous pattern '{pattern}' detected in exclude_dirs",
+                        working_directory=request.working_directory,
+                        outputs=None,
+                        affected_dirs=None,
+                    )
+
+    # Build the command
+    base_cmd = ['terragrunt']
+
+    # Handle run-all command differently
+    if request.command == 'run-all':
+        base_cmd.append('run-all')
+        # The actual terraform command becomes the first argument
+        # Default to 'apply' if not specified in the command
+        base_cmd.append('apply')
+    else:
+        base_cmd.append(request.command)
+
+    # Add auto-approve flag for apply and destroy commands to make them non-interactive
+    if request.command in ['apply', 'destroy'] or (request.command == 'run-all'):
+        logger.info(f'Adding -auto-approve flag to {request.command} command')
+        base_cmd.append('-auto-approve')
+
+    # Add terragrunt_config if specified and not using run-all
+    if request.terragrunt_config:
+        logger.info(f'Using custom terragrunt config file: {request.terragrunt_config}')
+        base_cmd.append(f'--terragrunt-config={request.terragrunt_config}')
+
+    # Add variables only for commands that accept them (plan, apply, destroy, output)
+    if request.command in ['plan', 'apply', 'destroy', 'output', 'run-all'] and request.variables:
+        logger.info(f'Adding {len(request.variables)} variables to {request.command} command')
+        for key, value in request.variables.items():
+            base_cmd.append(f'-var={key}={value}')
+
+    # Add include-dirs if specified
+    if request.include_dirs and request.command == 'run-all':
+        for dir_path in request.include_dirs:
+            base_cmd.append(f'--queue-include-dir={dir_path}')
+
+    # Add exclude-dirs if specified
+    if request.exclude_dirs and request.command == 'run-all':
+        for dir_path in request.exclude_dirs:
+            base_cmd.append(f'--queue-exclude-dir={dir_path}')
+
+    # Execute command
+    try:
+        process = subprocess.run(
+            base_cmd, cwd=request.working_directory, capture_output=True, text=True, env=env
+        )
+
+        # Prepare the result
+        stdout = process.stdout
+        stderr = process.stderr if process.stderr else ''
+
+        # Clean output text if requested
+        if request.strip_ansi:
+            logger.debug('Cleaning command output text (ANSI codes and control characters)')
+            stdout = clean_output_text(stdout)
+            stderr = clean_output_text(stderr)
+
+        # Extract affected directories for run-all command
+        affected_dirs = None
+        if request.command == 'run-all':
+            affected_dirs = []
+            # Look for directory paths in the output
+            dir_pattern = re.compile(r'Module at\s+"([^"]+)"')
+            for match in dir_pattern.finditer(stdout):
+                affected_dirs.append(match.group(1))
+
+        result = {
+            'command': f'terragrunt {request.command}',
+            'status': 'success' if process.returncode == 0 else 'error',
+            'return_code': process.returncode,
+            'stdout': stdout,
+            'stderr': stderr,
+            'working_directory': request.working_directory,
+            'outputs': None,
+            'affected_dirs': affected_dirs,
+        }
+
+        # Get outputs if this was a successful apply or output command
+        if (
+            request.command in ['apply', 'output'] or (request.command == 'run-all')
+        ) and process.returncode == 0:
+            try:
+                logger.info('Getting Terragrunt outputs')
+                output_process = subprocess.run(
+                    ['terragrunt', 'output', '-json'],
+                    cwd=request.working_directory,
+                    capture_output=True,
+                    text=True,
+                    env=env,
+                )
+
+                if output_process.returncode == 0 and output_process.stdout:
+                    # Get output and clean it if needed
+                    output_stdout = output_process.stdout
+                    if request.strip_ansi:
+                        output_stdout = clean_output_text(output_stdout)
+
+                    # Parse the JSON output
+                    raw_outputs = json.loads(output_stdout)
+
+                    # Process outputs to extract values from complex structure
+                    processed_outputs = {}
+                    for key, value in raw_outputs.items():
+                        # Terraform outputs in JSON format have a nested structure
+                        # with 'value', 'type', and sometimes 'sensitive'
+                        if isinstance(value, dict) and 'value' in value:
+                            processed_outputs[key] = value['value']
+                        else:
+                            processed_outputs[key] = value
+
+                    result['outputs'] = processed_outputs
+                    logger.info(f'Extracted {len(processed_outputs)} Terragrunt outputs')
+            except Exception as e:
+                logger.warning(f'Failed to get Terragrunt outputs: {e}')
+
+        # Return the output
+        return TerragruntExecutionResult(**result)
+    except Exception as e:
+        return TerragruntExecutionResult(
+            command=f'terragrunt {request.command}',
+            status='error',
+            error_message=str(e),
+            working_directory=request.working_directory,
+            outputs=None,
+            affected_dirs=None,
+        )

awslabs/terraform_mcp_server/models/__init__.py

@@ -5,6 +5,8 @@ from .models import (
     SubmoduleInfo,
     TerraformExecutionRequest,
     TerraformExecutionResult,
+    TerragruntExecutionRequest,
+    TerragruntExecutionResult,
     CheckovVulnerability,
     CheckovScanRequest,
     CheckovScanResult,
@@ -21,6 +23,8 @@ __all__ = [
     'SubmoduleInfo',
     'TerraformExecutionRequest',
     'TerraformExecutionResult',
+    'TerragruntExecutionRequest',
+    'TerragruntExecutionResult',
     'CheckovVulnerability',
     'CheckovScanRequest',
     'CheckovScanResult',

awslabs/terraform_mcp_server/models/models.py

@@ -302,3 +302,66 @@ class SearchUserProvidedModuleResult(BaseModel):
     outputs: List[TerraformOutput] = Field([], description='Outputs provided by the module')
     readme_content: Optional[str] = Field(None, description='README content of the module')
     error_message: Optional[str] = Field(None, description='Error message if execution failed')
+
+
+class TerragruntExecutionRequest(BaseModel):
+    """Request model for Terragrunt command execution with parameters.
+
+    Attributes:
+        command: The Terragrunt command to execute (init, plan, validate, apply, destroy, etc.).
+        working_directory: Directory containing Terragrunt configuration files.
+        variables: Optional dictionary of Terraform variables to pass.
+        aws_region: Optional AWS region to use.
+        strip_ansi: Whether to strip ANSI color codes from command output.
+        include_dirs: Optional list of directories to include in a multi-module run.
+        exclude_dirs: Optional list of directories to exclude from a multi-module run.
+        run_all: Whether to run the command in all subdirectories with terragrunt.hcl files.
+    """
+
+    command: Literal['init', 'plan', 'validate', 'apply', 'destroy', 'output', 'run-all'] = Field(
+        ..., description='Terragrunt command to execute'
+    )
+    working_directory: str = Field(..., description='Directory containing Terragrunt files')
+    variables: Optional[Dict[str, str]] = Field(None, description='Terraform variables to pass')
+    aws_region: Optional[str] = Field(None, description='AWS region to use')
+    strip_ansi: bool = Field(True, description='Whether to strip ANSI color codes from output')
+    include_dirs: Optional[List[str]] = Field(
+        None, description='Directories to include in a multi-module run'
+    )
+    exclude_dirs: Optional[List[str]] = Field(
+        None, description='Directories to exclude from a multi-module run'
+    )
+    run_all: bool = Field(False, description='Run command on all modules in subdirectories')
+    terragrunt_config: Optional[str] = Field(
+        None, description='Path to a custom terragrunt config file (not valid with run-all)'
+    )
+
+
+class TerragruntExecutionResult(BaseModel):
+    """Result model for Terragrunt command execution.
+
+    Attributes:
+        command: The Terragrunt command that was executed.
+        status: Execution status (success/error).
+        return_code: The command's return code (0 for success).
+        stdout: Standard output from the Terragrunt command.
+        stderr: Standard error output from the Terragrunt command.
+        working_directory: Directory where the command was executed.
+        error_message: Optional error message if execution failed.
+        outputs: Dictionary of output values from Terragrunt (for apply command).
+        affected_dirs: List of directories affected by a run-all command.
+    """
+
+    command: str
+    status: Literal['success', 'error']
+    return_code: Optional[int] = None
+    stdout: Optional[str] = None
+    stderr: str = ''
+    working_directory: str
+    error_message: Optional[str] = None
+    outputs: Optional[Dict[str, Any]] = Field(
+        None, description='Terragrunt outputs (for apply or output command)'
+    )
+    affected_dirs: Optional[List[str]] = Field(
+        None, description='Directories affected by a run-all command'
+    )

awslabs/terraform_mcp_server/server.py

@@ -8,6 +8,7 @@ from awslabs.terraform_mcp_server.impl.resources import (
 )
 from awslabs.terraform_mcp_server.impl.tools import (
     execute_terraform_command_impl,
+    execute_terragrunt_command_impl,
     run_checkov_scan_impl,
     search_aws_provider_docs_impl,
     search_awscc_provider_docs_impl,
@@ -24,6 +25,8 @@ from awslabs.terraform_mcp_server.models import (
     TerraformAWSProviderDocsResult,
     TerraformExecutionRequest,
     TerraformExecutionResult,
+    TerragruntExecutionRequest,
+    TerragruntExecutionResult,
 )
 from awslabs.terraform_mcp_server.static import (
     AWS_TERRAFORM_BEST_PRACTICES,
@@ -84,6 +87,61 @@ async def execute_terraform_command(
     return await execute_terraform_command_impl(request)
 
 
+@mcp.tool(name='ExecuteTerragruntCommand')
+async def execute_terragrunt_command(
+    command: Literal['init', 'plan', 'validate', 'apply', 'destroy', 'output', 'run-all'] = Field(
+        ..., description='Terragrunt command to execute'
+    ),
+    working_directory: str = Field(..., description='Directory containing Terragrunt files'),
+    variables: Optional[Dict[str, str]] = Field(None, description='Terraform variables to pass'),
+    aws_region: Optional[str] = Field(None, description='AWS region to use'),
+    strip_ansi: bool = Field(True, description='Whether to strip ANSI color codes from output'),
+    include_dirs: Optional[List[str]] = Field(
+        None, description='Directories to include in a multi-module run'
+    ),
+    exclude_dirs: Optional[List[str]] = Field(
+        None, description='Directories to exclude from a multi-module run'
+    ),
+    run_all: bool = Field(False, description='Run command on all modules in subdirectories'),
+    terragrunt_config: Optional[str] = Field(
+        None, description='Path to a custom terragrunt config file (not valid with run-all)'
+    ),
+) -> TerragruntExecutionResult:
+    """Execute Terragrunt workflow commands against an AWS account.
+
+    This tool runs Terragrunt commands (init, plan, validate, apply, destroy, run-all) in the
+    specified working directory, with optional variables and region settings. Terragrunt extends
+    Terraform's functionality by providing features like remote state management, dependencies
+    between modules, and the ability to execute Terraform commands on multiple modules at once.
+
+    Parameters:
+        command: Terragrunt command to execute
+        working_directory: Directory containing Terragrunt files
+        variables: Terraform variables to pass
+        aws_region: AWS region to use
+        strip_ansi: Whether to strip ANSI color codes from output
+        include_dirs: Directories to include in a multi-module run
+        exclude_dirs: Directories to exclude from a multi-module run
+        run_all: Run command on all modules in subdirectories
+        terragrunt_config: Path to a custom terragrunt config file (not valid with run-all)
+
+    Returns:
+        A TerragruntExecutionResult object containing command output and status
+    """
+    request = TerragruntExecutionRequest(
+        command=command,
+        working_directory=working_directory,
+        variables=variables,
+        aws_region=aws_region,
+        strip_ansi=strip_ansi,
+        include_dirs=include_dirs,
+        exclude_dirs=exclude_dirs,
+        run_all=run_all,
+        terragrunt_config=terragrunt_config,
+    )
+    return await execute_terragrunt_command_impl(request)
+
+
 @mcp.tool(name='SearchAwsProviderDocs')
 async def search_aws_provider_docs(
     asset_name: str = Field(

awslabs/terraform_mcp_server/static/MCP_INSTRUCTIONS.md

@@ -1,8 +1,6 @@
 # Terraform MCP Server Instructions
 
-## Overview
-
-MCP server specialized in AWS cloud infrastructure provided through Terraform. I help you create, understand, optimize, and execute Terraform configurations for AWS using security-focused development practices.
+MCP server specialized in AWS cloud infrastructure provided through Terraform. I help you create, understand, optimize, and execute Terraform Or Terragrunt configurations for AWS using security-focused development practices.
 
 ## How to Use This Server (Required Workflow)
 
@@ -80,7 +78,10 @@ When implementing specific AWS resources (only after confirming no suitable AWS-
 1. `ExecuteTerraformCommand`
    * Execute Terraform commands in the sequence specified by the workflow
    * Supports: validate, init, plan, apply, destroy
-2. `RunCheckovScan`
+2. `ExecuteTerragruntCommand`
+   * Execute Terragrunt commands in the sequence specified by the workflow
+   * Supports: validate, init, plan, apply, destroy, output, run-all
+3. `RunCheckovScan`
    * Run after validation passes, before initialization
    * Identifies security and compliance issues
 
@@ -103,6 +104,8 @@ The AWSCC provider (Cloud Control API-based) offers:
 - "Find documentation for awscc_lambda_function resource" (specifically AWSCC)
 - "Find documentation for aws_lambda_function resource" (specifically AWS)
 - "Execute terraform plan in my ./infrastructure directory"
+- "Execute terragrunt plan in my ./infrastructure directory"
+- "Execute terragrunt run-all plan in my ./infrastructure directory"
 - "How can I use the AWS Bedrock module to create a RAG application?"
 - "Show me details about the AWS-IA Bedrock Terraform module"
 - "Compare the four specific AWS-IA modules for generative AI applications"
@@ -115,6 +118,10 @@ The AWSCC provider (Cloud Control API-based) offers:
 - "Use the terraform-aws-modules/vpc/aws module to implement a VPC"
 - "Search for the hashicorp/consul/aws module and explain how to use it"
 - "What variables are required for the terraform-aws-modules/eks/aws module?"
+- "I have a multi-environment Terragrunt project. How can I run apply on all modules at once?"
+- "Execute terragrunt run-all apply in my ./infrastructure directory"
+- "How to construct a well-formed terragrunt hierarchy folder structure"
+- "Generate common inputs for all environments using generate in Terragrunt"
 
 ## Best Practices
 
@@ -129,5 +136,7 @@ When interacting with this server:
 7. **Be specific** about your requirements and constraints
 8. **Specify AWS region** when relevant to your infrastructure needs
 9. **Provide context** about your architecture and use case
-10. **For Terraform execution**, ensure the working directory exists and contains valid Terraform files
+10. **For Terraform/Terragrunt execution**, ensure the working directory exists and contains valid Terraform/Terragrunt files
 11. **Review generated code** carefully before applying changes to your infrastructure
+12. When using **Terragrunt**, leverage DRY features—locals, dependencies, and generate blocks—to compose multi-env stacks.
+13. **Organize repos with clear folder hierarchies** (e.g. live/, modules/) and consistent naming so both Terraform and Terragrunt code is discoverable.

awslabs/terraform_mcp_server/static/TERRAFORM_WORKFLOW_GUIDE.md

@@ -10,6 +10,7 @@ You have access to specialized tools and resources through this MCP server that
 1. Reference this workflow consistently throughout your interactions
 2. Leverage this MCP server's capabilities rather than relying solely on your general knowledge
 3. Explain the workflow steps to users as you assist them
+4. Choose the appropriate path—Terraform or Terragrunt—based on the user's project structure and tooling preferences
 
 ## Benefits to Emphasize
 When following this workflow and using these tools, you provide several advantages to users:
@@ -18,6 +19,7 @@ When following this workflow and using these tools, you provide several advantag
 - Identification of security vulnerabilities before deployment
 - Adherence to AWS best practices
 - Validation that code will work correctly when deployed
+- Support for layered, DRY configurations through Terragrunt when modularization and environment inheritance are needed
 
 By following this workflow guide and leveraging the provided tools and resources, you'll deliver consistent, high-quality assistance for Terraform development on AWS, helping users create infrastructure code that is syntactically valid, secure, and ready for review before deployment.
 
@@ -25,32 +27,33 @@ By following this workflow guide and leveraging the provided tools and resources
 
 ``` mermaid
 flowchart TD
-    start([Start Development]) --> edit[Edit Terraform Code]
+    start([Start Development]) --> detectConfig[Identify Project Type:\nTerraform or Terragrunt]
+
+    detectConfig --> edit[Edit Code]
 
     %% Initial Code Validation
-    edit --> tfValidate[Run terraform validate\nvia ExecuteTerraformCommand]
+    edit --> validate[Run Validation:\nterraform validate or terragrunt validate\nvia ExecuteTerraformCommand]
 
     %% Validation Flow
-    tfValidate -->|Passes| checkovScan[Run Security Scan\nvia RunCheckovScan]
-    tfValidate -->|Fails| fixValidation[Fix Configuration\nIssues]
+    validate -->|Passes| checkovScan[Run Security Scan\nvia RunCheckovScan]
+    validate -->|Fails| fixValidation[Fix Configuration\nIssues]
     fixValidation --> edit
 
     %% Checkov Flow
-    checkovScan -->|No Issues| tfInit[Run terraform init\nvia ExecuteTerraformCommand]
+    checkovScan -->|No Issues| initCmd[Run Init Command:\nterraform init or terragrunt init\nvia ExecuteTerraformCommand]
     checkovScan -->|Finds Issues| reviewIssues[Review Security\nIssues]
 
     reviewIssues --> manualFix[Fix Security Issues]
-
     manualFix --> edit
 
-    %% Terraform Init & Plan (No Apply)
-    tfInit -->|Success| tfPlan[Run terraform plan\nvia ExecuteTerraformCommand]
-    tfInit -->|Fails| fixInit[Fix Provider/Module\nIssues]
+    %% Init & Plan (No Apply)
+    initCmd -->|Success| planCmd[Run Plan Command:\nterraform plan or terragrunt plan\nvia ExecuteTerraformCommand]
+    initCmd -->|Fails| fixInit[Fix Provider/Module\nIssues]
     fixInit --> edit
 
     %% Final Review & Handoff to Developer
-    tfPlan -->|Plan Generated| reviewPlan[Review Planned Changes]
-    tfPlan -->|Issues Detected| edit
+    planCmd -->|Plan Generated| reviewPlan[Review Planned Changes]
+    planCmd -->|Issues Detected| edit
 
     reviewPlan --> codeReady[Valid, Secure Code Ready\nfor Developer Review]
 
@@ -72,17 +75,20 @@ flowchart TD
     class reviewIssues,reviewPlan warning
     class fixValidation,fixInit,manualFix error
     class edit process
-    class newChanges decision
-    class tfValidate,checkovScan,tfInit,tfPlan mcptool
+    class detectConfig,newChanges decision
+    class validate,checkovScan,initCmd,planCmd mcptool
     class handoff handoff
 ```
 
-1. Edit Terraform Code
-    - Write or modify Terraform configuration files for AWS resources
+1. Edit Terraform or Terragrunt Code
+    - Write or modify Terraform or Terragrunt configuration files for AWS resources
     - When writing code, follow this priority order:
         * FIRST check for specialized AWS-IA modules (`SearchSpecificAwsIaModules` tool)
         * If no suitable module exists, THEN use AWSCC provider resources (`SearchAwsccProviderDocs` tool)
         * ONLY fall back to traditional AWS provider (`SearchAwsProviderDocs` tool) when the above options don't meet requirements
+    - When using Terragrunt:
+        * Ensure that the terraform block references the correct module or configuration directory
+        * Use Terragrunt features such as locals, dependencies, generate, and inputs to manage DRY configuration
     - When a user provides a specific Terraform Registry module to use:
         * Use the `SearchUserProvidedModule` tool to analyze the module
         * Extract input variables, output variables, and README content
@@ -92,6 +98,7 @@ flowchart TD
         - Resources
             - *terraform_development_workflow* to consult this guide and to use it to ensure you're following the development workflow correctly
             - *terraform_aws_best_practices* for AWS best practices about security, code base structure and organization, AWS Provider version management, and usage of community modules
+            - *terragrunt_aws_best_practices* for AWS best practices about security, code base structure and organization, AWS Provider version management, and usage of community modules
             - *terraform_awscc_provider_resources_listing* for available AWS Cloud Control API resources
             - *terraform_aws_provider_resources_listing* for available AWS resources
         - Tools
@@ -100,10 +107,15 @@ flowchart TD
             - *SearchAwsccProviderDocs* tool to look up specific Cloud Control API resources
             - *SearchAwsProviderDocs* tool to look up specific resource documentation
 2. Validate Code
-    - Tool: *ExecuteTerraformCommand* with command="validate"
-        - Checks syntax and configuration validity without accessing AWS
-        - Identifies syntax errors, invalid resource configurations, and reference issues
-        - Example: ExecuteTerraformCommand(TerraformExecutionRequest(command="validate", working_directory="./my_project"))
+    - Tools:
+      - *ExecuteTerraformCommand* with command="validate"
+      - *ExecuteTerragruntCommand* with command="validate"
+    - Purpose:
+      - Checks syntax and configuration validity without accessing AWS
+      - Identifies syntax errors, invalid resource configurations, and reference issues
+    - Examples:
+      - ExecuteTerraformCommand(TerraformExecutionRequest(command="validate", working_directory="./my_project"))
+      - ExecuteTerragruntCommand(TerragruntExecutionRequest(command="validate", working_directory="./my_project"))
 3. Run Security Scan
     - Tool: *RunCheckovScan*
         - Scans code for security misconfigurations, compliance issues, and AWS best practice violations
@@ -113,14 +125,24 @@ flowchart TD
         - Edit the code to address security issues identified by the scan
         - Consult *terraform_aws_best_practices* resource for guidance
 5. Initialize Working Directory
-    - Tool: *ExecuteTerraformCommand* with command="init"
+    - Tools:
+      - Terraform: *ExecuteTerraformCommand* with command="init"
+      - Terragrunt: *ExecuteTerragruntCommand* with command="init"
+    - Purpose:
         - Downloads provider plugins and sets up modules
-        - Example: ExecuteTerraformCommand(TerraformExecutionRequest(command="init", working_directory="./my_project"))
+    - Example:
+      - ExecuteTerraformCommand(TerraformExecutionRequest(command="init", working_directory="./my_project"))
+      - ExecuteTerragruntCommand(TerragruntExecutionRequest(command="init", working_directory="./my_project"))
 6. Plan Changes
-    - Tool: *ExecuteTerraformCommand* with command="plan"
+    - Tools:
+      - *ExecuteTerraformCommand* with command="plan"
+      - *ExecuteTerragruntCommand* with command="plan"
+    - Purpose:
         - Creates an execution plan showing what changes would be made (without applying)
         - Verifies that the configuration is deployable
-        - Example: ExecuteTerraformCommand(TerraformExecutionRequest(command="plan", working_directory="./my_project", output_file="tfplan"))
+    - Examples:
+      - ExecuteTerraformCommand(TerraformExecutionRequest(command="plan", working_directory="./my_project", output_file="tfplan"))
+      - ExecuteTerragruntCommand(TerragruntExecutionRequest(command="plan", working_directory="./my_project", output_file="tfplan"))
 7. Review Plan & Code Ready
     - Review the plan output to ensure it reflects intended changes
     - Confirm all validation and security checks have passed
@@ -183,6 +205,110 @@ Options:
 Options:
 - `-auto-approve` - Skip interactive approval
 
+### Terragrunt Commands
+
+#### terragrunt init
+
+* Purpose: Initializes a Terragrunt working directory by preparing the underlying Terraform modules and provider plugins.
+* When to use: Before running any other commands in a new or updated Terragrunt configuration directory.
+
+Options:
+- `--terragrunt-config=PATH` - Path to the Terragrunt configuration file (default: terragrunt.hcl)
+
+```python
+ExecuteTerragruntCommand(TerragruntExecutionRequest(
+    command="init",
+    working_directory="./project_dir"
+))
+```
+
+#### terragrunt validate
+
+* Purpose: Validates the underlying Terraform configuration referenced by the Terragrunt wrapper.
+* When to use: After editing Terragrunt or Terraform configuration files, to check for syntax and reference issues.
+
+```python
+ExecuteTerragruntCommand(TerragruntExecutionRequest(
+    command="validate",
+    working_directory="./project_dir"
+))
+```
+Options:
+- `--terragrunt-config=PATH` - Path to the Terragrunt configuration file (default: `terragrunt.hcl`)
+
+#### terragrunt plan
+
+* Purpose: Creates an execution plan for infrastructure changes using the Terragrunt wrapper.
+* When to use: After validation passes, to preview changes before applying them.
+
+Options:
+- `-var 'name=value'` - Set variable (passed to Terraform)
+- `-var-file=filename` - Load variables from file (passed to Terraform)
+- `--terragrunt-config=PATH` - Path to the Terragrunt configuration file (default: `terragrunt.hcl`)
+
+```python
+ExecuteTerragruntCommand(TerragruntExecutionRequest(
+    command="plan",
+    working_directory="./project_dir",
+))
+```
+
+#### terragrunt apply
+
+* Purpose: Applies the planned changes using the Terragrunt wrapper.
+* When to use: After plan output is approved and developer chooses to proceed.
+
+>Note: This is typically executed by the developer after reviewing code and plan output.
+
+Options:
+- `-auto-approve` - Skip interactive approval
+- `--non-interactive` - Disables all interactive approval prompts (Terragrunt as well of Terraform)
+- `-var 'name=value'` - Set variable
+- `--terragrunt-config=PATH` - Use a specific Terragrunt configuration file
+
+```python
+ExecuteTerragruntCommand(TerragruntExecutionRequest(
+    command="apply",
+    working_directory="./project_dir"
+))
+```
+
+#### terragrunt destroy
+
+* Purpose: Destroys all infrastructure managed through the Terragrunt configuration.
+* When to use: When the infrastructure is no longer needed.
+
+>Note: This is typically executed by the developer once the application or environment is being decommissioned.
+
+Options:
+- `-auto-approve` - Skip interactive approval
+- `--non-interactive` - Disables all interactive approval prompts (Terragrunt as well of Terraform)
+- `--terragrunt-config=PATH` - Use a specific Terragrunt configuration file
+
+```python
+ExecuteTerragruntCommand(TerragruntExecutionRequest(
+    command="destroy",
+    working_directory="./project_dir"
+))
+```
+
+#### terragrunt run-all apply
+
+* Purpose: Recursively runs the `apply` command across all child Terragrunt modules in a directory tree.
+* When to use: To apply changes across an entire environment or stack, typically in a root coordination folder.
+
+Options:
+- `--non-interactive` - Disables all interactive approval prompts (Terragrunt as well of Terraform)
+- `--queue-exclude-dir` - Exclude glob path that should be excluded when issuing run-all commands. If a relative path is specified, it should be relative from working-dir.
+- `--queue-include-dir` - Include glob path that should be included when issuing run-all commands. If a relative path is specified, it should be relative from working-dir.
+
+```python
+ExecuteTerragruntCommand(TerragruntExecutionRequest(
+    command="run-all apply",
+    working_directory="./live/production"
+))
+```
+
 ### Checkov Commands
 
 These security scanning commands are available through dedicated tools:
@@ -200,5 +326,5 @@ These security scanning commands are available through dedicated tools:
 - **Cost Optimization**: Design resources to minimize costs while meeting requirements
 - **Operational Excellence**: Implement proper monitoring, logging, and observability
 - **Serverless-First**: Prefer serverless services when possible
-- **Infrastructure as Code**: Use Terraform to define all infrastructure
+- **Infrastructure as Code**: Define all infrastructure declaratively using Terraform (or Terragrunt where applicable)
 - **Regional Awareness**: Consider regional availability and constraints for services

{awslabs_terraform_mcp_server-0.0.11.dist-info → awslabs_terraform_mcp_server-0.0.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.terraform-mcp-server
-Version: 0.0.11
+Version: 0.0.12
 Summary: An AWS Labs Model Context Protocol (MCP) server for terraform
 Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4>=4.12.0
@@ -56,6 +56,12 @@ MCP server for Terraform on AWS best practices, infrastructure as code patterns,
   - Pass variables and specify AWS regions
   - Get formatted command output for analysis
 
+- **Terragrunt Workflow Execution** - Run Terragrunt commands directly
+  - Initialize, plan, validate, apply, run-all and destroy operations
+  - Pass variables and specify AWS regions
+  - Configure terragrunt-config and and include/exclude paths flags
+  - Get formatted command output for analysis
+
 ## Tools and Resources
 
 - **Terraform Development Workflow**: Follow security-focused development process via `terraform://workflow_guide`

{awslabs_terraform_mcp_server-0.0.11.dist-info → awslabs_terraform_mcp_server-0.0.12.dist-info}/RECORD

@@ -1,29 +1,30 @@
 awslabs/__init__.py,sha256=4zfFn3N0BkvQmMTAIvV_QAbKp6GWzrwaUN17YeRoChM,115
 awslabs/terraform_mcp_server/__init__.py,sha256=a-zIkwClerA84_XGykBggO4w5kf8f85EapnWnbAH01c,58
-awslabs/terraform_mcp_server/server.py,sha256=ZyX_w3oath8l2T3tH63EyH5J_l93LZGCxW2HCeL4t2s,15787
+awslabs/terraform_mcp_server/server.py,sha256=6BkVZRQH3qQ44PAQg2sW30x3lL-OKdO7ahCP2KwTFGY,18558
 awslabs/terraform_mcp_server/impl/resources/__init__.py,sha256=bxqHGDtuwWq8w-21lT5GzOuxBqkmnUvW6cnSA36ve3A,388
 awslabs/terraform_mcp_server/impl/resources/terraform_aws_provider_resources_listing.py,sha256=ohd-LOCuwLh0XchmUVRNIlgEcb1qJbiWMvVVklfZZyI,1991
 awslabs/terraform_mcp_server/impl/resources/terraform_awscc_provider_resources_listing.py,sha256=rcxTeN2SvzddNi5bMzMF8oZP9O-Nq4PxzFBiqHbsY-I,2078
-awslabs/terraform_mcp_server/impl/tools/__init__.py,sha256=4D7D6cYF98qj4lltiO5UOHNFRl8Gfg7Zv9n-wRlOj3o,715
+awslabs/terraform_mcp_server/impl/tools/__init__.py,sha256=QUowqVKDnxQUKR36rGJvE1AGxV7xX8ky6ymt-QJoFBw,826
 awslabs/terraform_mcp_server/impl/tools/execute_terraform_command.py,sha256=_fPxC2wT23oWa9XaAoUEV1j5lK7Xpi7MqBAq85fLNdU,8507
+awslabs/terraform_mcp_server/impl/tools/execute_terragrunt_command.py,sha256=7WDV9DhQMLaPXm1kOO2mAczU0ZUiBv6gA3mm9dmgcmc,13024
 awslabs/terraform_mcp_server/impl/tools/run_checkov_scan.py,sha256=oS6qgUPPti7lpa2VNsUwPbswiq2hgpe49fggVUI_PfM,13435
 awslabs/terraform_mcp_server/impl/tools/search_aws_provider_docs.py,sha256=w7NX4oQwsCeVQPj8YZzvXvXcox8drzZimW3mRL8Kd84,29049
 awslabs/terraform_mcp_server/impl/tools/search_awscc_provider_docs.py,sha256=fY8eRQ1j6oB4XyfAoUC6mTUXNkoFaY0vsmMhV6w0NR8,27297
 awslabs/terraform_mcp_server/impl/tools/search_specific_aws_ia_modules.py,sha256=Kny5iharA1Wj-9tnhoPHntu4qM9n-2mC2dB6TXwhqfk,20148
 awslabs/terraform_mcp_server/impl/tools/search_user_provided_module.py,sha256=6d_QHnDwpGicMsmQmpfs0hzTtf-XAVXZBNUsBnkfxtw,14491
 awslabs/terraform_mcp_server/impl/tools/utils.py,sha256=GB1OuhYgrg00AzKfhgaUpQwbVBK5D56GQLcm60NHd1c,20500
-awslabs/terraform_mcp_server/models/__init__.py,sha256=-kCRp9lGMz0-SXv0XvXP48_dVCeMbQIJqkxLTqXlmhk,801
-awslabs/terraform_mcp_server/models/models.py,sha256=oQutL78FdbXXQgekXjp8Dhotq-A-wBJLylQAHRMyNs0,12614
+awslabs/terraform_mcp_server/models/__init__.py,sha256=BmcLbcCd_ORzgr4TjmOMrwHHtp4iyz_BoeRYnEFYiHg,931
+awslabs/terraform_mcp_server/models/models.py,sha256=4kFNKRyDgLAL7TzL9CoADB--90rCCy7aQcubDbOKtjg,15600
 awslabs/terraform_mcp_server/scripts/generate_aws_provider_resources.py,sha256=wxwt3MxD3xUsrDXnfa9-3EAQfBg3fO-CzwkzjYNMIRU,56770
 awslabs/terraform_mcp_server/scripts/generate_awscc_provider_resources.py,sha256=ieHzBfTHPbxkTL3d_mRVga2-xLRRma4TnXC6Amq1ugc,48823
 awslabs/terraform_mcp_server/scripts/scrape_aws_terraform_best_practices.py,sha256=t_eFbciBwZXdK6pNkkcp4X7VPR4vXyXkmE_YLhm6Xr4,3783
 awslabs/terraform_mcp_server/static/AWSCC_PROVIDER_RESOURCES.md,sha256=I_vu3dWXzd9Pxcd7tkdxFQs97wtuunyoXdJCAkCUXnE,440270
 awslabs/terraform_mcp_server/static/AWS_PROVIDER_RESOURCES.md,sha256=OMboscC0Ov6O3U3K1uqrzRzx18nq_5AsJzITc5-CA8Y,303030
 awslabs/terraform_mcp_server/static/AWS_TERRAFORM_BEST_PRACTICES.md,sha256=cftJ9y2nZ0kMendoV6WBlQFsNw-QnGnmF6dR88eoYdA,87665
-awslabs/terraform_mcp_server/static/MCP_INSTRUCTIONS.md,sha256=P82tv9KJJxhoG5UFKaG16nQS5a0ud6Fcvg_BUypz-z0,6445
-awslabs/terraform_mcp_server/static/TERRAFORM_WORKFLOW_GUIDE.md,sha256=1RrSF7NH0BNVnQTZFwPhuaWsxElmCcwvl07iLOnO2gw,9768
+awslabs/terraform_mcp_server/static/MCP_INSTRUCTIONS.md,sha256=r-ChGWXW4EbXquzAeILVayqgTrOoA9XpkzyrHwCrER8,7368
+awslabs/terraform_mcp_server/static/TERRAFORM_WORKFLOW_GUIDE.md,sha256=jCLvjatXFL-1aN0CAuZkWb5IfQP8DVbrc3RsVeze3Fs,15045
 awslabs/terraform_mcp_server/static/__init__.py,sha256=mgAvoiD1_fgcgK5Sbf2nZLlX47D6ZuwuZbMrbNsyUKE,603
-awslabs_terraform_mcp_server-0.0.11.dist-info/METADATA,sha256=6RMm-IRV9vllVfJiyf7XIMWv_Cc4uYhk2NRf5HWskZY,5104
-awslabs_terraform_mcp_server-0.0.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-awslabs_terraform_mcp_server-0.0.11.dist-info/entry_points.txt,sha256=jCTPQeUJ74jpIDcYwVHQCk-y0n0ehRFFerh_Qm4ZU1c,90
-awslabs_terraform_mcp_server-0.0.11.dist-info/RECORD,,
+awslabs_terraform_mcp_server-0.0.12.dist-info/METADATA,sha256=3YSd4udjnQ_x-vcoBV8DMILt-KUWa-BK4qk9xNjEBOU,5403
+awslabs_terraform_mcp_server-0.0.12.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+awslabs_terraform_mcp_server-0.0.12.dist-info/entry_points.txt,sha256=jCTPQeUJ74jpIDcYwVHQCk-y0n0ehRFFerh_Qm4ZU1c,90
+awslabs_terraform_mcp_server-0.0.12.dist-info/RECORD,,