mcp-aws-solution-architect

Boa parte do trabalho de arquitetura não é decisão, é modelagem repetitiva: rascunhar o mesmo diagrama de aplicação web pela décima vez, fazer a conta de padaria do custo mensal antes de abrir a calculadora, conferir se o desenho esqueceu algum pilar do Well-Architected, formatar um ADR que ninguém quer formatar.

A pergunta que me levou a escrever este servidor não foi "um LLM consegue fazer isso?". Consegue, mais ou menos. Foi outra: por que eu aceitaria uma resposta diferente para a mesma entrada a cada vez que pergunto? Um diagrama de referência ou uma tabela de preços não precisa de criatividade, precisa de repetibilidade.

Por isso o servidor é determinístico por padrão. Cada ferramenta recebe entrada estruturada e devolve saída estruturada a partir de um catálogo de serviços e de uma tabela de preços embutidos no pacote. O modelo do cliente (Claude Desktop, Cursor, Cline, Continue ou um agente próprio) decide quando chamar a ferramenta; a ferramenta decide o que devolver. O Amazon Bedrock aparece no desenho como extensão opcional para saída mais rica, não como pré-requisito.

O repositório também é peça do meu portfólio público, e trato isso como restrição, não como enfeite: tipado, testado, com CI e varredura de segurança, porque um servidor MCP roda com as permissões do usuário que o configurou.

O código mora em src/mcp_aws_sa/: o servidor, as ferramentas e os dados no mesmo pacote. Essa decisão tem consequência operacional: o catálogo de serviços e a tabela de preços viajam com a versão instalada. Não há chamada de rede no caminho padrão, não há credencial para vazar e a mesma entrada produz a mesma saída, o que torna a suíte de tests/ em pytest significativa de verdade.

O preço disso é explícito. A tabela de preços embutida envelhece. A AWS muda preço, cria dimensão de cobrança nova e diferencia por região; o estimate_cost devolve ordem de grandeza para conversa inicial, não número para colocar em proposta. Para isso continua valendo a calculadora oficial ou o Cost Explorer.

O mesmo vale para o review_well_architected: é uma revisão leve, útil para apontar o pilar esquecido (é quase sempre sustentabilidade ou otimização de custo) antes de uma revisão formal. Não substitui o Well-Architected Tool nem uma conversa com quem vai operar o sistema.

A fronteira entre cliente e servidor é o que torna o desenho simples: o LLM do cliente interpreta a intenção e escolhe a ferramenta; o servidor não interpreta nada, só calcula. Se um dia eu ligar o Bedrock numa ferramenta, a interface externa fica igual e só a implementação interna muda.

O repositório tem três entregáveis, não um. Além do pacote Python, docs/ é um site MkDocs Material publicado no GitHub Pages com a referência de cada ferramenta, e frontend/ é uma landing estática sem dependências, publicada pela integração Git da Vercel.

A automação cobre o que eu cobraria de qualquer coisa que roda na máquina de outra pessoa:

• Python: Ruff, mypy e pytest.
• Frontend: lint, build estático e npm audit.
• Docs: build estrito do MkDocs, que falha em link quebrado.
• Segurança: CodeQL, pip-audit, dependency review, Trivy em modo filesystem e Gitleaks.
• Manutenção: Dependabot para Actions, dependências Python e do frontend.

O motivo do peso em segurança para um projeto de cinco ferramentas é simples: um servidor MCP é código que o assistente executa com as permissões do seu usuário. O custo de manter essa esteira é pequeno comparado ao de explicar por que uma dependência comprometida rodou no notebook de quem confiou no repositório. Os commits seguem Conventional Commits 1.0.0, e o OPERATIONS.md descreve os workflows e os segredos que eles exigem.