Skip to main content

Examples and Workflows

Comprehensive usage examples and workflow patterns for the Terraform MCP Server.

🚀 Complete Workflow​

A typical workflow using all three tools:

📚 Document Ingestion Examples​

Ingest AWS Provider Documentation​

User Request:

"Ingest AWS provider resources and data sources"

Tool Invocation:

await ingest_terraform_docs(
    filter_types=["terraform"]  # Both resource and data_source
)

Result:

  • Processes all AWS provider resources
  • Creates structured chunks with metadata
  • Generates vector embeddings
  • Stores in Neo4j with HNSW indexes

Ingest Best Practices​

User Request:

"Ingest Terraform best practices from the docs directory"

Tool Invocation:

await ingest_terraform_docs(
    filter_types=["best_practice"],
    scan_dirs=["docs/", "terraform_mcp_server/docs/"]
)

Result:

  • Scans directories for best practice documents
  • Uses LLM for content extraction and structuring
  • Creates semantic chunks with categories

Ingest Specific Services​

User Request:

"Ingest only EC2 and S3 resources"

Tool Invocation:

await ingest_terraform_docs(
    filter_types=["resource"],
    filter_services=["EC2", "S3"]
)

🔍 Document Search Examples​

Search for Resource Configuration​

User Request:

"Find AWS S3 bucket configuration examples"

Tool Invocation:

await terraform_doc_search(
    query="AWS S3 bucket configuration examples",
    top_k=5,
    similarity_threshold=0.7,
    node_types=["resource"]
)

Example Response:

{
  "results": [
    {
      "content": "resource \"aws_s3_bucket\" \"example\" {\n  bucket = \"my-bucket\"\n  ...\n}",
      "similarity_score": 0.92,
      "node_type": "resource"
    }
  ]
}

Search for Best Practices​

User Request:

"What are the best practices for Terraform state management?"

Tool Invocation:

await terraform_doc_search(
    query="Terraform state management best practices",
    top_k=8,
    similarity_threshold=0.7,
    node_types=["best_practice"]
)

User Request:

"Search for VPC configuration in both resources and best practices"

Tool Invocation:

await terraform_doc_search(
    query="VPC configuration",
    top_k=10,
    similarity_threshold=0.6,
    node_types=["resource", "best_practice"]
)

User Request:

"Find exact matches for EC2 instance with encryption"

Tool Invocation:

await terraform_doc_search(
    query="EC2 instance with encryption",
    top_k=3,
    similarity_threshold=0.9,  # High threshold
    node_types=["resource", "data_source"]
)

⚡ Terraform Execution Examples​

Initialize Terraform​

User Request:

"Initialize Terraform in /tmp/terraform-project"

Tool Invocation:

await terraform_execute(
    command="init",
    working_directory="/tmp/terraform-project"
)

Plan with Variables​

User Request:

"Run terraform plan with environment=production, instance_count=3, 
and AWS region us-west-2 in /tmp/project"

Tool Invocation:

await terraform_execute(
    command="plan",
    working_directory="/tmp/project",
    variables={
        "environment": "production",
        "instance_count": "3"
    },
    aws_region="us-west-2",
    timeout=600  # 10 minutes
)

Apply Configuration​

User Request:

"Apply the terraform configuration in /tmp/project with instance_type=t3.micro"

Tool Invocation:

await terraform_execute(
    command="apply",
    working_directory="/tmp/project",
    variables={
        "instance_type": "t3.micro"
    },
    strip_ansi=True
)

Note: Apply automatically includes -auto-approve flag.

Validate Configuration​

User Request:

"Validate the terraform configuration in /tmp/project"

Tool Invocation:

await terraform_execute(
    command="validate",
    working_directory="/tmp/project"
)

Destroy Infrastructure​

User Request:

"Destroy the infrastructure in /tmp/project with environment=production"

Tool Invocation:

await terraform_execute(
    command="destroy",
    working_directory="/tmp/project",
    variables={
        "environment": "production"
    }
)

Note: Destroy automatically includes -auto-approve flag.

🔄 End-to-End Workflows​

Infrastructure Deployment Workflow​

Scenario: Deploy a new EC2 instance with proper documentation search.

Step 1: Search for guidance
"Search for EC2 instance configuration and best practices"

Step 2: Initialize Terraform
"Initialize Terraform in /tmp/ec2-project"

Step 3: Plan changes
"Plan Terraform changes with instance_type=t3.micro and vpc_id=vpc-12345678"

Step 4: Review plan output
Agent analyzes the plan output...

Step 5: Apply configuration
"Apply the Terraform configuration"

Step 6: Verify
"Validate the configuration is correct"

Documentation-Driven Development​

Scenario: Use documentation to inform infrastructure decisions.

Step 1: Ingest documentation
"Ingest AWS provider resources for EC2 and VPC"

Step 2: Search for patterns
"Search for EC2 instance with VPC configuration guidance"

Step 3: Search for security
"Find best practices for EC2 security groups"

Step 4: Apply learned patterns
"Plan Terraform with recommended configurations"

Multi-Environment Deployment​

Scenario: Deploy to staging then production.

Step 1: Initialize
"Initialize Terraform in /tmp/multi-env"

Step 2: Plan staging
"Plan with environment=staging, instance_count=1"

Step 3: Apply staging
"Apply the configuration"

Step 4: Validate staging
"Validate the configuration"

Step 5: Plan production
"Plan with environment=production, instance_count=3"

Step 6: Apply production
"Apply the configuration"

💡 Tips and Best Practices​

For Document Ingestion​

TipDescription
Start SmallBegin with specific services, then expand
Use FiltersFilter by service to focus ingestion
Monitor ProgressWatch logs for ingestion status
Verify QualityCheck a sample of ingested content
TipDescription
Specific QueriesMore specific queries yield better results
Adjust ThresholdsHigher for precision, lower for recall
Use Node TypesFilter by type to focus search
IterateRefine queries based on results

For Terraform Execution​

TipDescription
Always Plan FirstReview plan output before applying
Set TimeoutsIncrease for complex operations
Use Safe DirectoriesStick to /tmp and /var/tmp
Check Return CodesVerify successful execution

🔒 Security Considerations​

Safe Variable Patterns​

✅ Safe:

variables={
    "environment": "production",
    "instance_type": "t3.micro",
    "count": "3"
}

❌ Blocked (Dangerous Patterns):

variables={
    "cmd": "rm -rf /",          # Command injection
    "script": "$(whoami)",      # Shell expansion
    "path": "../../../etc"      # Directory traversal
}

Allowed Directories​

By default, only these directories are allowed:

  • /tmp
  • /var/tmp

Custom directories can be configured via TERRAFORM_ALLOWED_WORKING_DIRECTORIES.

Example Queries Reference​

Ingestion Queries​

"Ingest AWS provider resources and data sources"
"Ingest Terraform best practices documentation"
"Ingest only EC2, S3, and VPC resources"
"Ingest README files from the project"

Search Queries​

"Find AWS S3 bucket configuration examples"
"Search for VPC data source subnet information"
"What are the best practices for state management?"
"Find EC2 instance with encryption configuration"
"Search for security group rules best practices"

Execution Queries​

"Initialize Terraform in /tmp/terraform-project"
"Plan Terraform changes with environment=production"
"Apply the terraform configuration with instance_type=t3.micro"
"Validate the terraform configuration"
"Destroy the infrastructure in /tmp/project"

Next Steps​

  • 🛠️ Tools - Available MCP tools reference
  • ⚙️ Configuration - Server configuration