Terry-Form MCP

Terry-Form MCP

Execução de Terraform com inteligência artificial através do Model Context Protocol.

Terry-Form MCP é um servidor Model Context Protocol containerizado que dá a assistentes de IA como Claude acesso seguro e estruturado ao Terraform. Ele expõe 25 ferramentas MCP que abrangem execução de Terraform, inteligência LSP, integração com GitHub e conectividade com Terraform Cloud — tudo rodando dentro de Docker com operações destrutivas bloqueadas por design.

Site de Documentação

Painel de Controle

O painel web integrado fornece monitoramento de saúde do servidor em tempo real, visão geral das categorias de ferramentas e status de integração de relance. O status ao vivo é atualizado automaticamente a cada 5 segundos.

Interface de Configuração

Uma interface de configuração com abas permite gerenciar configurações do servidor, integrações, credenciais de provedores de nuvem e limites de taxa — tudo sem tocar em arquivos de configuração. Construída com a stack HAT (HTMX + Alpine.js + Tailwind CSS).

Integração GitHub	Provedores de Nuvem	Limites de Taxa

Catálogo de Ferramentas

O catálogo interativo de ferramentas em /tools lista todas as 25 ferramentas MCP com busca, filtro por categoria e detalhes expansíveis de parâmetros. Também disponível como endpoint JSON bruto em /api/tools e como arquivo estático tools.json.

Início Rápido

Pré-requisitos

• Docker instalado e em execução
• Python >= 3.10 (para desenvolvimento local)

1. Build

scripts/build.sh      # Linux/macOS
scripts\build.bat     # Windows
# or directly:
docker build -t terry-form-mcp .

2. Executar como Servidor MCP

docker run -it --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp

3. Verificar a Imagem

scripts/verify.sh   # Runs 8 checks: Docker, image size, Terraform, terraform-ls, Python, files, tools, startup

Variáveis de Ambiente

Toda a configuração é feita por variáveis de ambiente. Nenhum arquivo de configuração é necessário para uso básico.

Configuração do Servidor

Terraform

LSP

Integração GitHub

Terraform Cloud

Limites de Taxa

Repasse de Provedores de Nuvem

Estas variáveis são encaminhadas diretamente ao subprocesso do Terraform. Defina-as para autenticar com seu provedor de nuvem.

AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, AWS_REGION, AWS_PROFILE

GCP: GOOGLE_CREDENTIALS, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_PROJECT, GOOGLE_REGION, GOOGLE_ZONE

Azure: ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_SUBSCRIPTION_ID, ARM_TENANT_ID

Configuração do Cliente MCP

Adicione Terry-Form a qualquer cliente compatível com MCP:

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/workspace:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\YourUsername\\terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YourUsername/terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

{
  "mcp.servers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspaceFolder}:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

Ferramentas (25)

Terraform Principal

# Initialize and validate a project
terry(path="infrastructure/aws", actions=["init", "validate"])

# Plan with variables
terry(path="environments/prod", actions=["plan"], vars={"instance_count": "3", "region": "us-east-1"})

Apenas init, validate, fmt e plan são permitidos. apply e destroy são bloqueados.

Inteligência LSP

# Code completions
terraform_complete(file_path="main.tf", line=10, character=0)

# Hover documentation
terraform_hover(file_path="main.tf", line=15, character=12)

# Detailed validation with error locations
terraform_validate_lsp(file_path="main.tf")

# Format a file
terraform_format_lsp(file_path="main.tf")

Alimentado por terraform-ls v0.38.5 — fornece autocompletar sensível ao contexto, documentação inline e diagnósticos com localizações precisas de código-fonte.

Integração GitHub

# Clone a repo and prepare it for Terraform operations
github_clone_repo(owner="myorg", repo="infrastructure")
github_prepare_workspace(owner="myorg", repo="infrastructure", config_path="environments/prod")

Varredura de Segurança

# Scan for hardcoded credentials, missing encryption, overly permissive policies
terry_security_scan(path="my-project")

# Get actionable improvement recommendations
terry_recommendations(path="my-project")

Arquitetura

┌─────────────┐     MCP Protocol     ┌──────────────────────────────────────┐
│ AI Assistant │ ◄──────────────────► │  Terry-Form MCP Server               │
│ (Claude)     │                      │                                      │
└─────────────┘                      │  ┌─────────────┐  ┌──────────────┐  │
                                     │  │ Terraform    │  │ terraform-ls │  │
                                     │  │ CLI 1.12     │  │ LSP 0.38.5   │  │
                                     │  └──────┬───────┘  └──────┬───────┘  │
                                     │         │                 │          │
                                     │         ▼                 ▼          │
                                     │  ┌──────────────────────────────┐   │
                                     │  │   /mnt/workspace (isolated)   │   │
                                     │  └──────────────────────────────┘   │
                                     └──────────────────────────────────────┘
                                              Docker Container

Componentes Principais

Stack do Frontend

A interface web integrada usa a stack HAT:

• HTMX 2.0 — atualizações parciais de página sem recarregamento completo
• Alpine.js 3.14 — reatividade leve no lado do cliente para abas e notificações
• Tailwind CSS — estilização utilitária com modo escuro por padrão

Acessível na raiz do servidor quando executado com transporte streamable-http ou sse.

Modelo de Segurança

Terry-Form implementa defesa em profundidade com quatro camadas:

Variáveis de ambiente forçadas: TF_IN_AUTOMATION=true, TF_INPUT=false, CHECKPOINT_DISABLE=true.

Executando com a Interface Web

Para usar o painel e a interface de configuração, execute com transporte HTTP:

# Local
MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 python3 src/server_enhanced_with_lsp.py

# Docker
docker run -it --rm \
  -p 8000:8000 \
  -v "$(pwd)":/mnt/workspace \
  -e MCP_TRANSPORT=streamable-http \
  terry-form-mcp

Em seguida, abra http://localhost:8000 no seu navegador.

Abas de Configuração

Detalhes do Contêiner

Construído sobre hashicorp/terraform:1.12 (baseado em Alpine, ~150MB). Inclui:

• CLI do Terraform 1.12
• terraform-ls v0.38.5 para suporte LSP
• Python 3.12 com FastMCP 3.0+
• Executa como usuário não-root terraform (UID 1001)

Desenvolvimento

# Install dependencies
pip install -r requirements.txt

# Run locally
python3 src/server_enhanced_with_lsp.py

# Code quality
black .       # Format (88-char line limit)
flake8 .      # Lint
mypy src/*.py # Type check

Limitações

• Sem modificação de estado — apply e destroy são bloqueados intencionalmente
• Apenas variáveis de string — tipos de variáveis complexos não são suportados via repasse de CLI
• Inicialização a frio do LSP — a primeira operação LSP leva 1-2 segundos para inicialização
• Execução local — projetado para fluxos de desenvolvimento, não para CI/CD de produção

Licença

MIT