# solution-architecture-mcp-toolkit

Ferramentas MCP e templates que encodam disciplina de arquitetura — ADR, threat model, Well-Architected.

- 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-08T20:45:31Z

---

Um toolkit Python com CLI, templates e desenho de ferramentas compatíveis com MCP para que um agente de IA ajude a produzir ADRs, checklists Well-Architected e threat models sem abrir mão de rastreabilidade e responsabilidade humana.

## O que é e por que existe

Este repositório nasceu de uma pergunta que ouço há anos em revisão de arquitetura: "o agente já escreveu, por que eu ainda preciso decidir?" A resposta é que um agente escreve rápido, mas não assina. Quem responde pela decisão em auditoria, no incidente ou na renovação de contrato é uma pessoa — e essa pessoa precisa de um registro que diga o que foi decidido, em qual contexto e com quais alternativas descartadas.

O toolkit encoda essa disciplina em ferramentas reutilizáveis: Architecture Decision Records, checklists do AWS Well-Architected, prompts e templates de threat modeling, fluxos de revisão de custo e risco, e um desenho de ferramentas compatível com MCP (Model Context Protocol) para assistentes de arquitetura. A ideia não é substituir o trabalho do arquiteto por chat genérico — é dar ao agente uma interface estreita e previsível, onde cada saída já nasce no formato que a governança exige.

**O que está no repositório:** um pacote Python instalável que expõe o comando `sa-toolkit`, uma suíte de testes em `pytest`, um frontend estático em HTML/CSS/JavaScript publicado na Vercel em `mcp-toolkit.moretes.com`, documentação em `docs/architecture.md` e um `OPERATIONS.md` com GitFlow, segredos da Vercel e o pipeline de segurança. O código de aplicação é Python; HTML aparece como linguagem principal porque o frontend pesa mais em bytes, não em lógica.

## O que o toolkit cobre

- **ADR via CLI:** `sa-toolkit adr --title --context --decision` gera um registro de decisão com os campos mínimos que uma auditoria pede.
- **Checklist Well-Architected:** `sa-toolkit well-architected` imprime a lista de verificação dos pilares para revisar antes de aprovar um desenho.
- **Threat modeling:** prompts e templates para que o agente levante ameaças no mesmo formato em todo projeto, em vez de uma conversa solta por vez.
- **Revisão de custo e risco:** fluxos que forçam a pergunta de manutenção — quanto custa operar isso por anos, não só subir.
- **Desenho de ferramentas MCP:** contratos de tool pensados para assistentes de arquitetura, com entrada e saída explícitas.
- **Frontend estático na Vercel:** superfície de portfólio sem framework pesado, com `npm ci`, `lint` e `build` como único ciclo.

## Como as peças se encaixam

O arquiteto (ou um agente de IA via ferramenta MCP) chama a CLI Python; a CLI aplica os templates e devolve artefatos versionáveis. O frontend é uma superfície separada, publicada na Vercel.

### 🐍 Python — sa-toolkit

- CLI `sa-toolkit` (compute)
- Ferramentas MCP contratos de tool (ai)
- Templates ADR · WA · threat model (data)
- pytest suíte de testes (ci)

### 📄 Artefatos

- ADR markdown versionado (storage)
- Checklist Well-Architected (storage)
- Threat model ameaças e mitigação (security)

### ▲ Vercel — frontend

- Site estático HTML/CSS/JS (frontend)

### Fluxos

- architect -> cli: executa comandos
- agent -> tools: chama tool
- tools -> cli: mesma lógica
- cli -> templates: aplica
- cli -> adr: gera
- cli -> checklist: imprime
- cli -> threat: estrutura
- tests -> cli: valida
- architect -> frontend: consulta docs

## Instalar e usar

1. **Clone e instale em modo editável** — `git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit && cd app-solution-architecture-mcp-toolkit && python -m pip install -e . pytest`. O `-e` aponta o pacote para o diretório de trabalho — edite um template e o comando reflete na hora, sem reinstalar.

2. **Rode o checklist Well-Architected** — `sa-toolkit well-architected` imprime a lista de verificação. Use antes de aprovar um desenho: é mais barato responder a cada item agora do que descobrir o pilar ignorado no primeiro incidente.

3. **Gere um ADR** — `sa-toolkit adr --title "Use Amazon EventBridge" --context "Need decoupling" --decision "Adopt EventBridge"`. Os três campos são o mínimo: título, contexto e decisão. Commit o resultado junto com o código que ele justifica.

4. **Confirme com os testes** — `pytest -q`. Se você mudou um template, os testes são o que impede uma saída quebrada de chegar ao agente em silêncio.

5. **Frontend (opcional)** — `cd frontend && npm ci && npm run lint && npm run build`. É a superfície estática publicada na Vercel; `OPERATIONS.md` documenta segredos e GitFlow.

_Quickstart — do clone ao primeiro ADR_

```bash
git clone https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit
cd app-solution-architecture-mcp-toolkit

# instala o pacote em modo editável + pytest
python -m pip install -e . pytest

# checklist dos pilares Well-Architected
sa-toolkit well-architected

# um ADR com os três campos mínimos
sa-toolkit adr \
  --title "Use Amazon EventBridge" \
  --context "Need decoupling" \
  --decision "Adopt EventBridge"

# valida templates e CLI
pytest -q

# frontend estático (Vercel)
cd frontend && npm ci && npm run lint && npm run build
```

## Como funciona por dentro

**A CLI é a única porta:** `sa-toolkit` é um entry point Python instalado pelo `pip install -e .`. Cada subcomando — `adr`, `well-architected` — recebe argumentos explícitos e devolve texto pronto para ir ao repositório. Não há estado, não há banco, não há chamada de rede; o que entra pelos flags é tudo que a ferramenta sabe.

**Templates são a fonte de verdade:** ADR, checklist e threat model vivem como templates no pacote. A CLI preenche campos, não inventa seções. Isso importa por uma razão prática: quando o formato do ADR muda — um campo novo de compliance, por exemplo — muda num lugar só, e todo agente que usa a ferramenta passa a produzir o formato novo sem retreinar nada.

**Desenho MCP em cima da mesma lógica:** a proposta de ferramenta compatível com MCP expõe as mesmas operações da CLI com contrato de entrada e saída definido. O agente não recebe "escreva um ADR" como instrução livre; recebe uma tool com parâmetros nomeados. A diferença aparece na revisão: saída estruturada é comparável entre projetos, saída de chat não.

**Testes guardam o contrato:** `pytest -q` cobre CLI e templates. Sem isso, um template editado com erro de formatação chegaria ao agente e viraria ADR quebrado em silêncio — e ADR quebrado é pior que ADR ausente, porque parece que existe.

**Frontend desacoplado:** o site em `frontend/` é HTML/CSS/JS sem framework, com `npm ci`, `lint` e `build` como único ciclo. Não compartilha código com o pacote Python; é documentação e portfólio, publicado na Vercel pela integração Git.

> **O que este repositório não é:** Não é um servidor MCP pronto para plugar no seu cliente e esquecer, e não é um revisor que aprova arquitetura sozinho. Os templates dão formato; a decisão continua sendo sua. Se o agente devolver um ADR sem alternativas descartadas ou um threat model sem mitigação atribuída a alguém, o artefato está incompleto — trate como rascunho, não como registro.

## Por que encodar prática em ferramenta

Depois de anos revisando desenhos de sistemas financeiros, o defeito que mais vi não foi decisão errada — foi decisão sem registro. O sistema entra em produção, o time muda, e dois anos depois ninguém sabe por que a fila é FIFO ou por que o banco é multi-região. O custo dessa amnésia não é o de escrever o ADR que faltou; é o de refazer a análise inteira sob pressão de incidente.

Agentes de IA pioram ou resolvem isso, dependendo de como entram. Entram como chat livre, e o resultado é prosa convincente que ninguém consegue comparar com o projeto anterior. Entram como ferramenta com contrato, e cada saída já traz título, contexto, decisão e consequências no mesmo lugar de sempre.

**Traceabilidade:** ADR gerado pela CLI vai para o git ao lado do código. O `git blame` responde quem decidiu e quando.

**Revisão de segurança:** threat model no template padrão é comparável entre projetos; o revisor sabe onde procurar a mitigação que falta.

**Custo como manutenção:** o fluxo de revisão de custo pergunta o que a escolha custa por ano de operação — não o que custa no mês do lançamento.

A lição por trás do repositório: ferramenta estreita produz artefato auditável; chat largo produz texto que parece artefato.

## Perguntas frequentes

### Preciso de credenciais AWS para usar?

Não. A CLI não chama nenhuma API AWS; o checklist Well-Architected é conhecimento encodado em template, não uma consulta ao serviço Well-Architected Tool.

### Funciona com qual cliente MCP?

O repositório documenta o desenho das ferramentas compatíveis com MCP; a integração com um cliente específico depende de você expor a CLI como servidor. Leia `docs/architecture.md` antes de assumir que basta apontar o cliente.

### Por que HTML aparece como linguagem principal?

O frontend estático em `frontend/` pesa mais em bytes que o pacote Python. A lógica está em Python; o HTML é a superfície de portfólio na Vercel.

### Posso trocar o formato do ADR?

Sim — edite o template no pacote e rode `pytest -q`. Com `pip install -e .` a mudança vale na hora. Mantenha os testes passando ou a saída quebrada chega ao agente sem aviso.

## Referências

- [fernandofatech/app-solution-architecture-mcp-toolkit (GitHub)](https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit)
- [Solution Architecture MCP Toolkit — site (Vercel)](https://mcp-toolkit.moretes.com)
- [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html)
- [Model Context Protocol — specification](https://modelcontextprotocol.io/)

## Quando usar

Use quando: você já escreve ADRs e threat models à mão, quer que um agente de IA produza o primeiro rascunho no seu formato, e precisa que o resultado seja versionável e comparável entre projetos. Também serve como ponto de partida se você está desenhando suas próprias ferramentas MCP e quer um exemplo de contrato estreito em vez de chat livre. Não use se espera um servidor MCP pronto ou um revisor automático — o toolkit dá formato e disciplina; a decisão e a assinatura continuam com você.

## Links

- [GitHub repository](https://github.com/fernandofatech/app-solution-architecture-mcp-toolkit)
- [Homepage](https://mcp-toolkit.moretes.com)