solution-architecture-mcp-toolkit
ADR, Well-Architected e threat model como ferramentas que um agente de IA chama
git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit.gitcerca de 4 min · áudio gerado ao tocar
O Solution Architecture MCP Toolkit é um pacote Python com CLI (sa-toolkit) e templates que registram em ferramentas o trabalho repetível do arquiteto: ADR, checklist do Well-Architected, threat model e revisão de custo e risco. Assim um assistente de IA usa essas ferramentas em vez de improvisar em chat genérico.
Por que este repositório existe
A pergunta que me levou a montar este toolkit não foi "a IA consegue escrever um ADR?". Consegue, e escreve rápido. A pergunta foi outra: quem responde por aquela decisão daqui a dois anos, quando alguém abrir o documento para entender por que o sistema está do jeito que está?
Pedir num chat aberto "me ajuda a decidir entre SQS e EventBridge" costuma devolver um texto convincente, sem estrutura fixa, sem contexto registrado e sem dono. Seis meses depois, ninguém acha o raciocínio, e o custo aparece na manutenção: cada decisão sem registro vira uma reunião de arqueologia.
A aposta do repositório é pôr a disciplina dentro da ferramenta. Se o agente só consegue produzir um ADR passando por um template com título, contexto e decisão, o formato deixa de depender da boa vontade de quem escreve o prompt. O mesmo vale para o checklist do Well-Architected e para o threat model: a estrutura vem pronta, a IA acelera o preenchimento e a revisão continua sendo de uma pessoa.
É isso que o README chama de codificar a prática de arquitetura em vez de substituí-la por chat genérico. A IA ganha velocidade, e decisão explícita, rastreabilidade, revisão de segurança, visão de custo e responsabilidade humana continuam na mão de alguém.
O que vem no repositório
sa-toolkit adr recebe --title, --context e --decision e devolve o registro no formato padrão.sa-toolkit well-architected imprime as perguntas de revisão, prontas para rodar antes de um design review.frontend/, com poucas dependências.Como as peças se encaixam
O núcleo é o pacote Python. A CLI e um assistente compatível com MCP consomem os mesmos templates, e a revisão humana fecha o ciclo antes de o artefato ir para o repositório do projeto.
- sa-toolkit · CLI
- Assistente de IA · MCP client
- ADR · title/context/decision
- Well-Architected · checklist
- Threat model · prompts + templates
- Custo e risco · review workflow
- Revisão humana · human sign-off
- Repositório do projeto · docs/adr
- Frontend estático · mcp-toolkit.moretes.com
Instalar e usar
- 1
Clone o repositório
git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit.gite entre no diretório. Use um virtualenv para não misturar com o Python do sistema. - 2
Instale em modo editável
python -m pip install -e . pytestinstala o pacote, registra o comandosa-toolkitno PATH e traz o pytest para a suíte de testes. - 3
Rode o checklist do Well-Architected
sa-toolkit well-architectedimprime as perguntas de revisão. Rode antes do design review, não depois: pergunta respondida tarde vira retrabalho. - 4
Gere um ADR
sa-toolkit adr --title "Use Amazon EventBridge" --context "Need decoupling" --decision "Adopt EventBridge". O resultado é rascunho: complete consequências e alternativas antes de versionar. - 5
Confira com os testes
pytest -qdeve passar limpo. Se você alterar um template, é aqui que descobre se quebrou o formato que os outros comandos esperam.
# Python package + CLI
python -m pip install -e . pytest
sa-toolkit well-architected
sa-toolkit adr --title "Use Amazon EventBridge" \
--context "Need decoupling" \
--decision "Adopt EventBridge"
pytest -q
# Static frontend (Vercel)
cd frontend
npm ci
npm run lint
npm run buildComo funciona por dentro
O repositório tem duas superfícies com papéis bem separados.
Pacote Python: é onde o trabalho acontece. A CLI sa-toolkit expõe subcomandos (adr, well-architected) que leem templates e montam o artefato a partir dos argumentos. Cada ferramenta recebe entrada nomeada e devolve saída num formato previsível, e é por isso que elas servem também para MCP. Um agente que chama adr com title, context e decision não tem como pular o contexto, porque o contrato da ferramenta exige.
Frontend em frontend/: HTML, CSS e JavaScript estáticos, com poucas dependências e deploy na Vercel. É a vitrine pública em mcp-toolkit.moretes.com, sem backend e sem chamada a modelo. Escolhi assim para o custo de manter a página ficar perto de zero: não há servidor para corrigir nem chave para rotacionar.
Testes e operação: pytest -q cobre o pacote, e npm run lint com npm run build cobrem o frontend. O OPERATIONS.md descreve o GitFlow, os segredos da Vercel e a esteira de segurança. Leia antes de abrir PR, porque é ali que está o que a esteira barra.
A documentação de arquitetura do próprio toolkit fica em docs/architecture.md.
O que este toolkit não faz
Ele não toma decisão de arquitetura e não aprova nada. Os comandos geram rascunho estruturado. Um ADR com contexto de três palavras, como o do exemplo, é formato válido e documento inútil. O valor está no que você escreve dentro do template, e a revisão humana é parte do fluxo, não etapa opcional.
Como eu uso no dia a dia
O uso que mais rende não é gerar documento do zero. É padronizar a entrada de uma conversa que já vai acontecer.
Antes de um design review, rodo o checklist do Well-Architected e mando as perguntas junto com o convite. A reunião começa das lacunas, não da apresentação do desenho. Quando sai uma decisão, o ADR é gerado na hora com o contexto discutido, enquanto todo mundo ainda lembra por que a alternativa B perdeu.
Com um agente, a lógica é a mesma, só que com o agente fazendo a chamada. Em vez de pedir "escreve um ADR sobre isso", o assistente chama a ferramenta e o formato chega igual ao do ADR anterior. Isso importa quando o repositório tem 40 ADRs e alguém precisa ler todos numa auditoria: formato consistente é o que faz a leitura caber numa tarde.
O threat model segue o mesmo princípio. O template obriga a passar por cada fronteira de confiança, coisa que um prompt solto esquece com facilidade.
Perguntas frequentes
Preciso de conta AWS para usar?
Não. O pacote gera ADRs, checklists e templates localmente. O foco em AWS está no conteúdo, como as perguntas do Well-Architected e os exemplos com EventBridge, não em chamadas a API.
Ele já é um servidor MCP pronto para plugar?
O README fala em desenho de ferramentas compatíveis com MCP, e a superfície documentada hoje é a CLI sa-toolkit. Antes de configurar num cliente, confira docs/architecture.md para ver como as ferramentas são expostas.
Posso trocar os templates pelos do meu time?
Pode, e esse é o caminho natural. Com instalação editável (pip install -e .), a mudança vale na hora. Rode pytest -q depois para garantir que o formato continua o esperado.
O frontend chama algum modelo de IA?
Não. É estático e serve de vitrine pública. Não há backend nem custo por requisição.
Referências
Para quem é
Use este toolkit quando o seu time já escreve ADR e faz design review, mas cada documento sai num formato diferente, e quando você quer pôr um assistente de IA nesse fluxo sem abrir mão da rastreabilidade. É um bom ponto de partida para quem quer ver como ferramentas MCP podem carregar governança em vez de contorná-la. Se o seu time ainda não decide as coisas por escrito, comece pelo hábito: ferramenta nenhuma substitui alguém disposto a assinar a decisão.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser