Cloud Architect MCP · 0.3.0

Servidor MCP stateless para gerar planos AWS revisáveis e provisionar recursos após aprovação administrativa. Implementado em TypeScript, com o SDK oficial MCP v2 e protocolo 2026-07-28.

O projeto tem um modo local executável sem conta AWS e infraestrutura CDK para a execução real. O modo local simula o provisionamento: nenhum recurso de nuvem é criado.

O que este MVP faz

validate_plan não consulta preços, quotas, IAM ou CloudFormation.

Blueprints disponíveis:

• storage: bucket S3 privado, criptografado e versionado.

• event-backbone: fila SQS, dead-letter queue e tabela DynamoDB sob demanda, com PITR. A aplicação consumidora dos eventos deve ser implementada separadamente.

Os recursos são retidos na remoção da stack. Isso preserva dados e também pode manter custos. O MVP cria novas stacks; atualização, exclusão, estimativa de custos, código arbitrário e templates enviados pelo cliente não fazem parte deste recorte.

O modelo de linguagem fica no cliente MCP: ele escolhe o blueprint e preenche parâmetros estruturados. O servidor não precisa de uma chave de API de LLM e não transforma texto livre em infraestrutura irrestrita.

Veja o guia de uso e aplicações para um exemplo completo em linguagem simples.

Novidades da versão 0.3

O histórico permite retomar o trabalho sem guardar cada ID. A comparação distingue mudanças de arquitetura de nomes gerados automaticamente: dois planos equivalentes ainda podem criar stacks diferentes. Operações cujo resultado ficou incerto ganham o estado recuperável NEEDS_ATTENTION; a reconciliação consulta a CloudFormation antes de concluir o resultado.

O artigo para LinkedIn apresenta a motivação, o fluxo e as aplicações do projeto.

Executar localmente

Requisito: Node.js 24.x, incluindo o módulo node:sqlite.

npm ci
npm run check
npm run demo
npm run dev

O servidor escuta exclusivamente em http://127.0.0.1:8787/mcp. O banco SQLite fica em .local/architect.db, fora do Git. O perfil local representa um único desenvolvedor confiável, sem autenticação, e deve permanecer em loopback.

npm run demo executa cliente e servidor oficiais MCP v2 no mesmo processo: gera e compara dois planos, pagina o histórico, verifica a recusa sem aprovação, simula a aprovação administrativa, aplica, consulta e repete a operação. A aprovação automática desse exemplo existe apenas em um banco efêmero de demonstração.

Em outro terminal, com npm run dev aberto:

npm run client -- --tool list_blueprints
npm run client -- --tool plan_architecture --input examples/plan-storage.json
npm run client -- --tool list_plans --input examples/history.json
npm run client -- --tool list_operations --input examples/history.json

Revise o template retornado. Use o id e o digest completos no comando administrativo:

npm run inspect -- --plan <planId>
npm run approve -- --plan <planId> --digest <sha256>

Copie examples/apply.json e preencha planId, digest e uma chave de idempotência própria. Depois:

npm run client -- --tool apply_architecture --input <seu-arquivo.json>
npm run inspect -- --operation <operationId>

O simulador local retoma operações pendentes após reinício. O resultado inclui mode: SIMULATED. Planos expiram em 24 horas; a repetição de uma operação já aceita continua retornando a mesma operação após a expiração.

Arquitetura AWS

flowchart LR
    Client[Cliente MCP] --> API[HTTP API + JWT]
    API --> Gateway[Lambda MCP]
    Gateway --> DB[(DynamoDB)]
    Admin[CLI administrativa / IAM separado] --> DB
    DB --> Stream[DynamoDB Streams]
    Stream --> Dispatcher[Lambda dispatcher]
    Dispatcher --> Workflow[Step Functions Standard]
    Workflow --> Worker[Lambda worker]
    Worker --> CF[CloudFormation]
    Worker --> DB
    Stream --> DLQ[Fila de recuperação]
    Workflow --> Events[EventBridge: falha ou interrupção]
    Events --> Reconciler[Lambda reconciler]
    Reconciler --> CF
    Reconciler --> DB

A aprovação é vinculada ao digest do template. A operação e a mudança de estado do plano são gravadas na mesma transação. O registro da operação funciona como uma saída persistida: o stream dispara a execução mesmo que a conexão MCP termine. O nome determinístico da execução e o token CloudFormation permitem recuperar repetições.

O transporte não preserva sessão MCP. O estado de negócio permanece no banco e no workflow. A consulta usa get_operation; este MVP não implementa a extensão MCP Tasks nem subscriptions/SSE. Clientes precisam suportar a revisão 2026-07-28; o modo legado é rejeitado explicitamente.

O reconciler valida eventos de execuções interrompidas e consulta a stack, sem permissão para criar recursos. EventBridge tem entrega de melhor esforço; a CLI administrativa oferece reconciliação manual. Não há varredura global automática de operações paradas. Veja recuperação e migração do histórico.

Infraestrutura e validação

npm run synth

Esse comando gera os bundles e o CloudFormation da infraestrutura em cdk.out/. A síntese não implanta nada. Os valores JWT de exemplo servem apenas à inspeção local; configure emissor e audiência reais antes de implantar.

Consulte o guia de implantação, as decisões e fronteiras de confiança e as evidências de validação.

npm run typecheck
npm test
npm run format:check
npm audit --omit=dev

A CI executa verificação de tipos, testes, build, formatação, síntese e auditoria de dependências. Testes com clientes MCP e SQLite são reais; os adaptadores AWS são exercitados com respostas controladas do SDK. Uma implantação sandbox continua necessária para validar IAM, authorizer, streams e provisionamento no serviço AWS real.

Para verificar os schemas CloudFormation, instale a ferramenta opcional em um ambiente Python separado:

python -m pip install -r requirements-validation.txt
npm run export:templates
cfn-lint -t .local/templates/*.json
cfn-lint -i W3005 -t cdk.out/CloudArchitectMcpStack.template.json

Somente o template gerado pelo CDK ignora W3005: o CDK inclui dependências explícitas de roles que já são impostas por GetAtt. As demais verificações permanecem ativas.

Autorização remota: o cliente de exemplo usa um bearer token de acesso existente. O HTTP API rejeita tokens inválidos antes de invocar a Lambda, portanto essas respostas padrão não incluem o WWW-Authenticate montado pela aplicação. A descoberta automática completa de autorização exige configuração adicional no gateway/cliente; os metadados do recurso também são servidos na rota pública documentada.

Estrutura

src/domain/       Contratos, schemas, catálogo e invariantes
src/adapters/     Persistência em memória, SQLite e DynamoDB
src/mcp.ts        Ferramentas MCP
src/http.ts       Limites HTTP, origem e metadados de autorização
src/lambda.ts     Adapter API Gateway
src/dispatcher.ts Entrega das operações à Step Functions
src/worker.ts     Criação e acompanhamento CloudFormation
src/reconciler.ts Reconciliação de workflows interrompidos
src/cli/          Inspeção, aprovação, reconciliação e migração
infra/            Infraestrutura CDK
tests/            Domínio, protocolo, persistência e infraestrutura
examples/         Entradas sem segredos

Licença e citação

Licenciado sob a Apache License 2.0, com os créditos em NOTICE. A licença permite uso comercial, respeitadas suas condições, incluindo preservação dos avisos aplicáveis. Dependências de terceiros mantêm suas licenças próprias.

Para citar o projeto, use CITATION.cff ou a opção Cite this repository no GitHub. A citação em artigos e apresentações é recomendada; não foi acrescentada uma obrigação de citação acadêmica à licença. O crédito identifica o perfil público pedropaulofernandes88-stack.

O campo private: true em package.json apenas evita publicação acidental no npm; não controla a visibilidade do repositório GitHub.

Referências

• Especificação MCP 2026-07-28

• SDK TypeScript oficial

• Transações DynamoDB e IAM

• Step Functions Standard

• CloudFormation CreateStack