tf-dialect

# 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 ```bash # 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:** ```hcl # 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:** ```hcl # 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 ```bash npm install npm run build ``` ## Configuration 1. Copy the example config: ```bash cp terraform-style.example.yaml terraform-style.yaml ``` 2. Edit `terraform-style.yaml` to match your organization's standards: ```yaml 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 ```bash npm run mcp ``` ### With Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "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: ```json { "mcpServers": { "tf-dialect": { "command": "node", "args": ["/absolute/path/to/tf-dialect/dist/index.js"] } } } ``` ### With Cline VSCode Extension Add to your MCP settings: ```json { "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:** ```json { "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:** ```json { "resourceType": "s3_bucket", // optional "search": "postgres" // optional } ``` **Output:** ```json { "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:** ```json { "code": "resource \"aws_s3_bucket\" \"example\" { ... }", "filePath": "main.tf" // optional } ``` **Output:** ```json { "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:** ```json { "resourceType": "aws_s3_bucket", "env": "prod", "service": "analytics", "purpose": "logs", // optional "extraTags": { // optional "team": "data" } } ``` **Output:** ```json { "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 ```bash # 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.