Tf Dialect

tf方言

tf方言 是一个MCP（模型上下文协议）服务器，它向AI编码代理公开您组织的Terraform风格指南，确保它们生成上下文感知的、特定于组织的基础设施代码，而不是通用的HCL。

配置一次，与任何支持MCP的编码代理（Claude Desktop、Cline等）一起使用。

快速开始

# 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)

为什么使用tf方言？

问题

AI编码助手生成违反组织标准的通用Terraform代码。您现有的工具（tflint、Sentinel、模块注册表）是 反应式--它们在编写代码后发现违规行为。开发商浪费时间解决可预防的问题。

解决方案

tf方言在代码生成之前通过MCP将您的Terraform标准暴露给AI代理。AI学习你的命名约定、所需标签、批准的模块和安全默认值，然后在第一次尝试时生成符合要求的代码。

之前/之后

没有tf方言：

# 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

使用tf方言：

# 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

定位

tf方言 互补的--它使AI代理知道您的模块注册表，并帮助生成通过现有验证工具的代码。

目标用户

• 平台团队： 在整个组织中标准化人工智能生成的IaC
• 开发者： 使用Claude/Copilot/ChatGPT进行地形建模
• 组织机构： 基于人工智能不了解的现有Terraform标准

特性

• 📚 风格指南管理：在单个YAML文件中定义您的Terraform约定
• 🔍 验证：根据组织的规则检查Terraform代码片段
• 📝 代码示例：为常见模式提供可重用的代码段
• 🛡️ 安全默认值：自动执行安全最佳实践
• 🏗️ 代码生成：生成兼容的Terraform资源
• 🤖 人工智能原生：与支持MCP的编码代理无缝协作

安装

npm install
npm run build

配置

1. 复制示例配置：

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

1. 编辑 terraform-style.yaml 为了符合贵组织的标准：

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

naming:
  resource_format: "
---"
  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
    }

运行服务器

独立

npm run mcp

使用克劳德桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在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"
      }
    }
  }
}

或者如果 terraform-style.yaml 与服务器位于同一目录中：

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

使用Cline VSCode扩展

添加到MCP设置中：

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

MCP工具

服务器公开了AI代理可以使用的四个工具：

1. get_style_guide

获取完整的Terraform样式指南配置。

输入： 无

输出：

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

代理提示示例：

“显示此项目的Terraform样式指南”

______________________________________________________________________

2. list_examples

列出代码示例，可选择按资源类型或搜索词进行筛选。

输入：

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

输出：

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

代理提示示例：

“显示S3存储桶的示例” “列出所有RDS示例”

______________________________________________________________________

3. validate_snippet

根据样式指南验证Terraform代码。

输入：

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

输出：

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

代理提示示例：

“根据我们的样式指南验证此Terraform代码” “检查此S3存储桶配置是否符合要求”

______________________________________________________________________

4. generate_resource

根据组织标准生成Terraform资源。

输入：

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

输出：

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

支持的资源类型：

• aws_s3_bucket
• aws_db_instance
• 其他（生成带有TODO的通用存根）

代理提示示例：

“为prod分析日志生成S3存储桶” “为暂存API数据库创建RDS实例”

______________________________________________________________________

验证规则

tf方言执行以下规则：

必填标签

确保所有资源都包含配置中定义的必需标签。

禁止模式

阻止危险模式，如：

• 0.0.0.0/0 在安全组中
• 硬编码凭证
• 您定义的自定义正则表达式模式

安全默认值

实施安全最佳实践：

S3铲斗：

• 阻止公众访问
• 启用版本控制
• 启用加密（KMS或AES256）

RDS实例：

• 启用存储加密
• 设置备份保留期
• 其他可配置的默认值

命名约定

验证资源名称是否符合您的格式：

• `

---`

• 检查组件数量和结构

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

工作流示例

1. 客服询问风格：

- 客服电话 get_style_guide - 了解组织的惯例

1. Agent需要一个示例：

- 客服电话 list_examples 随着 resourceType: "rds" - 获取可用的RDS配置示例

1. 代理生成代码：

- 客服电话 generate_resource 或编写代码 - 然后打电话 validate_snippet 检查合规性

1. 代理修复违规：

- 读取违规建议 - 更新代码以符合要求

用例

• 入职：新团队成员的人工智能助手会立即学习你的标准
• 一致性：所有Terraform代码在团队中都遵循相同的模式
• 安全：在生成的代码中自动执行安全默认值
• 生产力：AI在第一次尝试时生成符合要求的代码，而不是通用的HCL

许可证

麻省理工学院

贡献

欢迎投稿！这是一个为IaC高级用户设计的OSS友好项目。