awslabs.terraform-mcp-server 0.0.1__tar.gz

awslabs_terraform_mcp_server-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+
+# Build
+*.manifest
+*.spec
+.pybuilder/
+target/
+
+# Environments
+.env
+.env.local
+.env.*.local
+
+# PyPI
+.pypirc

awslabs_terraform_mcp_server-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v3.13.0
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [push]

awslabs_terraform_mcp_server-0.0.1/.python-version

@@ -0,0 +1 @@
+3.10

awslabs_terraform_mcp_server-0.0.1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- Initial project setup

awslabs_terraform_mcp_server-0.0.1/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: awslabs.terraform-mcp-server
+Version: 0.0.1
+Summary: An AWS Labs Model Context Protocol (MCP) server for terraform
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: checkov>=3.2.402
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pypdf2>=3.0.0
+Requires-Dist: requests>=2.31.0
+Description-Content-Type: text/markdown
+
+# AWS Terraform MCP Server
+
+MCP server for Terraform on AWS best practices, infrastructure as code patterns, and security compliance with Checkov.
+
+## Features
+
+- **Terraform Best Practices** - Get prescriptive Terraform advice for building applications on AWS
+  - AWS Well-Architected guidance for Terraform configurations
+  - Security and compliance recommendations
+  - AWSCC provider prioritization for consistent API behavior
+
+- **Security-First Development Workflow** - Follow a structured process for creating secure code
+  - Step-by-step guidance for validation and security scanning
+  - Integration of Checkov at the right stages of development
+  - Clear handoff points between AI assistance and developer deployment
+
+- **Checkov Integration** - Work with Checkov for security and compliance scanning
+  - Run security scans on Terraform code to identify vulnerabilities
+  - Automatically fix identified security issues when possible
+  - Get detailed remediation guidance for compliance issues
+
+- **AWS Provider Documentation** - Search for AWS and AWSCC provider resources
+  - Find documentation for specific resources and attributes
+  - Get example snippets and implementation guidance
+  - Compare AWS and AWSCC provider capabilities
+
+- **AWS-IA GenAI Modules** - Access specialized modules for AI/ML workloads
+  - Amazon Bedrock module for generative AI applications
+  - OpenSearch Serverless for vector search capabilities
+  - SageMaker endpoint deployment for ML model hosting
+  - Serverless Streamlit application deployment for AI interfaces
+
+- **Terraform Workflow Execution** - Run Terraform commands directly
+  - Initialize, plan, validate, apply, and destroy operations
+  - Pass variables and specify AWS regions
+  - Get formatted command output for analysis
+
+## Tools and Resources
+
+- **Terraform Development Workflow**: Follow security-focused development process via `terraform://workflow_guide`
+- **AWS Best Practices**: Access AWS-specific guidance via `terraform://aws_best_practices`
+- **AWS Provider Resources**: Access resource listings via `terraform://aws_provider_resources_listing`
+- **AWSCC Provider Resources**: Access resource listings via `terraform://awscc_provider_resources_listing`
+
+## Prerequisites
+
+1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
+2. Install Python using `uv python install 3.10`
+3. Install Terraform CLI for workflow execution
+4. Install Checkov for security scanning
+
+## Installation
+
+Here are some ways you can work with MCP across AWS, and we'll be adding support to more products including Amazon Q Developer CLI soon: (e.g. for Amazon Q Developer CLI MCP, `~/.aws/amazonq/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "awslabs.terraform-mcp-server": {
+      "command": "uvx",
+      "args": ["awslabs.terraform-mcp-server@latest"],
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+## Security Considerations
+
+When using this MCP server, you should consider:
+- **Following the structured development workflow** that integrates validation and security scanning
+- Reviewing all Checkov warnings and errors manually
+- Fixing security issues rather than ignoring them whenever possible
+- Documenting clear justifications for any necessary exceptions
+- Using the RunCheckovScan tool regularly to verify security compliance
+- Preferring the AWSCC provider for its consistent API behavior and better security defaults
+
+Before applying Terraform changes to production environments, you should conduct your own independent assessment to ensure that your infrastructure would comply with your own specific security and quality control practices and standards, as well as the local laws, rules, and regulations that govern you and your content.

awslabs_terraform_mcp_server-0.0.1/README.md

@@ -0,0 +1,82 @@
+# AWS Terraform MCP Server
+
+MCP server for Terraform on AWS best practices, infrastructure as code patterns, and security compliance with Checkov.
+
+## Features
+
+- **Terraform Best Practices** - Get prescriptive Terraform advice for building applications on AWS
+  - AWS Well-Architected guidance for Terraform configurations
+  - Security and compliance recommendations
+  - AWSCC provider prioritization for consistent API behavior
+
+- **Security-First Development Workflow** - Follow a structured process for creating secure code
+  - Step-by-step guidance for validation and security scanning
+  - Integration of Checkov at the right stages of development
+  - Clear handoff points between AI assistance and developer deployment
+
+- **Checkov Integration** - Work with Checkov for security and compliance scanning
+  - Run security scans on Terraform code to identify vulnerabilities
+  - Automatically fix identified security issues when possible
+  - Get detailed remediation guidance for compliance issues
+
+- **AWS Provider Documentation** - Search for AWS and AWSCC provider resources
+  - Find documentation for specific resources and attributes
+  - Get example snippets and implementation guidance
+  - Compare AWS and AWSCC provider capabilities
+
+- **AWS-IA GenAI Modules** - Access specialized modules for AI/ML workloads
+  - Amazon Bedrock module for generative AI applications
+  - OpenSearch Serverless for vector search capabilities
+  - SageMaker endpoint deployment for ML model hosting
+  - Serverless Streamlit application deployment for AI interfaces
+
+- **Terraform Workflow Execution** - Run Terraform commands directly
+  - Initialize, plan, validate, apply, and destroy operations
+  - Pass variables and specify AWS regions
+  - Get formatted command output for analysis
+
+## Tools and Resources
+
+- **Terraform Development Workflow**: Follow security-focused development process via `terraform://workflow_guide`
+- **AWS Best Practices**: Access AWS-specific guidance via `terraform://aws_best_practices`
+- **AWS Provider Resources**: Access resource listings via `terraform://aws_provider_resources_listing`
+- **AWSCC Provider Resources**: Access resource listings via `terraform://awscc_provider_resources_listing`
+
+## Prerequisites
+
+1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
+2. Install Python using `uv python install 3.10`
+3. Install Terraform CLI for workflow execution
+4. Install Checkov for security scanning
+
+## Installation
+
+Here are some ways you can work with MCP across AWS, and we'll be adding support to more products including Amazon Q Developer CLI soon: (e.g. for Amazon Q Developer CLI MCP, `~/.aws/amazonq/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "awslabs.terraform-mcp-server": {
+      "command": "uvx",
+      "args": ["awslabs.terraform-mcp-server@latest"],
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+## Security Considerations
+
+When using this MCP server, you should consider:
+- **Following the structured development workflow** that integrates validation and security scanning
+- Reviewing all Checkov warnings and errors manually
+- Fixing security issues rather than ignoring them whenever possible
+- Documenting clear justifications for any necessary exceptions
+- Using the RunCheckovScan tool regularly to verify security compliance
+- Preferring the AWSCC provider for its consistent API behavior and better security defaults
+
+Before applying Terraform changes to production environments, you should conduct your own independent assessment to ensure that your infrastructure would comply with your own specific security and quality control practices and standards, as well as the local laws, rules, and regulations that govern you and your content.

awslabs_terraform_mcp_server-0.0.1/awslabs/__init__.py

@@ -0,0 +1,2 @@
+# This file is part of the awslabs namespace.
+# It is intentionally minimal to support PEP 420 namespace packages.

awslabs_terraform_mcp_server-0.0.1/awslabs/terraform_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""awslabs.terraform-mcp-server"""
+
+__version__ = '0.0.0'

awslabs_terraform_mcp_server-0.0.1/awslabs/terraform_mcp_server/impl/resources/__init__.py

@@ -0,0 +1,11 @@
+"""Resource implementations for the Terraform expert."""
+
+from .terraform_aws_provider_resources_listing import terraform_aws_provider_assets_listing_impl
+from .terraform_awscc_provider_resources_listing import (
+    terraform_awscc_provider_resources_listing_impl,
+)
+
+__all__ = [
+    'terraform_aws_provider_assets_listing_impl',
+    'terraform_awscc_provider_resources_listing_impl',
+]

awslabs_terraform_mcp_server-0.0.1/awslabs/terraform_mcp_server/impl/resources/terraform_aws_provider_resources_listing.py

@@ -0,0 +1,52 @@
+"""Implementation for terraform_aws_provider_resources_listing resource."""
+
+import sys
+from loguru import logger
+from pathlib import Path
+
+
+# Configure logger for enhanced diagnostics with stacktraces
+logger.configure(
+    handlers=[
+        {
+            'sink': sys.stderr,
+            'backtrace': True,
+            'diagnose': True,
+            'format': '<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>',
+        }
+    ]
+)
+
+# Path to the static markdown file
+STATIC_RESOURCES_PATH = (
+    Path(__file__).parent.parent.parent / 'static' / 'AWS_PROVIDER_RESOURCES.md'
+)
+
+
+async def terraform_aws_provider_assets_listing_impl() -> str:
+    """Generate a comprehensive listing of AWS provider resources and data sources.
+
+    This implementation reads from a pre-generated static markdown file instead of
+    scraping the web in real-time. The static file should be generated using the
+    generate_aws_provider_resources.py script.
+
+    Returns:
+        A markdown formatted string with categorized resources and data sources
+    """
+    logger.info('Loading AWS provider resources listing from static file')
+
+    try:
+        # Check if the static file exists
+        if STATIC_RESOURCES_PATH.exists():
+            # Read the static file content
+            with open(STATIC_RESOURCES_PATH, 'r') as f:
+                content = f.read()
+            logger.info('Successfully loaded AWS Provider asset list')
+            return content
+        else:
+            # Send error if static file does not exist
+            logger.debug(f"Static assets list file not found at '{STATIC_RESOURCES_PATH}'")
+            raise Exception('Static assets list file not found')
+    except Exception as e:
+        logger.error(f'Error generating AWS provider assets listing: {e}')
+        return f'# AWS Provider Assets Listing\n\nError generating listing: {str(e)}'

awslabs_terraform_mcp_server-0.0.1/awslabs/terraform_mcp_server/impl/resources/terraform_awscc_provider_resources_listing.py

@@ -0,0 +1,55 @@
+"""Implementation for terraform_awscc_provider_resources_listing resource."""
+
+import sys
+from loguru import logger
+from pathlib import Path
+
+
+# Configure logger for enhanced diagnostics with stacktraces
+logger.configure(
+    handlers=[
+        {
+            'sink': sys.stderr,
+            'backtrace': True,
+            'diagnose': True,
+            'format': '<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>',
+        }
+    ]
+)
+
+# Path to the static markdown file
+STATIC_RESOURCES_PATH = (
+    Path(__file__).parent.parent.parent / 'static' / 'AWSCC_PROVIDER_RESOURCES.md'
+)
+
+
+async def terraform_awscc_provider_resources_listing_impl() -> str:
+    """Generate a comprehensive listing of AWSCC provider resources and data sources.
+
+    This implementation reads from a pre-generated static markdown file instead of
+    scraping the web in real-time. The static file should be generated using the
+    generate_awscc_provider_resources.py script.
+
+    Returns:
+        A markdown formatted string with categorized resources and data sources
+    """
+    logger.info('Loading AWSCC provider resources listing from static file')
+
+    try:
+        # Check if the static file exists
+        if STATIC_RESOURCES_PATH.exists():
+            # Read the static file content
+            with open(STATIC_RESOURCES_PATH, 'r') as f:
+                content = f.read()
+
+            logger.info(
+                f'Successfully loaded AWSCC provider resources from {STATIC_RESOURCES_PATH}'
+            )
+            return content
+        else:
+            # Send error if static file does not exist
+            logger.debug(f"Static assets list file not found at '{STATIC_RESOURCES_PATH}'")
+            raise Exception('Static assets list file not found')
+    except Exception as e:
+        logger.error(f'Error generating AWSCC provider resources listing: {e}')
+        return f'# AWSCC Provider Resources Listing\n\nError generating listing: {str(e)}'

awslabs_terraform_mcp_server-0.0.1/awslabs/terraform_mcp_server/impl/tools/__init__.py

@@ -0,0 +1,15 @@
+"""Tool implementations for the terraform MCP server."""
+
+from .execute_terraform_command import execute_terraform_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
+from .run_checkov_scan import run_checkov_scan_impl
+
+__all__ = [
+    'execute_terraform_command_impl',
+    'search_aws_provider_docs_impl',
+    'search_awscc_provider_docs_impl',
+    'search_specific_aws_ia_modules_impl',
+    'run_checkov_scan_impl',
+]

awslabs_terraform_mcp_server-0.0.1/awslabs/terraform_mcp_server/impl/tools/execute_terraform_command.py

@@ -0,0 +1,206 @@
+"""Implementation of Terraform 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 TerraformExecutionRequest, TerraformExecutionResult
+from loguru import logger
+
+
+async def execute_terraform_command_impl(
+    request: TerraformExecutionRequest,
+) -> TerraformExecutionResult:
+    """Execute Terraform workflow commands against an AWS account.
+
+    This tool runs Terraform commands (init, plan, validate, apply, destroy) in the
+    specified working directory, with optional variables and region settings.
+
+    Parameters:
+        request: Details about the Terraform command to execute
+
+    Returns:
+        A TerraformExecutionResult object containing command output and status
+    """
+    logger.info(f"Executing 'terraform {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']
+    if request.command not in allowed_commands:
+        logger.error(f'Invalid Terraform command: {request.command}')
+        return TerraformExecutionResult(
+            command=f'terraform {request.command}',
+            status='error',
+            error_message=f'Invalid Terraform command: {request.command}. Allowed commands are: {", ".join(allowed_commands)}',
+            working_directory=request.working_directory,
+            outputs=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 TerraformExecutionResult(
+                        command=f'terraform {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,
+                    )
+
+    # Build the command
+    cmd = ['terraform', request.command]
+
+    # Add auto-approve flag for apply and destroy commands to make them non-interactive
+    if request.command in ['apply', 'destroy']:
+        logger.info(f'Adding -auto-approve flag to {request.command} command')
+        cmd.append('-auto-approve')
+
+    # Add variables only for commands that accept them (plan, apply, destroy)
+    if request.command in ['plan', 'apply', 'destroy'] and request.variables:
+        logger.info(f'Adding {len(request.variables)} variables to {request.command} command')
+        for key, value in request.variables.items():
+            cmd.append(f'-var={key}={value}')
+
+    # Execute command
+    try:
+        process = subprocess.run(
+            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)
+
+        result = {
+            'command': f'terraform {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,
+        }
+
+        # Get outputs if this was a successful apply command
+        if request.command == 'apply' and process.returncode == 0:
+            try:
+                logger.info('Getting Terraform outputs')
+                output_process = subprocess.run(
+                    ['terraform', '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)} Terraform outputs')
+            except Exception as e:
+                logger.warning(f'Failed to get Terraform outputs: {e}')
+
+        # Return the output
+        return TerraformExecutionResult(**result)
+    except Exception as e:
+        return TerraformExecutionResult(
+            command=f'terraform {request.command}',
+            status='error',
+            error_message=str(e),
+            working_directory=request.working_directory,
+            outputs=None,
+        )