tf-dialect

tf-dialect is an MCP (Model Context Protocol) server that exposes your organization's Terraform style guide to AI coding agents, ensuring they generate context-aware, organization-specific Infrastructure as Code instead of generic HCL.

Configure once, use with any MCP-capable coding agent (Claude Desktop, Cline, etc.).

Quick Start

# Clone the repository
git clone https://github.com/utpaljaynadiger/tf-dialect.git
cd tf-dialect

# Install dependencies
npm install

# Build the project
npm run build

# Create your style configuration
cp terraform-style.example.yaml terraform-style.yaml

# Edit terraform-style.yaml with your organization's standards
# Then configure in your MCP client (see "Running the Server" section)

Why tf-dialect?

The Problem

AI coding assistants generate generic Terraform code that violates your org's standards. Your existing tools (tflint, Sentinel, module registries) are reactive—they catch violations after code is written. Developers waste cycles fixing preventable issues.

The Solution

tf-dialect exposes your Terraform standards to AI agents via MCP before code generation. AI learns your naming conventions, required tags, approved modules, and security defaults, then generates compliant code on first try.

Before/After

Without tf-dialect:

# AI generates generic code
resource "aws_s3_bucket" "logs" {
  bucket = "my-logs-bucket"
}
# ❌ Wrong naming, missing tags, no encryption, not using approved module
# → 3 commits to fix tflint/Sentinel violations

With tf-dialect:

# AI calls get_style_guide() + list_examples() first
module "logs_bucket" {
  source = "../modules/s3-bucket"
  
  name = "acme-prod-logs"
  kms_key_id = data.aws_kms_key.standard.arn
  
  tags = {
    CostCenter  = "engineering"
    Team        = "platform"
    Environment = "prod"
  }
}
# ✅ Passes all checks on first commit

Positioning

tf-dialect is complementary—it makes AI agents aware of your module registry and helps generate code that passes your existing validation tools.

Target Users

• Platform teams: Standardizing AI-generated IaC across your org
• Developers: Using Claude/Copilot/ChatGPT for Terraform
• Organizations: With existing Terraform standards that AI doesn't know about

Features

• 📚 Style Guide Management: Define your Terraform conventions in a single YAML file
• 🔍 Validation: Check Terraform snippets against your organization's rules
• 📝 Code Examples: Provide reusable snippets for common patterns
• 🛡️ Security Defaults: Enforce security best practices automatically
• 🏗️ Code Generation: Generate compliant Terraform resources
• 🤖 AI-Native: Works seamlessly with MCP-capable coding agents

Installation

npm install
npm run build

Configuration

1. Copy the example config:

cp terraform-style.example.yaml terraform-style.yaml

2. Edit terraform-style.yaml to match your organization's standards:

modules:
  pattern: "root + shared-modules"
  shared_module_path: "modules/"
  prefer_shared_modules: true

naming:
  resource_format: "<project>-<env>-<component>-<extra?>"
  variable_case: "snake_case"
  output_case: "snake_case"

tagging:
  required_tags:
    - "environment"
    - "owner"
    - "cost_center"
  defaults:
    environment: "${var.environment}"
    owner: "infra-team"

security_defaults:
  s3_bucket:
    block_public_acls: true
    versioning: true
    encryption: "aws:kms"
  rds:
    storage_encrypted: true
    backup_retention_period: 7

examples:
  s3_private_bucket: |
    module "logs_bucket" {
      source = "../modules/s3-bucket"
      name   = "${local.project}-${var.environment}-logs"
      tags   = local.default_tags
    }

Running the Server

Standalone

npm run mcp

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "tf-dialect": {
      "command": "node",
      "args": ["/absolute/path/to/tf-dialect/dist/index.js"],
      "env": {
        "TERRAFORM_STYLE_PATH": "/absolute/path/to/your/terraform-style.yaml"
      }
    }
  }
}

Or if terraform-style.yaml is in the same directory as the server:

{
  "mcpServers": {
    "tf-dialect": {
      "command": "node",
      "args": ["/absolute/path/to/tf-dialect/dist/index.js"]
    }
  }
}

With Cline VSCode Extension

Add to your MCP settings:

{
  "mcpServers": {
    "tf-dialect": {
      "command": "node",
      "args": ["/absolute/path/to/tf-dialect/dist/index.js"]
    }
  }
}

MCP Tools

The server exposes four tools that AI agents can use:

1. get_style_guide

Get the complete Terraform style guide configuration.

Input: None

Output:

{
  "modules": { ... },
  "naming": { ... },
  "tagging": { ... },
  "providers": { ... },
  "security_defaults": { ... },
  "examples": { ... }
}

Example agent prompt:

"Show me the Terraform style guide for this project"

2. list_examples

List code examples, optionally filtered by resource type or search term.

Input:

{
  "resourceType": "s3_bucket",  // optional
  "search": "postgres"          // optional
}

Output:

{
  "examples": [
    {
      "name": "s3_private_bucket",
      "code": "module \"logs_bucket\" { ... }"
    }
  ]
}

Example agent prompts:

"Show me examples of S3 buckets" "List all RDS examples"

3. validate_snippet

Validate Terraform code against the style guide.

Input:

{
  "code": "resource \"aws_s3_bucket\" \"example\" { ... }",
  "filePath": "main.tf"  // optional
}

Output:

{
  "valid": false,
  "violations": [
    {
      "ruleId": "required_tag_missing",
      "severity": "error",
      "message": "Missing required tags: environment, owner",
      "line": 5,
      "suggestion": "Add the following tags: environment = \"...\", owner = \"...\""
    }
  ]
}

Example agent prompts:

"Validate this Terraform code against our style guide" "Check if this S3 bucket configuration is compliant"

4. generate_resource

Generate a Terraform resource following organization standards.

Input:

{
  "resourceType": "aws_s3_bucket",
  "env": "prod",
  "service": "analytics",
  "purpose": "logs",       // optional
  "extraTags": {           // optional
    "team": "data"
  }
}

Output:

{
  "code": "resource \"aws_s3_bucket\" \"this\" { ... }"
}

Supported resource types:

• aws_s3_bucket
• aws_db_instance
• Others (generates generic stub with TODOs)

Example agent prompts:

"Generate an S3 bucket for prod analytics logs" "Create an RDS instance for the staging API database"

Validation Rules

tf-dialect enforces the following rules:

Required Tags

Ensures all resources include required tags defined in your config.

Forbidden Patterns

Blocks dangerous patterns like:

• 0.0.0.0/0 in security groups
• Hardcoded credentials
• Custom regex patterns you define

Security Defaults

Enforces security best practices:

S3 Buckets:

• Block public access
• Enable versioning
• Enable encryption (KMS or AES256)

RDS Instances:

• Enable storage encryption
• Set backup retention period
• Other configurable defaults

Naming Conventions

Validates resource names follow your format:

• <project>-<env>-<component>-<extra?>
• Checks component count and structure

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

Example Workflow

1. Agent asks about style:

   • Agent calls get_style_guide
   • Learns your organization's conventions

2. Agent needs an example:

   • Agent calls list_examples with resourceType: "rds"
   • Gets working RDS configuration examples

3. Agent generates code:

   • Agent calls generate_resource or writes code
   • Then calls validate_snippet to check compliance

4. Agent fixes violations:

   • Reads violation suggestions
   • Updates code to be compliant

Use Cases

• Onboarding: New team members' AI assistants learn your standards instantly
• Consistency: All Terraform code follows the same patterns across teams
• Security: Enforce security defaults automatically in generated code
• Productivity: AI generates compliant code on first try, not generic HCL

License

MIT

Contributing

Contributions welcome! This is an OSS-friendly project designed for IaC power users.