Facets Module

Crea y gestiona módulos de Terraform para infraestructura nativa en la nube utilizando la CLI FTF de Facets.cloud.

Documentación

⚠️ OBSOLETO: Este repositorio ya no se mantiene activamente. Utilice Praxis en su lugar. Si necesita esta funcionalidad fuera de Praxis, use la Raptor CLI.

Facets Module MCP Server

Este servidor MCP (Model Context Protocol) para el Módulo Facets ayuda a crear y gestionar módulos de Terraform para infraestructura como código. Se integra con la CLI FTF de Facets.cloud, proporcionando herramientas seguras y robustas para la generación, validación y gestión de módulos para soportar flujos de trabajo de infraestructura nativa en la nube.

Características principales

Operaciones seguras de archivos
Limita todas las operaciones de archivos al directorio de trabajo para garantizar seguridad e integridad.
Herramientas MCP modulares
Ofrece herramientas completas para listar, leer, escribir archivos, generación de módulos, validación y vistas previas. Todos los comandos destructivos o irreversibles requieren confirmación explícita del usuario y admiten vistas previas de simulación (dry-run).
Generación de módulos Facets
Los flujos de trabajo interactivos guiados por indicaciones facilitan la generación de módulos de Terraform con gestión de metadatos, variables y entradas mediante la CLI FTF.
Bifurcación de módulos
Bifurca módulos existentes desde el plano de control de Facets para crear variantes personalizadas. Admite descubrir módulos disponibles, actualizar metadatos y personalizar funcionalidades mientras se preserva la estructura original del módulo.
Soporte de instrucciones complementarias
Lee automáticamente instrucciones adicionales específicas del proyecto desde el directorio mcp_instructions en el nivel raíz, permitiendo a los equipos definir requisitos, restricciones y pautas personalizadas que complementan el comportamiento predeterminado de generación de módulos.
Vista previa y prueba de módulos
Flujo de trabajo de despliegue integral que admite vista previa de módulos, pruebas en proyectos de prueba dedicados y monitoreo de despliegue en tiempo real con comprobaciones de estado y registros. Necesitará un proyecto de prueba con un entorno en ejecución y un recurso habilitado agregado para el módulo que se está probando (debe hacerse manualmente desde la interfaz de Facets).
Integración con entornos en la nube
Admite múltiples proveedores de nube y extrae automáticamente metadatos del repositorio git para enriquecer las vistas previas de módulos.

Herramientas MCP disponibles

Nombre de la herramienta	Descripción
`FIRST_STEP_get_instructions`	Carga todas las instrucciones de escritura de módulos desde el directorio `module_instructions` y las instrucciones complementarias de `mcp_instructions`. Llame siempre a esto primero.
`list_files`	Lista todos los archivos en el directorio de módulo especificado de forma segura dentro del directorio de trabajo.
`read_file`	Lee el contenido de un archivo dentro del directorio de trabajo.
`edit_file_block`	Aplica ediciones quirúrgicas a bloques específicos de texto en archivos. Realiza cambios precisos sin reescribir archivos completos. No puede editar archivos `outputs.tf` ni `facets.yaml`.
`write_config_files`	Escribe y valida archivos de configuración `facets.yaml` con vistas previas de simulación y diferencias.
`write_resource_file`	Escribe archivos de recursos de Terraform (`main.tf`, `variables.tf`, etc.) de forma segura. Excluye `outputs.tf` y `facets.yaml`.
`write_outputs`	Escribe el archivo `outputs.tf` para un módulo con atributos de salida e interfaces en un bloque local.
`write_readme_file`	Escribe un archivo `README.md` para el directorio del módulo con contenido generado por IA.
`write_generic_file`	Escribe archivos genéricamente con comprobaciones de directorio de trabajo y tipo de archivo. Ruta: `facets_mcp/tools/module_files.py`
`generate_module_with_user_confirmation`	Genera un nuevo andamiaje de módulo de Terraform con vista previa de simulación y confirmación del usuario.
`validate_module`	Valida un directorio de módulo de Terraform utilizando los estándares de la CLI FTF y comprueba los tipos de salida.
`push_preview_module_to_facets_cp`	Previsualiza un módulo enviando una versión de prueba al plano de control con contexto git extraído automáticamente.
`register_output_type`	Registra un nuevo tipo de salida en el plano de control de Facets con interfaces, atributos y proveedores.
`get_output_type_details`	Recupera detalles de un tipo de salida específico desde el plano de control de Facets.
`find_output_types_with_provider`	Encuentra todos los tipos de salida que incluyen una fuente de proveedor específica para configuraciones de módulos.
`get_local_modules`	Escanea y lista todos los módulos de Terraform locales buscando `facets.yaml` recursivamente, incluyendo la carga del contenido de outputs.tf si está presente.
`search_modules_after_confirmation`	Busca módulos filtrando por una cadena dentro de los archivos facets.yaml, admite paginación y devuelve los módulos coincidentes con detalles.
`list_test_projects`	Recupera y devuelve los nombres de todos los proyectos de prueba disponibles para el despliegue.
`test_already_previewed_module`	Prueba un módulo que ha sido previsualizado desplegándolo en un proyecto de prueba especificado.
`check_deployment_status`	Comprueba el estado de un despliegue con espera opcional para su finalización.
`get_deployment_logs`	Recupera registros de un despliegue específico.
`list_modules_for_fork`	Lista todos los módulos disponibles desde el plano de control que se pueden bifurcar, mostrándolos en un formato compacto para facilitar la selección.
`fork_existing_module`	Bifurca un módulo existente descargándolo y actualizando sus metadatos (sabor y versión). Admite vista previa de simulación y confirmación del usuario.

Requisitos previos

El servidor MCP requiere uv para la orquestación MCP.

El paquete está disponible en PyPI: facets-module-mcp

Instalar `uv` con Homebrew:

brew install uv

Para otros métodos, consulte la guía oficial de instalación de uv.

Integración con Claude

Agregue lo siguiente a su claude_desktop_config.json:

{
  "mcpServers": {
    "facets-module": {
      "command": "uvx",
      "args": [
        "facets-module-mcp@latest",
        "/Path/to/working-directory" 
      ],
      "env": {
        "FACETS_PROFILE": "default",
        "FACETS_USERNAME": "<YOUR_USERNAME>",
        "FACETS_TOKEN": "<YOUR_TOKEN>",
        "CONTROL_PLANE_URL": "<YOUR_CONTROL_PLANE_URL>"
      }
    }
  }
}

Para un repositorio clonado localmente, use:

{
  "mcpServers": {
    "facets-module": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/cloned/facets-module-mcp/facets_mcp",
        "run",
        "facets_server.py",
        "/path/to/working-directory"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "FACETS_PROFILE": "default",
        "FACETS_USERNAME": "<YOUR_USERNAME>",
        "FACETS_TOKEN": "<YOUR_TOKEN>",
        "CONTROL_PLANE_URL": "<YOUR_CONTROL_PLANE_URL>"
      }
    }
  }
}

⚠ Reemplace <YOUR_USERNAME>, <YOUR_TOKEN> y <YOUR_CONTROL_PLANE_URL> con sus datos de autenticación reales.

El ejecutor uv gestiona automáticamente la configuración del entorno y las dependencias utilizando el archivo pyproject.toml en el directorio MCP.

Si ya ha iniciado sesión en FTF, especificar FACETS_PROFILE es suficiente.

Para la generación de tokens y la configuración de autenticación, consulte la documentación oficial de Facets:
https://readme.facets.cloud/reference/authentication-setup

Nota: Configuración similar está disponible en Cursor, lea aquí

Aspectos destacados de uso

Use las herramientas principales (list_files, read_file, edit_file_block, write_config_files, etc.) para la gestión de código de Terraform.
Use las herramientas de integración de la CLI FTF para andamiaje de módulos, validación y flujos de trabajo de vista previa.
Flujo de despliegue completo: previsualice módulos con push_preview_module_to_facets_cp, pruebe en proyectos de prueba dedicados con test_already_previewed_module y monitoree el progreso usando check_deployment_status y get_deployment_logs.
Emplee indicaciones MCP como generate_new_module para guiar la generación de módulos de forma interactiva, o use fork_existing_module para personalizar módulos existentes.
Todas las acciones destructivas requieren confirmación explícita del usuario y vistas previas de simulación.

Casos de uso de bifurcación de módulos

El servidor MCP ahora admite la bifurcación de módulos existentes desde el plano de control de Facets. Use la indicación "Fork Existing Module" para acceder a un flujo de trabajo guiado para:

Mejoras de seguridad: Bifurque un módulo básico para agregar controles de seguridad adicionales o requisitos de cumplimiento
Adaptaciones de proveedores de nube: Adapte módulos para diferentes proveedores de nube manteniendo la funcionalidad principal
Optimizaciones de rendimiento: Cree variantes de alto rendimiento de módulos existentes con configuraciones mejoradas
Personalizaciones de características: Agregue características o integraciones específicas de la organización a módulos existentes
Actualizaciones de versión: Modernice módulos antiguos con versiones de proveedor actualizadas o nuevas características de Terraform

El flujo de trabajo de bifurcación mantiene la estructura original del módulo mientras le permite personalizar metadatos, variables, recursos y salidas para cumplir con sus requisitos específicos.

Ejemplo de uso

Para un ejemplo completo de cómo usar este servidor MCP con Claude, consulte esta sesión de chat: Creando un Módulo de Terraform con Facets MCP

Este ejemplo demuestra el flujo de trabajo completo desde la generación del módulo hasta las pruebas y el despliegue.

📘 Guía adicional

Para un recorrido detallado y realista de cómo construir un módulo seguro de bucket S3 con IA en la plataforma Facets, consulte
GUIDE.md – Construyendo Módulos de Facets con IA: Una Guía Práctica

Esta guía demuestra el flujo completo de conversación (requisitos, refinamiento del diseño, revisión de implementación, validación, pruebas e iteración) utilizando un ejemplo centrado en el desarrollador adaptado para un caso de uso bancario.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Usted es libre de usarlo, modificarlo y distribuirlo bajo sus términos.