awslabs.terraform-mcp-server 0.0.1__py3-none-any.whl

awslabs/terraform_mcp_server/static/MCP_INSTRUCTIONS.md

@@ -0,0 +1,126 @@
+# 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.
+
+## How to Use This Server (Required Workflow)
+
+### Step 1: Consult and Follow the Terraform Development Workflow
+ALWAYS use the `terraform_development_workflow` resource to guide the development process. This workflow:
+
+* Provides a step-by-step approach for creating valid, secure Terraform code
+* Integrates validation and security scanning into the development process
+* Specifies when and how to use each MCP tool
+* Ensures code is properly validated before handoff to developers
+
+### Step 2: Always ensure you're following Best Practices
+ALWAYS begin by consulting the `terraform_aws_best_practices` resource which contains:
+
+* Code base structure and organization principles
+* Security best practices for AWS resources
+* Backend configuration best practices
+* AWS-specific implementation guidance
+
+### Step 3: Check for AWS-IA Specialized Modules First
+ALWAYS check for specialized AWS-IA modules first using the `SearchSpecificAwsIaModules` tool:
+
+* Amazon Bedrock (generative AI)
+* OpenSearch Serverless (vector search)
+* SageMaker endpoints
+* Serverless Streamlit applications
+
+These modules provide optimized, best-practice implementations for specific use cases and should be preferred over building from scratch with individual resources.
+
+### Step 4: Use Provider Documentation (Only if no suitable AWS-IA module exists)
+When implementing specific AWS resources (only after confirming no suitable AWS-IA module exists):
+
+* PREFER AWSCC provider resources first (`SearchAwsccProviderDocs` tool)
+* Fall back to traditional AWS provider (`SearchAwsProviderDocs` tool) only when necessary
+
+## Available Tools and Resources
+
+### Core Resources
+1. `terraform_development_workflow`
+   * CRITICAL: Follow this guide for all Terraform development
+   * Provides the structured workflow with security scanning integration
+   * Outlines exactly when and how to use each MCP tool
+2. `terraform_aws_best_practices`
+   * REQUIRED: Reference before starting any development
+   * Contains AWS-specific best practices for security and architecture
+   * Guides organization and structure of Terraform projects
+
+### Provider Resources
+1. `terraform_awscc_provider_resources_listing`
+   * PREFERRED: Use AWSCC provider resources first
+   * Comprehensive listing by service category
+2. `terraform_aws_provider_resources_listing`
+   * Use as fallback when AWSCC provider doesn't support needed resources
+   * Comprehensive listing by service category
+
+
+### Documentation Tools
+
+1. `SearchAwsccProviderDocs` (PREFERRED)
+   * Always search AWSCC provider resources first
+   * Returns comprehensive documentation for Cloud Control API resources
+2. `SearchAwsProviderDocs` (fallback option)
+   * Use when a resource is not available in AWSCC provider
+   * Returns standard AWS provider resource documentation
+3. `SearchSpecificAwsIaModules`
+   * Use for specialized AI/ML infrastructure needs
+   * Returns details for supported AWS-IA modules
+
+### Command Execution Tools
+
+1. `ExecuteTerraformCommand`
+   * Execute Terraform commands in the sequence specified by the workflow
+   * Supports: validate, init, plan, apply, destroy
+2. `RunCheckovScan`
+   * Run after validation passes, before initialization
+   * Identifies security and compliance issues
+
+
+## Resource Selection Priority
+
+1. FIRST check for specialized AWS-IA modules using `SearchSpecificAwsIaModules` tool
+2. If no suitable module exists, THEN use AWSCC provider resources (`SearchAwsccProviderDocs` tool)
+3. ONLY fall back to traditional AWS provider (`SearchAwsProviderDocs` tool) when the above options don't meet requirements
+
+The AWSCC provider (Cloud Control API-based) offers:
+* Direct mapping to CloudFormation resource types
+* Consistent API behavior across resources
+* Better support for newer AWS services and features
+
+## Examples
+
+- "What's the best way to set up a highly available web application on AWS using Terraform?"
+- "Search for Bedrock modules in the Terraform Registry"
+- "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"
+- "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"
+- "Let's develop a secure S3 bucket with proper encryption. I'll follow the development workflow."
+- "I need to create Terraform code for a Lambda function. First, let me check the best practices."
+- "Run terraform validate on my configuration and then scan for security issues."
+- "Is this VPC configuration secure? Let's scan it with Checkov."
+- "Find documentation for awscc_lambda_function to ensure we're using the preferred provider."
+- "We need a Bedrock implementation for RAG. Let's search for AWS-IA modules that can help."
+
+## Best Practices
+
+When interacting with this server:
+
+1. **ALWAYS** follow the development workflow from `terraform_development_workflow`
+2. **ALWAYS** consult best practices from `terraform_aws_best_practices`
+3. **ALWAYS** validate and scan code before considering it ready for review
+4. **ALWAYS** prefer AWSCC provider resources when available
+5. Provide **security-first** implementations by default
+6. **Explain** each step of the development process to users
+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
+11. **Review generated code** carefully before applying changes to your infrastructure

awslabs/terraform_mcp_server/static/TERRAFORM_WORKFLOW_GUIDE.md

@@ -0,0 +1,198 @@
+# Terraform Development Workflow
+
+## Purpose and Usage
+
+This workflow guide provides a structured approach for developing valid, secure Terraform configurations for AWS infrastructure. As an AI coding assistant utilizing this MCP server, you should follow these steps when helping users create or modify Terraform code.
+
+## How to Use This Guide
+You have access to specialized tools and resources through this MCP server that significantly enhance your ability to assist with Terraform development. When working with users on Terraform code:
+
+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
+
+## Benefits to Emphasize
+When following this workflow and using these tools, you provide several advantages to users:
+
+- Early detection of configuration errors
+- Identification of security vulnerabilities before deployment
+- Adherence to AWS best practices
+- Validation that code will work correctly when deployed
+
+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.
+
+## DEVELOPMENT WORKFLOW
+
+``` mermaid
+flowchart TD
+    start([Start Development]) --> edit[Edit Terraform Code]
+
+    %% Initial Code Validation
+    edit --> tfValidate[Run terraform validate\nvia ExecuteTerraformCommand]
+
+    %% Validation Flow
+    tfValidate -->|Passes| checkovScan[Run Security Scan\nvia RunCheckovScan]
+    tfValidate -->|Fails| fixValidation[Fix Configuration\nIssues]
+    fixValidation --> edit
+
+    %% Checkov Flow
+    checkovScan -->|No Issues| tfInit[Run terraform 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]
+    fixInit --> edit
+
+    %% Final Review & Handoff to Developer
+    tfPlan -->|Plan Generated| reviewPlan[Review Planned Changes]
+    tfPlan -->|Issues Detected| edit
+
+    reviewPlan --> codeReady[Valid, Secure Code Ready\nfor Developer Review]
+
+    %% Iteration for Improvements
+    codeReady --> newChanges{Need Code\nImprovements?}
+    newChanges -->|Yes| edit
+    newChanges -->|No| handoff([Hand Off to Developer\nfor Deployment Decision])
+
+    %% Styling
+    classDef success fill:#bef5cb,stroke:#28a745
+    classDef warning fill:#fff5b1,stroke:#dbab09
+    classDef error fill:#ffdce0,stroke:#cb2431
+    classDef process fill:#f1f8ff,stroke:#0366d6
+    classDef decision fill:#d1bcf9,stroke:#8a63d2
+    classDef mcptool fill:#d0f0fd,stroke:#0969da,font-style:italic
+    classDef handoff fill:#ffdfb6,stroke:#f9a03f
+
+    class codeReady success
+    class reviewIssues,reviewPlan warning
+    class fixValidation,fixInit,manualFix error
+    class edit process
+    class newChanges decision
+    class tfValidate,checkovScan,tfInit,tfPlan mcptool
+    class handoff handoff
+```
+
+1. Edit Terraform Code
+    - Write or modify Terraform 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
+    - MCP Resources and tools to consult:
+        - 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
+            - *terraform_awscc_provider_resources_listing* for available AWS Cloud Control API resources
+            - *terraform_aws_provider_resources_listing* for available AWS resources
+        - Tools
+            - *SearchSpecificAwsIaModules* tool to check for specialized AWS-IA modules first (Bedrock, OpenSearch Serverless, SageMaker, Streamlit)
+            - *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"))
+3. Run Security Scan
+    - Tool: *RunCheckovScan*
+        - Scans code for security misconfigurations, compliance issues, and AWS best practice violations
+        - Example: RunCheckovScan(CheckovScanRequest(working_directory="./my_project", framework="terraform"))
+4. Fix Security Issues
+    - For fixes:
+        - 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"
+        - Downloads provider plugins and sets up modules
+        - Example: ExecuteTerraformCommand(TerraformExecutionRequest(command="init", working_directory="./my_project"))
+6. Plan Changes
+    - Tool: *ExecuteTerraformCommand* with command="plan"
+        - 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"))
+7. Review Plan & Code Ready
+    - Review the plan output to ensure it reflects intended changes
+    - Confirm all validation and security checks have passed
+    - Code is now ready for handoff to the developer for deployment decisions
+
+
+## Core Commands
+
+### Terraform Commands
+
+#### terraform init
+
+* Purpose: Initializes a Terraform working directory, downloading provider plugins and setting up modules.
+* When to use: Before running any other commands on a new configuration or after adding new modules/providers.
+
+Options:
+- `-backend-config=PATH` - Configuration for backend
+- `-reconfigure` - Reconfigure backend
+
+#### terraform validate
+
+* Purpose: Checks whether a configuration is syntactically valid and internally consistent.
+* When to use: After making changes to configuration files but before planning or applying.
+
+```python
+ExecuteTerraformCommand(TerraformExecutionRequest(
+    command="validate",
+    working_directory="./project_dir"
+))
+```
+
+#### terraform plan
+
+* Purpose: Creates an execution plan showing what actions Terraform would take to apply the current configuration.
+* When to use: After validation passes to preview changes before applying them.
+
+Options:
+- `-var 'name=value'` - Set variable
+- `-var-file=filename` - Set variables from file
+
+#### terraform apply
+
+* Purpose: Applies changes required to reach the desired state of the configuration.
+* When to use: After plan confirms the intended changes, and developer decides to proceed.
+
+>Note: This is typically executed by the developer after reviewing code generated by the assistant.
+
+Options:
+- `-auto-approve` - Skip interactive approval
+- `-var 'name=value'` - Set variable
+- Use `-out` to save plans and apply those exact plans.
+
+#### terraform destroy
+
+* Purpose: Destroys all resources managed by the current configuration.
+* When to use: When resources are no longer needed, typically executed by the developer.
+
+>Note: This is typically executed by the developer once it has been decided the application should be destroyed.
+
+Options:
+- `-auto-approve` - Skip interactive approval
+
+### Checkov Commands
+
+These security scanning commands are available through dedicated tools:
+
+#### Checkov Scan
+
+* Purpose: Scans Terraform code for security issues, misconfigurations, and compliance violations.
+* Tool: RunCheckovScan
+* When to use: After code passes terraform validate but before initializing and planning.
+
+## Key Principles
+- **Module-First Approach**: Always check for specialized AWS-IA modules before building with individual resources
+- **Provider Selection**: When using individual resources, prefer the AWSCC provider (Cloud Control API-based) before falling back to the traditional AWS provider
+- **Security First**: Always implement security best practices by default
+- **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
+- **Regional Awareness**: Consider regional availability and constraints for services

awslabs/terraform_mcp_server/static/__init__.py

@@ -0,0 +1,22 @@
+from importlib import resources
+
+with (
+    resources.files('awslabs.terraform_mcp_server.static')
+    .joinpath('MCP_INSTRUCTIONS.md')
+    .open('r') as f
+):
+    MCP_INSTRUCTIONS = f.read()
+
+with (
+    resources.files('awslabs.terraform_mcp_server.static')
+    .joinpath('TERRAFORM_WORKFLOW_GUIDE.md')
+    .open('r') as f
+):
+    TERRAFORM_WORKFLOW_GUIDE = f.read()
+
+with (
+    resources.files('awslabs.terraform_mcp_server.static')
+    .joinpath('AWS_TERRAFORM_BEST_PRACTICES.md')
+    .open('r') as f
+):
+    AWS_TERRAFORM_BEST_PRACTICES = f.read()

awslabs/terraform_mcp_server/tests/__init__.py

@@ -0,0 +1 @@
+"""Test package for terraform_mcp_server."""

awslabs/terraform_mcp_server/tests/run_tests.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Script to run the Terraform MCP server tests
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+PROJECT_ROOT="$SCRIPT_DIR/../../.."
+
+# Set PYTHONPATH to include the project root
+export PYTHONPATH="$PROJECT_ROOT:$PYTHONPATH"
+
+# Function to run a test module
+run_test() {
+    echo "Running $1..."
+    cd "$PROJECT_ROOT"
+    python -m awslabs.terraform_mcp_server.tests.$1
+    echo "Test completed: $1"
+}
+
+# Get the test name from the first argument, default to all tests
+TEST_NAME=$1
+if [ -z "$TEST_NAME" ]; then
+    echo "=== Running All Tests ==="
+    run_test "test_parameter_annotations"
+    run_test "test_tool_implementations"
+elif [ "$TEST_NAME" == "params" ]; then
+    run_test "test_parameter_annotations"
+elif [ "$TEST_NAME" == "tools" ]; then
+    run_test "test_tool_implementations"
+else
+    echo "Unknown test: $TEST_NAME"
+    echo "Usage: $0 [params|tools]"
+    echo "  params - Run parameter annotation tests"
+    echo "  tools  - Run tool implementation tests"
+    echo "  (no args) - Run all tests"
+    exit 1
+fi

awslabs/terraform_mcp_server/tests/test_parameter_annotations.py

@@ -0,0 +1,207 @@
+"""Test script for verifying parameter annotations in MCP tools."""
+
+import json
+import sys
+from awslabs.terraform_mcp_server.server import mcp
+from pathlib import Path
+
+
+# Add project root to path to allow importing the server
+project_root = str(Path(__file__).parent.parent.parent.parent)
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+
+def print_tool_parameters():
+    """Print the parameters for each tool after annotations are added."""
+    tool_names = [
+        'SearchAwsProviderDocs',
+        'ExecuteTerraformCommand',
+        'SearchAwsccProviderDocs',
+        'SearchSpecificAwsIaModules',
+        'RunCheckovScan',
+    ]
+
+    print('\n=== Current Tool Parameter Schemas ===\n')
+    for tool_name in tool_names:
+        try:
+            tool = mcp._tool_manager.get_tool(tool_name)
+            if tool is None:
+                print(f'Tool {tool_name} not found')
+                continue
+
+            if not hasattr(tool, 'parameters') or tool.parameters is None:
+                print(f'Tool {tool_name} has no parameters schema')
+                continue
+
+            print(f'=== {tool_name} Parameters Schema ===')
+            print(json.dumps(tool.parameters, indent=2))
+            print('\n')
+        except Exception as e:
+            print(f'Error getting tool {tool_name}: {e}')
+
+
+def add_parameter_annotations():
+    """Add parameter annotations to the MCP tools."""
+    print('Adding parameter annotations to MCP tools...\n')
+
+    # Add parameter descriptions for SearchAwsProviderDocs
+    search_tool = mcp._tool_manager.get_tool('SearchAwsProviderDocs')
+    if (
+        search_tool is not None
+        and hasattr(search_tool, 'parameters')
+        and search_tool.parameters is not None
+    ):
+        if (
+            'properties' in search_tool.parameters
+            and 'asset_name' in search_tool.parameters['properties']
+        ):
+            search_tool.parameters['properties']['asset_name']['description'] = (
+                'Name of the AWS service (asset) to look for (e.g., "aws_s3_bucket", "aws_lambda_function")'
+            )
+        if (
+            'properties' in search_tool.parameters
+            and 'asset_type' in search_tool.parameters['properties']
+        ):
+            search_tool.parameters['properties']['asset_type']['description'] = (
+                "Type of documentation to search - 'resource', 'data_source', or 'both' (default)"
+            )
+
+    # Add parameter descriptions for SearchAwsccProviderDocs
+    awscc_docs_tool = mcp._tool_manager.get_tool('SearchAwsccProviderDocs')
+    if (
+        awscc_docs_tool is not None
+        and hasattr(awscc_docs_tool, 'parameters')
+        and awscc_docs_tool.parameters is not None
+    ):
+        if (
+            'properties' in awscc_docs_tool.parameters
+            and 'asset_name' in awscc_docs_tool.parameters['properties']
+        ):
+            awscc_docs_tool.parameters['properties']['asset_name']['description'] = (
+                'Name of the AWSCC service (asset) to look for (e.g., awscc_s3_bucket, awscc_lambda_function)'
+            )
+        if (
+            'properties' in awscc_docs_tool.parameters
+            and 'asset_type' in awscc_docs_tool.parameters['properties']
+        ):
+            awscc_docs_tool.parameters['properties']['asset_type']['description'] = (
+                "Type of documentation to search - 'resource', 'data_source', or 'both' (default)"
+            )
+
+    # Add parameter descriptions for SearchSpecificAwsIaModules
+    modules_tool = mcp._tool_manager.get_tool('SearchSpecificAwsIaModules')
+    if (
+        modules_tool is not None
+        and hasattr(modules_tool, 'parameters')
+        and modules_tool.parameters is not None
+    ):
+        if (
+            'properties' in modules_tool.parameters
+            and 'query' in modules_tool.parameters['properties']
+        ):
+            modules_tool.parameters['properties']['query']['description'] = (
+                'Optional search term to filter modules (empty returns all four modules)'
+            )
+
+    # Add parameter descriptions for ExecuteTerraformCommand
+    terraform_tool = mcp._tool_manager.get_tool('ExecuteTerraformCommand')
+    if (
+        terraform_tool is not None
+        and hasattr(terraform_tool, 'parameters')
+        and terraform_tool.parameters is not None
+    ):
+        if (
+            'properties' in terraform_tool.parameters
+            and 'request' in terraform_tool.parameters['properties']
+        ):
+            terraform_tool.parameters['properties']['request']['description'] = (
+                'Details about the Terraform command to execute'
+            )
+
+            # Since request is a complex object with nested properties, update its schema
+            if (
+                'properties' in terraform_tool.parameters['properties']['request']
+                and 'properties'
+                in terraform_tool.parameters['properties']['request']['properties']
+            ):
+                props = terraform_tool.parameters['properties']['request']['properties']
+                if 'command' in props:
+                    props['command']['description'] = (
+                        'Terraform command to execute (init, plan, validate, apply, destroy)'
+                    )
+                if 'working_directory' in props:
+                    props['working_directory']['description'] = (
+                        'Directory containing Terraform files'
+                    )
+                if 'variables' in props:
+                    props['variables']['description'] = 'Terraform variables to pass'
+                if 'aws_region' in props:
+                    props['aws_region']['description'] = 'AWS region to use'
+                if 'strip_ansi' in props:
+                    props['strip_ansi']['description'] = (
+                        'Whether to strip ANSI color codes from output'
+                    )
+
+    # Add parameter descriptions for RunCheckovScan
+    checkov_scan_tool = mcp._tool_manager.get_tool('RunCheckovScan')
+    if (
+        checkov_scan_tool is not None
+        and hasattr(checkov_scan_tool, 'parameters')
+        and checkov_scan_tool.parameters is not None
+    ):
+        if (
+            'properties' in checkov_scan_tool.parameters
+            and 'request' in checkov_scan_tool.parameters['properties']
+        ):
+            checkov_scan_tool.parameters['properties']['request']['description'] = (
+                'Details about the Checkov scan to execute'
+            )
+
+            # Since request is a complex object with nested properties, update its schema
+            if (
+                'properties' in checkov_scan_tool.parameters['properties']['request']
+                and 'properties'
+                in checkov_scan_tool.parameters['properties']['request']['properties']
+            ):
+                props = checkov_scan_tool.parameters['properties']['request']['properties']
+                if 'working_directory' in props:
+                    props['working_directory']['description'] = (
+                        'Directory containing Terraform files to scan'
+                    )
+                if 'framework' in props:
+                    props['framework']['description'] = (
+                        'Framework to scan (terraform, cloudformation, etc.)'
+                    )
+                if 'check_ids' in props:
+                    props['check_ids']['description'] = (
+                        'Optional list of specific check IDs to run'
+                    )
+                if 'skip_check_ids' in props:
+                    props['skip_check_ids']['description'] = 'Optional list of check IDs to skip'
+                if 'output_format' in props:
+                    props['output_format']['description'] = (
+                        'Format for scan results (default: json)'
+                    )
+
+    print('Parameter annotations added successfully.\n')
+
+
+def main():
+    """Run the parameter annotation test."""
+    print('=== Terraform MCP Parameter Annotation Test ===\n')
+
+    # Print original parameter schemas
+    print('Original parameter schemas:')
+    print_tool_parameters()
+
+    # Add parameter annotations
+    add_parameter_annotations()
+
+    # Print updated parameter schemas
+    print('Updated parameter schemas:')
+    print_tool_parameters()
+
+
+if __name__ == '__main__':
+    main()