# terraform-mcp-server

MCP (Model Context Protocol) server para gestionar los módulos de Terraform de la organización **<TuOrg>** en GitHub.

Este server expone tools que permiten a los agentes de IA buscar, inspeccionar y scaffoldear configuraciones de Terraform usando la librería de módulos privados de la organización (repos con el nombre `terraform-aws-module-*`).

## Funcionalidades

- **search_modules** — Lista y filtra los módulos de Terraform disponibles en la organización
- **get_module** — Obtiene el detalle del módulo: README, variables, outputs y última versión
- **list_module_versions** — Lista todos los tags de versión disponibles de un módulo
- **scaffold_terraform** — Genera una configuración completa de Terraform usando un módulo

## Instalación

```bash
# Clona el repositorio
git clone https://github.com/<TuOrg>/terraform-mcp-server.git
cd terraform-mcp-server

# Instala con pip
pip install -e .

# O con uv
uv pip install -e .
```

## Variables de entorno

| Variable | Obligatoria | Default | Descripción |
|----------|-------------|---------|-------------|
| `GITHUB_TOKEN` | Sí | — | Personal access token de GitHub con scope `repo` |
| `GITHUB_ORG` | Sí | `<TuOrg>` (placeholder) | Nombre de la organización de GitHub — el default es un placeholder, hay que definirla |
| `MODULE_PREFIX` | No | `terraform-aws-module-` | Prefijo de los repos de módulos |
| `TF_MIN_VERSION` | No | `1.10` | Versión mínima de Terraform en las configuraciones generadas (1.10+ es necesario para el locking nativo de state en S3) |
| `IAC_ROLE_NAME` | No | `terraform-iac` | Rol IAM que asume el provider generado — el `assume_role` se emite siempre, nunca se usan credenciales estáticas |

## Uso

### Arrancar el server

```bash
# Directamente
terraform-mcp-server

# O como módulo de Python
python -m terraform_mcp_server.server
```

### Configuración del cliente MCP

Agrégalo a la configuración de tu cliente MCP (por ejemplo, Claude Desktop, Kiro, etc.):

```json
{
  "mcpServers": {
    "terraform-mcp-server": {
      "command": "terraform-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

O si lo ejecutas desde el código fuente con `uv`:

```json
{
  "mcpServers": {
    "terraform-mcp-server": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/terraform-mcp-server", "terraform-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

## Referencia de tools

### search_modules

Busca los módulos de Terraform disponibles en la organización.

**Parámetros:**
- `query` (str, opcional): filtra los módulos por nombre de servicio

**Ejemplo de respuesta:**
```json
{
  "count": 2,
  "modules": [
    {
      "name": "terraform-aws-module-vpc",
      "service_name": "vpc",
      "description": "Terraform module for AWS VPC",
      "last_updated": "2024-01-15T10:30:00Z",
      "default_branch": "main"
    }
  ]
}
```

### get_module

Obtiene información detallada de un módulo concreto.

**Parámetros:**
- `service_name` (str, obligatorio): nombre del servicio (por ejemplo, "vpc", "ec2")

### list_module_versions

Lista todas las versiones disponibles (tags git) de un módulo.

**Parámetros:**
- `service_name` (str, obligatorio): nombre del servicio

### scaffold_terraform

Genera una configuración completa de Terraform usando un módulo.

**Parámetros:**
- `service_name` (str, obligatorio): nombre del servicio
- `variables` (dict, opcional): valores de variables para precargar

**Archivos generados:**
- `versions.tf` — Bloque `terraform` (required_version, required_providers)
- `providers.tf` — Configuración del provider (region + `assume_role` obligatorio sobre `terraform-iac` + default_tags)
- `variables.tf` — Variables comunes + propias del módulo
- `terraform.tfvars` — Valores de las variables (con placeholders)
- `main.tf` — Llamada al módulo
- `outputs.tf` — Outputs del módulo
- `data.tf` — Placeholder de data sources

> El bloque provider incluye siempre `assume_role`. `aws_account_id` es una variable
> obligatoria (validada a 12 dígitos) y sin default — Terraform no se ejecuta hasta
> que se indique la cuenta propietaria del rol `terraform-iac`.

### get_backend_config

Obtiene la configuración del backend S3 (bucket, key, region) según team, project y environment.
El bloque devuelto va en **`backend.tf`** (campo `file` de la respuesta).

**Parámetros:**
- `team` (str, obligatorio): nombre del equipo
- `project` (str, obligatorio): nombre del proyecto
- `environment` (str, obligatorio): environment (dev, staging, prod, ...)
- `bucket` (str, opcional): bucket indicado por el usuario — tiene prioridad sobre `BACKEND_CONFIG`
- `region` (str, opcional): region indicada por el usuario — tiene prioridad sobre `BACKEND_CONFIG`

Normalmente resuelve desde la variable de entorno `BACKEND_CONFIG` (JSON con `backends` y
`environment_mapping`). Si no está definida, **no falla**: devuelve `needs_user_input` con la
pregunta que el agente debe hacer, para volver a llamarla con `bucket` y `region`.

```json
{
  "needs_user_input": true,
  "missing": ["bucket", "region"],
  "question_for_user": "¿En qué bucket de S3 y en qué region quieres guardar el state?"
}
```

## Desarrollo

```bash
# Instala las dependencias de desarrollo
pip install -e ".[dev]"

# Ejecuta en modo desarrollo
python -m terraform_mcp_server.server
```

## Convención de nombres de los módulos

Los módulos siguen el patrón: `terraform-aws-module-{service_name}`

Ejemplos:
- `terraform-aws-module-vpc` → service_name: `vpc`
- `terraform-aws-module-ec2` → service_name: `ec2`
- `terraform-aws-module-rds` → service_name: `rds`
- `terraform-aws-module-s3` → service_name: `s3`

## Licencia

MIT