mcp-aws-solution-architect

A pergunta que me levou a escrever isso não foi "dá para um assistente desenhar arquitetura?" — foi "que parte do meu dia de arquiteto é repetitiva o suficiente para virar função com assinatura?". Depois de anos desenhando plataformas sobre AWS, a resposta veio rápido: o rascunho do diagrama Mermaid, a estimativa de custo mensal de guardanapo, a passada pelos seis pilares do Well-Architected antes da revisão formal e o ADR que ninguém quer formatar. Nenhuma dessas tarefas exige criatividade; todas exigem consistência.

O Model Context Protocol resolve o encaixe: em vez de colar o mesmo prompt em cada cliente, o servidor publica as ferramentas com esquema tipado e o cliente — Claude Desktop, Cursor, Cline, Continue ou um agente próprio — descobre e chama. Deterministic by default: a resposta sai de um catálogo de serviços e de uma tabela de preços embutidos, sem chamada a modelo nenhum. Isso significa que o servidor roda offline, é coberto por pytest e devolve o mesmo resultado para a mesma entrada. O Amazon Bedrock entra como opção por ferramenta, para enriquecer a saída quando você quiser — não como dependência para existir.

Registro: este é um repositório de portfólio. O que ele demonstra é a forma de construir uma ferramenta MCP com higiene de produção — tipagem, testes, esteira de segurança — mais do que um catálogo AWS exaustivo. Trate o catálogo como ponto de partida para o seu, não como fonte final.

O fluxo é curto de propósito. O cliente sobe o processo mcp-aws-sa e conversa por stdio — o transporte padrão do MCP. O servidor anuncia as cinco ferramentas com esquema de entrada; o cliente decide, a partir da conversa, quando chamar cada uma. No exemplo do README — backend de jogo com 50k DAU — o encadeamento acontece porque a saída de uma ferramenta é entrada plausível da próxima, não porque o servidor orquestra algo.

Camada de ferramentas: cada tool é uma função tipada em src/mcp_aws_sa/, lendo do catálogo de serviços e da tabela de preços versionados junto com o código. Sem estado, sem rede. É o que permite cobrir cada ferramenta com teste unitário e rodar mypy sem exceções — o teste compara saída com fixture, não com resposta de modelo.

Bedrock opcional: a linha tracejada do diagrama. Quando você liga, a ferramenta usa Claude ou Nova via Amazon Bedrock para escrever rationale mais rico ou um diagrama menos genérico. O custo aparece só nesse caminho, e é custo por invocação — meça antes de deixar ligado num agente que roda em loop, porque um maxIterations esquecido vira fatura.

Layout: src/mcp_aws_sa/ (pacote: server, tools, data), tests/ (pytest), docs/ (MkDocs Material publicado no GitHub Pages), frontend/ (landing estática sem dependência, na Vercel), .github/workflows/ (CI e deploy da documentação).

Se a ferramenta vai sugerir arquitetura para outras pessoas, o repositório precisa mostrar a própria higiene. Python: Ruff, mypy e pytest em cada push. Frontend: lint, build estático e npm audit. Docs: build estrito do MkDocs — link quebrado derruba o job — e deploy no GitHub Pages. Segurança: CodeQL, pip-audit, dependency review, Trivy no filesystem e Gitleaks para segredo vazado. Manutenção: Dependabot em três frentes — GitHub Actions, dependências Python e dependências do frontend. Vercel: preview por PR e produção pela integração Git, sem token de deploy guardado no repositório.

A lição por trás disso: o custo de uma ferramenta de portfólio não é escrevê-la — é mantê-la instalável daqui a dois anos, quando o SDK do MCP mudou de versão e uma dependência transitiva ganhou CVE. Dependabot mais pip-audit transformam esse dia em PR automático, e não em surpresa. Commits seguem Conventional Commits, o que deixa o changelog derivável em vez de escrito à mão.