# solution-architecture-mcp-toolkit Toolkit MCP bilíngue para ADRs, modelagem de ameaças e revisões Well-Architected com governança. - 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/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-05-16T01:11:20Z --- solution-architecture-mcp-toolkit é uma CLI em Python e biblioteca de templates que codifica práticas reais de arquitetura — ADRs, revisões AWS Well-Architected, modelagem de ameaças, workflows de custo e risco — em ferramentas compatíveis com MCP para que agentes de IA acelerem o trabalho sem contornar a governança. ## O que é este projeto e por que o construí A maioria dos workflows de arquitetura assistidos por IA hoje se resume a colar um diagrama numa janela de chat e pedir opiniões. Essa abordagem produz texto, não decisões — e não deixa trilha de auditoria, revisão de segurança, justificativa de custo nem responsabilidade. Este toolkit adota uma posição diferente: a disciplina de arquitetura deve ser codificada nas próprias ferramentas, não deixada à qualidade de um prompt. O projeto encapsula práticas consolidadas — Architecture Decision Records (ADRs), os cinco pilares do AWS Well-Architected Framework, modelagem de ameaças no estilo STRIDE e checklists de custo/risco — em uma CLI (`sa-toolkit`) e um conjunto de definições de ferramentas compatíveis com MCP que um agente de IA pode invocar com estrutura e retornar saída estruturada. O repositório é também um artefato de portfólio. É bilíngue (inglês e português), documentado em padrões de produção e implantado como frontend estático no Vercel em [mcp-toolkit.moretes.com](https://mcp-toolkit.moretes.com). O stack é intencionalmente enxuto: Python para a CLI e lógica de ferramentas, HTML/CSS/JavaScript para o frontend, sem dependências pesadas de framework que obscureceriam os conceitos de arquitetura demonstrados. ## O que o toolkit cobre - **Geração de ADR** — comando CLI para criar um Architecture Decision Record estruturado com título, contexto, decisão e consequências, pronto para commit. - **Checklist Well-Architected AWS** — workflow de revisão interativo cobrindo os cinco pilares (Excelência Operacional, Segurança, Confiabilidade, Eficiência de Performance, Otimização de Custos). - **Prompts e templates de modelagem de ameaças** — entradas estruturadas para análise no estilo STRIDE que produzem saídas consistentes e revisáveis. - **Workflows de revisão de custo e risco** — templates reutilizáveis que exigem justificativa explícita de custo e reconhecimento de risco nos artefatos de arquitetura. - **Design de ferramentas compatíveis com MCP** — as definições de ferramentas seguem convenções MCP para que possam ser invocadas por agentes de IA com entrada/saída estruturada. - **Frontend estático bilíngue no Vercel** — superfície de portfólio que documenta o toolkit, implantada via GitFlow com segredos Vercel e pipeline de segurança descrito em OPERATIONS.md. ## Como o toolkit se encaixa Um desenvolvedor ou agente de IA invoca a CLI, que roteia para módulos de ferramentas. Cada módulo produz saída estruturada (arquivos ADR, relatórios de checklist, documentos de modelagem de ameaças). O frontend no Vercel expõe o portfólio; o pacote Python é instalado e testado de forma independente. ### 👤 Caller - Architect or Developer (user) - AI Agent (MCP client) (ai) ### 💻 CLI Layer - sa-toolkit CLI entry point (compute) ### 🔧 Tool Modules - ADR Tool adr --title --context --decision (compute) - Well-Architected Checklist Tool (compute) - Threat Model Prompts & Templates (security) - Cost & Risk Review Workflow (compute) ### 📄 Outputs - ADR Markdown File (storage) - Checklist / Review Report (storage) - Threat Model Document (storage) ### 🌐 Frontend - Vercel mcp-toolkit.moretes.com (frontend) ### 🔁 CI/CD - GitFlow + Security Pipeline (ci) ### Fluxos - human -> cli: invoca - agent -> cli: chamada MCP - cli -> adr: roteia - cli -> wa: roteia - cli -> threat: roteia - cli -> cost: roteia - adr -> adr_file: escreve - wa -> report: escreve - threat -> threatdoc: escreve - cost -> report: anexa - ci -> vercel: implanta - human -> vercel: navega portfólio ## Instalando e usando o toolkit 1. **Clone o repositório** — Comece clonando localmente. O repositório contém tanto o pacote Python quanto o frontend em `frontend/`. 2. **Instale o pacote Python e o executor de testes** — Execute `python -m pip install -e . pytest` na raiz do repositório. O flag `-e` instala em modo editável para que alterações nos módulos de ferramentas sejam refletidas imediatamente. 3. **Execute a revisão Well-Architected** — Execute `sa-toolkit well-architected` para iniciar um checklist interativo cobrindo os cinco pilares do AWS Well-Architected. A saída é estruturada e adequada para commit como artefato de revisão. 4. **Gere um ADR** — Use `sa-toolkit adr --title "Use Amazon EventBridge" --context "Need decoupling" --decision "Adopt EventBridge"` para criar um arquivo markdown ADR completo. Forneça seu próprio título, contexto e decisão. 5. **Execute a suíte de testes** — Execute `pytest -q` para verificar os módulos de ferramentas. Mantenha verde antes de commitar; o pipeline de segurança em OPERATIONS.md executa a mesma suíte no push. 6. **Build e deploy do frontend (opcional)** — Entre no diretório `frontend/`, execute `npm ci` para instalar dependências, `npm run lint` para verificar qualidade do código e `npm run build` para produzir o bundle estático. Implante no Vercel seguindo as instruções de segredos e GitFlow em OPERATIONS.md. _Quickstart local completo — instalar, gerar ADR, executar revisão Well-Architected, testar_ ```bash # 1. Clone git clone https://github.com/fernandofatech/solution-architecture-mcp-toolkit.git cd solution-architecture-mcp-toolkit # 2. Install Python package (editable) + pytest python -m pip install -e . pytest # 3. Generate an Architecture Decision Record sa-toolkit adr \ --title "Use Amazon EventBridge" \ --context "Need decoupling between order service and fulfillment" \ --decision "Adopt EventBridge as the event bus" # 4. Run the Well-Architected checklist sa-toolkit well-architected # 5. Verify everything passes pytest -q # --- Frontend (optional) --- cd frontend npm ci npm run lint npm run build ``` ## Como funciona: design de ferramentas MCP e codificação de governança A ideia central é que a governança de arquitetura deve residir na ferramenta, não no prompt. Cada capacidade do `sa-toolkit` é estruturada como uma definição de ferramenta compatível com MCP: aceita entradas tipadas e nomeadas, as valida e produz uma saída determinística e estruturada que pode ser armazenada, comparada, revisada e auditada. Para ADRs, a ferramenta impõe os campos mínimos que tornam um registro de decisão útil — título, contexto, decisão e consequências — em vez de aceitar texto livre. Para a revisão Well-Architected, a ferramenta percorre perguntas pilar a pilar e registra respostas em um formato que remete à documentação do próprio framework da AWS. Para modelagem de ameaças, os templates guiam o analista pelas categorias de ameaças sistematicamente. Esse design significa que um agente de IA chamando essas ferramentas via MCP obtém a mesma saída estruturada que um humano obteria da CLI. O agente não pode pular campos do ADR, não pode produzir uma revisão Well-Architected que omita um pilar, e não pode gerar um modelo de ameaças sem os prompts estruturais. A governança é aplicada na fronteira da ferramenta, não no nível da conversa. O pacote Python é instalado com `pip install -e .`, que registra o entry point `sa-toolkit`. O frontend é um site estático separado e com poucas dependências em `frontend/` que serve como superfície de portfólio. As duas responsabilidades são deliberadamente desacopladas. > **Por que MCP em vez de prompts simples:** MCP (Model Context Protocol) permite definir ferramentas com schemas tipados que um agente de IA chama explicitamente, em vez de inferir intenção de texto livre. Para trabalho de arquitetura isso importa: uma ferramenta que requer `--title`, `--context` e `--decision` não pode produzir um ADR sem esses campos. Um prompt pode. O toolkit usa convenções MCP precisamente porque artefatos de arquitetura precisam ser completos e consistentes, não apenas plausíveis. ## Perguntas comuns ### Preciso de um agente de IA para usar isso? Posso usar a CLI de forma independente? Nenhum agente de IA é necessário. A CLI funciona completamente de forma independente — `sa-toolkit adr` e `sa-toolkit well-architected` são úteis por si sós para qualquer arquiteto que queira saídas estruturadas e commitáveis. O design compatível com MCP está disponível se você quiser integrar as ferramentas a um workflow de agente, mas não é pré-requisito. ### Isso é específico para AWS? O checklist Well-Architected é específico para AWS — mapeia para os cinco pilares do AWS Well-Architected Framework. A ferramenta de ADR, templates de modelagem de ameaças e workflows de custo/risco são agnósticos de nuvem e se aplicam a qualquer contexto de arquitetura. Os tópicos do repositório incluem AWS porque é minha plataforma principal, não porque o toolkit inteiro exige isso. ### Qual versão do Python é necessária? O README não especifica uma versão mínima explicitamente. Dadas as convenções de tooling e o uso de empacotamento padrão `pip install -e .`, Python 3.9+ é uma suposição segura. Verifique `pyproject.toml` ou `setup.py` no repositório para a restrição declarada. ### Como faço o deploy do frontend no Vercel? Faça o build localmente com `npm ci && npm run build` dentro de `frontend/`. Para deploy no Vercel, a estratégia de branching GitFlow, segredos necessários e o pipeline de segurança estão documentados em OPERATIONS.md na raiz do repositório. O site já está disponível em mcp-toolkit.moretes.com como referência. ## Para quem é e quando usar Este toolkit é para arquitetos de soluções, engenheiros de plataforma e engenheiros sênior que querem usar ferramentas de IA sem abrir mão da disciplina de documentação e governança que tornam as decisões de arquitetura rastreáveis e defensáveis. Se seu workflow atual de arquitetura assistida por IA produz transcrições de chat em vez de ADRs, pula revisões Well-Architected ou trata modelagem de ameaças como opcional, este repositório oferece uma alternativa concreta. É também uma referência de portfólio para quem avalia como projetar ferramentas compatíveis com MCP que codificam conhecimento de domínio em vez de delegá-lo inteiramente à inferência do modelo. A documentação bilíngue (inglês e português) e o deploy de produção no Vercel fazem dele um exemplo completo e inspecionável, não apenas um esboço. Não é adequado se você precisa de um SaaS totalmente hospedado, uma experiência GUI-first ou integração profunda com uma plataforma de IA específica pronta para uso. É um toolkit — opinativo, estruturado e deliberadamente mínimo — que você estende e integra ao seu próprio workflow. ## Links e referências - [GitHub — fernandofatech/solution-architecture-mcp-toolkit](https://github.com/fernandofatech/solution-architecture-mcp-toolkit) - [Live site — mcp-toolkit.moretes.com](https://mcp-toolkit.moretes.com) - [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html) - [Model Context Protocol (MCP) specification](https://modelcontextprotocol.io/) - [Architecture Decision Records — Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - [Fernando Francisco Azevedo — author portfolio](https://fernando.moretes.com) ## Links - [GitHub repository](https://github.com/fernandofatech/solution-architecture-mcp-toolkit) - [Homepage](https://mcp-toolkit.moretes.com)