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
| Tool | Phase | Purpose |
|---|---|---|
| tf-dialect | Pre-generation | Teach AI your standards |
| Module Registry | Reference | Provide reusable modules |
| tflint/checkov | Post-generation | Static analysis |
| Sentinel/OPA | Runtime | Policy enforcement |
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
- Copy the example config:
cp terraform-style.example.yaml terraform-style.yaml
- Edit
terraform-style.yamlto 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_bucketaws_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/0in 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
-
Agent asks about style:
- Agent calls
get_style_guide - Learns your organization's conventions
- Agent calls
-
Agent needs an example:
- Agent calls
list_exampleswithresourceType: "rds" - Gets working RDS configuration examples
- Agent calls
-
Agent generates code:
- Agent calls
generate_resourceor writes code - Then calls
validate_snippetto check compliance
- Agent calls
-
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.