# solution-architecture-mcp-toolkit ADR, Well-Architected e threat model como ferramentas que um agente de IA chama - URL: https://fernando.moretes.com/open-source/solution-architecture-mcp-toolkit - Markdown: https://fernando.moretes.com/open-source/solution-architecture-mcp-toolkit/guide.md?lang=pt - GitHub: https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit - Homepage: https://mcp-toolkit.moretes.com - Language: HTML - Topics: adr, ai, ai-tools, architecture-decision-records, aws, devsecops, mcp, moretes, portfolio, python, solution-architecture, vercel, well-architected - Stars: 1 - Forks: 0 - Updated: 2026-09-29T16:37:05Z --- 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 - **ADR pela CLI:** `sa-toolkit adr` recebe `--title`, `--context` e `--decision` e devolve o registro no formato padrão. - **Checklist do AWS Well-Architected:** `sa-toolkit well-architected` imprime as perguntas de revisão, prontas para rodar antes de um design review. - **Prompts e templates de threat model:** estrutura fixa para a conversa de segurança, que deixa de começar do zero a cada sistema. - **Fluxos de revisão de custo e risco:** o roteiro de perguntas que eu faço antes de aprovar um desenho. - **Desenho de ferramentas compatíveis com MCP:** como expor essas peças a um assistente de arquitetura sem perder a governança. - **Frontend estático para Vercel:** a vitrine pública em `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. ### 🔧 Entrada: CLI e agente - sa-toolkit CLI (compute) - Assistente de IA MCP client (ai) ### 🐍 Pacote Python: templates - ADR title/context/decision (data) - Well-Architected checklist (data) - Threat model prompts + templates (security) - Custo e risco review workflow (data) ### 📤 Saída: artefato revisado - Revisão humana human sign-off (user) - Repositório do projeto docs/adr (storage) ### ▲ Vercel: vitrine - Frontend estático mcp-toolkit.moretes.com (frontend) ### Fluxos - architect -> cli: roda o comando - architect -> agent: pede ajuda - agent -> adr: chama a ferramenta - cli -> adr: gera ADR - cli -> wa: imprime checklist - agent -> threat: usa template - agent -> cost: segue o roteiro - adr -> review: rascunho - threat -> review: rascunho - review -> repo: aprovado e versionado ## Instalar e usar 1. **Clone o repositório**: `git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit.git` e 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 . pytest` instala o pacote, registra o comando `sa-toolkit` no PATH e traz o pytest para a suíte de testes. 3. **Rode o checklist do Well-Architected**: `sa-toolkit well-architected` imprime 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 -q` deve passar limpo. Se você alterar um template, é aqui que descobre se quebrou o formato que os outros comandos esperam. _Quickstart completo: pacote Python e frontend_ ```bash # 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 build ``` ## Como 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 - [GitHub: fernandofatech/app-solution-architecture-mcp-toolkit](https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit) - [Solution Architecture MCP Toolkit (live)](https://mcp-toolkit.moretes.com) - [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) - [Model Context Protocol](https://modelcontextprotocol.io) ## 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. ## Links - [GitHub repository](https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit) - [Homepage](https://mcp-toolkit.moretes.com)