Facets Module

Crie e gerencie módulos Terraform para infraestrutura nativa em nuvem usando o Facets.cloud FTF CLI.

Documentação

⚠️ OBSOLETO: Este repositório não é mais mantido ativamente. Use Praxis em vez disso. Se você precisar dessa funcionalidade fora do Praxis, use o Raptor CLI.

Servidor MCP do Módulo Facets

Este servidor MCP (Model Context Protocol) para o Módulo Facets auxilia na criação e gerenciamento de módulos Terraform para infraestrutura como código. Ele se integra ao CLI FTF da Facets.cloud, fornecendo ferramentas seguras e robustas para geração, validação e gerenciamento de módulos para dar suporte a fluxos de trabalho de infraestrutura nativa em nuvem.

Principais Recursos

Operações Seguras de Arquivos
Limita todas as operações de arquivos ao diretório de trabalho para garantir segurança e integridade.
Ferramentas MCP Modulares
Oferece ferramentas abrangentes para listagem, leitura, escrita de arquivos, geração de módulos, validação e visualizações. Todos os comandos destrutivos ou irreversíveis exigem confirmação explícita do usuário e suportam visualizações de simulação (dry-run).
Geração de Módulos Facets
Fluxos de trabalho interativos guiados por prompts facilitam a geração de módulos Terraform com gerenciamento de metadados, variáveis e entradas usando o CLI FTF.
Fork de Módulos
Faça fork de módulos existentes do plano de controle Facets para criar variantes personalizadas. Suporta descoberta de módulos disponíveis, atualização de metadados e personalização de funcionalidades, preservando a estrutura original do módulo.
Suporte a Instruções Complementares
Lê automaticamente instruções adicionais específicas do projeto do diretório mcp_instructions no nível raiz, permitindo que as equipes definam requisitos, restrições e diretrizes personalizadas que complementam o comportamento padrão de geração de módulos.
Visualização e Teste de Módulos
Fluxo de trabalho de implantação abrangente com suporte a visualização de módulos, testes em projetos de teste dedicados e monitoramento de implantação em tempo real com verificações de status e logs. Você precisará de um projeto de teste com um ambiente em execução e um recurso habilitado adicionado para o módulo em teste (a ser feito manualmente pela interface do Facets).
Integração com Ambientes de Nuvem
Suporta vários provedores de nuvem e extrai automaticamente metadados do repositório git para enriquecer as visualizações de módulos.

Ferramentas MCP Disponíveis

Nome da Ferramenta	Descrição
`FIRST_STEP_get_instructions`	Carrega todas as instruções de escrita de módulos do diretório `module_instructions` e instruções complementares de `mcp_instructions`. Sempre chame esta primeiro.
`list_files`	Lista todos os arquivos no diretório do módulo especificado com segurança, dentro do diretório de trabalho.
`read_file`	Lê o conteúdo de um arquivo dentro do diretório de trabalho.
`edit_file_block`	Aplica edições cirúrgicas a blocos específicos de texto em arquivos. Faz alterações precisas sem reescrever arquivos inteiros. Não pode editar arquivos `outputs.tf` ou `facets.yaml`.
`write_config_files`	Escreve e valida arquivos de configuração `facets.yaml` com visualizações de simulação (dry-run) e diff.
`write_resource_file`	Escreve arquivos de recursos Terraform (`main.tf`, `variables.tf`, etc.) com segurança. Exclui `outputs.tf` e `facets.yaml`.
`write_outputs`	Escreve o arquivo `outputs.tf` para um módulo com atributos e interfaces de saída em um bloco local.
`write_readme_file`	Escreve um arquivo `README.md` para o diretório do módulo com conteúdo gerado por IA.
`write_generic_file`	Escreve arquivos genericamente com verificações de diretório de trabalho e tipo de arquivo. Caminho: `facets_mcp/tools/module_files.py`
`generate_module_with_user_confirmation`	Gera um novo esqueleto de módulo Terraform com visualização de simulação (dry-run) e confirmação do usuário.
`validate_module`	Valida um diretório de módulo Terraform usando os padrões do CLI FTF e verifica os tipos de saída.
`push_preview_module_to_facets_cp`	Visualiza um módulo enviando uma versão de teste ao plano de controle com contexto git extraído automaticamente.
`register_output_type`	Registra um novo tipo de saída no plano de controle Facets com interfaces, atributos e provedores.
`get_output_type_details`	Recupera detalhes de um tipo de saída específico do plano de controle Facets.
`find_output_types_with_provider`	Encontra todos os tipos de saída que incluem uma fonte de provedor específica para configurações de módulos.
`get_local_modules`	Escaneia e lista todos os módulos Terraform locais pesquisando por `facets.yaml` recursivamente, incluindo o carregamento do conteúdo de outputs.tf se presente.
`search_modules_after_confirmation`	Pesquisa módulos filtrando por uma string dentro de arquivos facets.yaml, suporta paginação e retorna módulos correspondentes com detalhes.
`list_test_projects`	Recupera e retorna os nomes de todos os projetos de teste disponíveis para implantação.
`test_already_previewed_module`	Testa um módulo que foi visualizado, implantando-o em um projeto de teste especificado.
`check_deployment_status`	Verifica o status de uma implantação com espera opcional pela conclusão.
`get_deployment_logs`	Recupera logs de uma implantação específica.
`list_modules_for_fork`	Lista todos os módulos disponíveis do plano de controle que podem ser bifurcados, exibindo-os em formato compacto para fácil seleção.
`fork_existing_module`	Faz fork de um módulo existente baixando-o e atualizando seus metadados (flavor e versão). Suporta visualização de simulação (dry-run) e confirmação do usuário.

Pré-requisitos

O servidor MCP requer uv para orquestração MCP.

O pacote está disponível no PyPI: facets-module-mcp

Instale o `uv` com Homebrew:

brew install uv

Para outros métodos, consulte o guia oficial de instalação do uv.

Integração com Claude

Adicione o seguinte ao seu 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 um repositório 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>"
      }
    }
  }
}

⚠ Substitua <YOUR_USERNAME>, <YOUR_TOKEN> e <YOUR_CONTROL_PLANE_URL> pelos seus dados de autenticação reais.

O executor uv gerencia automaticamente a configuração do ambiente e das dependências usando o arquivo pyproject.toml no diretório MCP.

Se você já fez login no FTF, especificar FACETS_PROFILE é suficiente.

Para geração de tokens e configuração de autenticação, consulte a documentação oficial do Facets:
https://readme.facets.cloud/reference/authentication-setup

Nota: Configuração semelhante está disponível no Cursor, leia aqui

Destaques de Uso

Use as ferramentas principais (list_files, read_file, edit_file_block, write_config_files, etc.) para gerenciamento de código Terraform.
Use as ferramentas de integração do CLI FTF para fluxos de trabalho de criação de esqueleto, validação e visualização de módulos.
Fluxo de implantação completo: visualize módulos com push_preview_module_to_facets_cp, teste em projetos de teste dedicados com test_already_previewed_module e monitore o progresso usando check_deployment_status e get_deployment_logs.
Empregue prompts MCP como generate_new_module para guiar a geração de módulos interativamente, ou use fork_existing_module para personalizar módulos existentes.
Todas as ações destrutivas exigem confirmação explícita do usuário e visualizações de simulação (dry-run).

Casos de Uso de Fork de Módulos

O servidor MCP agora suporta fork de módulos existentes do plano de controle Facets. Use o prompt "Fork Existing Module" para acessar um fluxo de trabalho guiado para:

Aprimoramentos de segurança: Faça fork de um módulo básico para adicionar controles de segurança adicionais ou requisitos de conformidade
Adaptações de provedores de nuvem: Adapte módulos para diferentes provedores de nuvem mantendo a funcionalidade principal
Otimizações de desempenho: Crie variantes de alto desempenho de módulos existentes com configurações aprimoradas
Personalizações de recursos: Adicione recursos ou integrações específicos da organização a módulos existentes
Atualizações de versão: Modernize módulos mais antigos com versões atualizadas de provedores ou novos recursos do Terraform

O fluxo de trabalho de fork mantém a estrutura original do módulo, permitindo que você personalize metadados, variáveis, recursos e saídas para atender aos seus requisitos específicos.

Exemplo de Uso

Para um exemplo abrangente de como usar este servidor MCP com Claude, confira esta sessão de chat: Criando um Módulo Terraform com Facets MCP

Este exemplo demonstra o fluxo de trabalho completo, desde a geração do módulo até o teste e a implantação.

📘 Guia Adicional

Para um passo a passo detalhado e realista de construção de um módulo seguro de bucket S3 com IA na plataforma Facets, consulte
GUIDE.md – Construindo Módulos Facets com IA: Um Guia Prático

Este guia demonstra o fluxo completo da conversa—requisitos, refinamento do design, revisão da implementação, validação, teste e iteração—usando um exemplo focado no desenvolvedor, adaptado para um caso de uso bancário.

Licença

Este projeto é licenciado sob a Licença MIT. Você é livre para usar, modificar e distribuir sob seus termos.