fcp-terraform

fcp-terraform

MCP server for Terraform HCL generation through intent-level commands.

What It Does

fcp-terraform lets LLMs build Terraform configurations by describing infrastructure intent -- resources, data sources, variables, outputs -- and renders them into valid HCL. Instead of writing raw HCL syntax, the LLM sends operations like add resource aws_instance web ami:"ami-0c55b159" instance_type:t2.micro and fcp-terraform manages the semantic model, dependency graph, and serialization. Built on the FCP framework.

Written in Go using HashiCorp's hclwrite library for native HCL AST generation -- no string concatenation or template rendering.

Quick Example

terraform_session('new "Main Infrastructure"')

terraform([
  'add resource aws_instance web ami:"ami-0c55b159" instance_type:t2.micro',
  'add resource aws_s3_bucket assets bucket:"my-assets"',
  'add variable region default:"us-east-1" type:string',
  'add output instance_ip value:"aws_instance.web.public_ip"',
])

terraform_query('plan')

The plan query produces:

variable "region" {
  type    = string
  default = "us-east-1"
}

resource "aws_instance" "web" {
  ami           = "ami-0c55b159"
  instance_type = "t2.micro"
}

resource "aws_s3_bucket" "assets" {
  bucket = "my-assets"
}

output "instance_ip" {
  value = aws_instance.web.public_ip
}

Available MCP Tools

Tool	Purpose
terraform(ops)	Batch mutations -- add, set, remove, connect, nest, label, style
terraform_query(q)	Inspect the config -- map, list, describe, plan, graph, validate, find
terraform_session(action)	Lifecycle -- new, open, save, checkpoint, undo, redo
terraform_help()	Full reference card

Verb Reference

Verb	Syntax
add resource	add resource TYPE LABEL [key:value...]
add provider	add provider PROVIDER [region:R] [key:value...]
add variable	add variable NAME [type:T] [default:V] [description:D]
add output	add output NAME value:EXPR [description:D]
add data	add data TYPE LABEL [key:value...]
add module	add module LABEL source:PATH [key:value...]
connect	connect SRC -> TGT [label:TEXT]
set	set LABEL key:value [key:value...]
nest	nest LABEL BLOCK_TYPE[/CHILD_TYPE] [key:value...]
remove	remove LABEL or remove @SELECTOR
label	label OLD_LABEL "new_label"
style	style LABEL tags:"Key=Val,Key2=Val2"

Selectors

@type:aws_instance      All resources of a given type
@provider:aws            All blocks from a given provider
@kind:resource           All blocks of kind (resource, variable, output, data)
@tag:KEY or @tag:KEY=VAL Blocks matching a tag
@all                     All blocks

Installation

Go install

go install github.com/os-tack/fcp-terraform/cmd/fcp-terraform@latest

GitHub Releases

Download a prebuilt binary from Releases and put fcp-terraform on your PATH.

MCP Client Configuration

{
  "mcpServers": {
    "fcp-terraform": {
      "command": "fcp-terraform"
    }
  }
}

Architecture

cmd/fcp-terraform/main.go     MCP server — 4 tools, stdio transport
        │
internal/terraform/            Domain layer
  ├── model.go                 Semantic model (blocks, attributes, connections)
  ├── adapter.go               FCP adapter (dispatch ops → handlers)
  ├── handlers.go              Verb handlers (add, set, remove, nest, etc.)
  ├── queries.go               Query dispatcher (plan, graph, describe, etc.)
  ├── selectors.go             @type, @provider, @kind, @tag, @all
  ├── values.go                Attribute type inference, hclwrite value generation
  ├── verb_specs.go            Verb specifications and reference card sections
  ├── block_ref.go             Terraform reference detection
  └── index.go                 Label index for O(1) lookups
        │
internal/fcpcore/              Shared FCP framework (Go port)
  ├── tokenizer.go             DSL tokenizer
  ├── parsed_op.go             Operation parser
  ├── verb_registry.go         Verb spec registry + reference card generator
  ├── event_log.go             Event sourcing (undo/redo)
  ├── session.go               Session lifecycle (new, open, save, checkpoint)
  └── formatter.go             Response formatter

HCL generation uses HashiCorp's hclwrite package for native AST manipulation. Provider is auto-detected from resource type prefixes (aws_, google_, azurerm_).

Worked Example: AWS Production Web Stack

A realistic deployment showing how operations compose. This example creates a VPC with subnets, EC2, RDS, S3, IAM, and security groups -- 13 resources total.

terraform_session('new "Acme Corp Web Stack"')