Gerando Diagramas de Arquitetura AWS com Kiro CLI e Agent Skills

Ao tentar seguir o tutorial oficial da AWS “Build AWS architecture diagrams using Amazon Q CLI and MCP” para gerar diagramas de arquitetura dos meus projetos, me deparei com um problema: o MCP server awslabs.aws-diagram-mcp-server foi descontinuado. Todas as versões foram removidas (yanked) do PyPI.

A funcionalidade migrou para o sistema de Agent Skills do plugin deploy-on-aws do repositório awslabs/agent-plugins. Neste post, compartilho o caminho atualizado para configurar tudo e gerar diagramas profissionais no formato .drawio.

O que mudou?

Antes (Descontinuado)	Agora (Atual)
`awslabs.aws-diagram-mcp-server`	Agent Skill `aws-architecture-diagram`
Gerava PNG via Python `diagrams` + Graphviz	Gera `.drawio` XML com ícones AWS4 oficiais
Dependia de Graphviz instalado	Não precisa de Graphviz
Diagrama estático (imagem)	Diagrama editável (draw.io)
Sem dark mode	Suporte a dark mode nativo

A nova abordagem é superior: gera diagramas editáveis, com ícones oficiais AWS4, step badges numerados, containers coloridos por categoria, e suporte a dark mode.

Pré-requisitos

Kiro CLI instalado e configurado
Python 3.10+
uv (gerenciador de pacotes Python)
bun (para instalar plugins)
defusedxml (validação XML dos diagramas)
draw.io desktop (opcional, para export PNG/SVG/PDF)

Instalação Passo a Passo

1. Instalar dependências base

# Instalar uv (se não tiver)
pip install uv

# Instalar bun (necessário para o instalador de plugins)
curl -fsSL https://bun.sh/install | bash

# Instalar defusedxml (validação XML)
sudo apt-get install -y python3-defusedxml
# ou: pip3 install "defusedxml>=0.7.1"

2. Instalar o plugin deploy-on-aws

COMPOUND_PLUGIN_GITHUB_SOURCE=https://github.com/awslabs/agent-plugins \
  bunx @every-env/compound-plugin install deploy-on-aws --to kiro --output ~/.kiro

Isso instala duas skills:

aws-architecture-diagram — gera diagramas draw.io com ícones AWS4
deploy — analisa codebase, recomenda serviços AWS, estima custos

3. Corrigir estrutura de diretórios (se necessário)

O instalador pode criar um nível extra. Verifique:

# Se ficou em ~/.kiro/.kiro/skills/, mova:
mv ~/.kiro/.kiro/skills/deploy ~/.kiro/skills/
mv ~/.kiro/.kiro/skills/aws-architecture-diagram ~/.kiro/skills/
rmdir ~/.kiro/.kiro/skills

Estrutura final esperada:

~/.kiro/skills/
├── aws-architecture-diagram/
│   ├── SKILL.md
│   └── references/
│       ├── aws4-shapes-services.md
│       ├── style-guide.md
│       ├── xml-rules.md
│       ├── xml-templates-structure.md
│       └── example-*.drawio
└── deploy/
    ├── SKILL.md
    └── references/

4. Configurar MCP Servers

Adicione ao seu ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "awsknowledge": {
      "type": "http",
      "url": "https://knowledge-mcp.global.api.aws",
      "disabled": false
    },
    "aws-documentation": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "disabled": false
    },
    "terraform": {
      "command": "uvx",
      "args": ["awslabs.aws-iac-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "disabled": false
    },
    "aws-pricing": {
      "command": "uvx",
      "args": ["awslabs.aws-pricing-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "disabled": false
    }
  }
}

Nota: O antigo awslabs.aws-diagram-mcp-server não funciona mais. Se estiver no seu config, remova-o.

5. Remover o server descontinuado (se existir)

Se você seguiu o tutorial antigo e tem o awslabs.aws-diagram-mcp-server configurado, remova-o:

# Verifique se está no seu mcp.json
grep "aws-diagram" ~/.kiro/settings/mcp.json

# Se encontrar, remova o bloco inteiro

O erro que você verá se tentar usar:

× No solution found when resolving tool dependencies:
  Because awslabs-aws-diagram-mcp-server>=0.8.2025141004 was yanked
  (reason: Superceeded by diagram agent skill in the deploy-on-aws plugin)

Como Usar

Modo Brainstorm (do zero)

Inicie o Kiro CLI e descreva a arquitetura:

kiro-cli

Depois, no chat:

Generate an architecture diagram for a serverless REST API with 
API Gateway, Lambda, DynamoDB and Cognito authentication

Modo Análise (de código existente)

Dentro do diretório do seu projeto:

analyze my codebase and generate an architecture diagram

A skill detecta automaticamente:

CloudFormation (AWSTemplateFormatVersion, AWS::*)
CDK (cdk.json, constructs)
Terraform (resource "aws_*")
Docker (Dockerfiles, docker-compose)

Invocação explícita

Se a skill não ativar automaticamente:

Use the aws-architecture-diagram skill to create a diagram of my infrastructure

Opções de estilo

Sketch mode: "create a sketch-mode diagram..." (estilo hand-drawn)
Sem legenda: "...without legend"
Export PNG: "...and export as PNG" (requer draw.io desktop)

Exemplos de Diagramas Gerados

Serverless REST API

Diagrama gerado com: "Generate a serverless REST API diagram with Cognito, API Gateway, Lambda and DynamoDB"

Event-Driven Data Pipeline

Event-Driven Pipeline

Diagrama gerado com: "Create an event-driven pipeline with S3, EventBridge, SQS, Lambda and DynamoDB"

Características dos diagramas gerados:

Ícones AWS4 oficiais (48x48) dentro de containers coloridos (120x120)
Step badges numerados em teal (#007CBD)
Título + subtítulo + separador laranja AWS
Cores por categoria (Compute=laranja, Database=roxo, Storage=verde, etc.)
Dark mode adaptativo via light-dark()
Edges com orthogonalEdgeStyle e routing limpo
Formato .drawio editável

Troubleshooting

“No solution found when resolving tool dependencies”

O awslabs.aws-diagram-mcp-server foi descontinuado. Remova-o do mcp.json e use a skill.

Skill não ativa automaticamente

Invoque explicitamente: "Use the aws-architecture-diagram skill to..."

“bunx: command not found”

Instale o bun: curl -fsSL https://bun.sh/install | bash

Diagramas não validam

Verifique se defusedxml está instalado: python3 -c "import defusedxml; print('OK')"

Referências

Tutorial original AWS (desatualizado) — referência que motivou este post
awslabs/agent-plugins — repositório oficial dos plugins
Plugin deploy-on-aws — contém a skill de diagramas
Kiro CLI — documentação oficial
MCP Protocol — especificação do protocolo

Conclusão

A migração do MCP server para Agent Skills representa uma evolução significativa:

Diagramas editáveis em vez de imagens estáticas
Ícones oficiais AWS4 sempre atualizados
Dark mode nativo
Validação XML automática
Preview no browser via app.diagrams.net

Se você encontrou o tutorial da AWS e se deparou com o erro de pacote descontinuado, agora sabe o caminho correto. A nova abordagem é mais poderosa e produz resultados profissionais que podem ser editados e refinados no draw.io.

Este post foi escrito após encontrar o tutorial oficial da AWS desatualizado e realizar as correções necessárias para funcionar com a versão atual das ferramentas.

O que mudou?#

Pré-requisitos#

Instalação Passo a Passo#

1. Instalar dependências base#

2. Instalar o plugin deploy-on-aws#

3. Corrigir estrutura de diretórios (se necessário)#

4. Configurar MCP Servers#

5. Remover o server descontinuado (se existir)#

Como Usar#

Modo Brainstorm (do zero)#

Modo Análise (de código existente)#

Invocação explícita#

Opções de estilo#

Exemplos de Diagramas Gerados#

Serverless REST API#

Event-Driven Data Pipeline#

Características dos diagramas gerados:#

Troubleshooting#

“No solution found when resolving tool dependencies”#

Skill não ativa automaticamente#

“bunx: command not found”#

Diagramas não validam#

Referências#

Conclusão#