# mcp-aws-solution-architect

Servidor MCP bilíngue com 5 ferramentas determinísticas para arquitetura AWS

- URL: https://fernando.moretes.com/open-source/mcp-aws-solution-architect

- Markdown: https://fernando.moretes.com/open-source/mcp-aws-solution-architect/guide.md?lang=pt

- GitHub: https://github.com/fernando-moretes/app-mcp-aws-solution-architect

- Homepage: https://fernando-moretes.github.io/app-mcp-aws-solution-architect/

- Language: Python

- Topics: ai, ai-tools, architecture, aws, claude, github-actions, llm-tools, mcp, model-context-protocol, moretes, portfolio, python, solution-architecture, well-architected

- Stars: 0

- Forks: 0

- Updated: 2026-09-29T16:23:33Z

---

O mcp-aws-solution-architect é um servidor Model Context Protocol em Python que expõe cinco ferramentas de trabalho de arquiteto AWS (sugestão de serviços, diagrama Mermaid, estimativa de custo, revisão Well-Architected e ADR) para qualquer cliente MCP, sem depender de LLM para funcionar.

## Por que este repositório existe

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.

## As cinco ferramentas

- **`suggest_services`:** mapeia a descrição de um caso de uso para uma lista curada de serviços AWS, com a justificativa de cada um.
- **`generate_architecture_diagram`:** gera um diagrama Mermaid para padrões comuns: aplicação web, RAG, event-driven e batch.
- **`estimate_cost`:** estimativa mensal aproximada a partir de uma lista de itens `{service, usage}`, usando a tabela de preços embutida.
- **`review_well_architected`:** revisão leve nos seis pilares do Well-Architected, com achados e recomendações.
- **`generate_adr`:** formata um Architecture Decision Record no estilo MADR a partir de contexto, opções, decisão e consequências.

## Instalar e conectar ao cliente

1. **Pré-requisito**: Python 3.11 ou superior. Nenhuma credencial AWS é necessária para o modo determinístico.

2. **Clonar e instalar a partir do fonte**: Clone o repositório, crie um virtualenv e instale em modo editável com `pip install -e ".[dev]"`. O extra `dev` traz Ruff, mypy e pytest.

3. **Subir o servidor**: Rode `mcp-aws-sa`. O transporte é stdio, o padrão do MCP: o processo fica esperando o cliente na entrada padrão, então parecer "travado" no terminal é o comportamento correto.

4. **Registrar no Claude Desktop**: No macOS, edite `~/Library/Application Support/Claude/claude_desktop_config.json` e adicione a entrada em `mcpServers`. Prefira o caminho absoluto do binário dentro do `.venv`: o Claude Desktop não ativa o seu virtualenv, e um `command` que não está no PATH falha sem mensagem útil.

5. **Reiniciar e testar**: Reinicie o Claude Desktop e peça algo que encadeie as ferramentas, por exemplo: serviços para um backend de jogo multiplayer global, diagrama Mermaid e custo mensal para 50k DAU. O assistente chama `suggest_services`, depois `generate_architecture_diagram`, depois `estimate_cost`.

_Quickstart: instalação, servidor e configuração do cliente_

```bash
git clone https://github.com/fernando-moretes/app-mcp-aws-solution-architect.git
cd app-mcp-aws-solution-architect
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# stdio transport; waits for an MCP client
mcp-aws-sa

# Claude Desktop (macOS):
# ~/Library/Application Support/Claude/claude_desktop_config.json
# {
#   "mcpServers": {
#     "aws-solution-architect": {
#       "command": "/absolute/path/to/.venv/bin/mcp-aws-sa",
#       "args": []
#     }
#   }
# }
```

## Como uma pergunta vira chamada de ferramenta

O cliente MCP conversa com o servidor por stdio. A camada de ferramentas lê o catálogo e a tabela de preços locais; o Bedrock é um caminho opcional.

### 🤖 Cliente MCP

- MCP Client Claude Desktop / Cursor / Cline (frontend)

### 🔧 mcp-aws-sa

- MCP Server stdio transport (compute)
- Tools layer 5 tools (compute)
- Service catalog + pricing table (data)

### 🟧 AWS: opcional

- Amazon Bedrock Claude / Nova (ai)

### Fluxos

- user -> client: pergunta em linguagem natural
- client -> server: tool call via stdio
- server -> tools: despacha
- tools -> catalog: consulta determinística
- tools -> bedrock: saída mais rica (opcional)

## Como funciona por dentro

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.

> **Custo estimado não é orçamento:** O `estimate_cost` usa preços congelados no pacote. Use para comparar ordens de grandeza entre opções, nunca como número final: transferência de dados, região e camadas gratuitas mudam a conta, e a tabela não sabe quando a AWS alterou um preço.

## Engenharia em volta do servidor

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.

## Perguntas frequentes

### Preciso de conta AWS ou de credenciais?

Não no modo padrão. As cinco ferramentas funcionam com dados locais. Credencial só entra em cena se uma ferramenta for estendida para usar o Bedrock.

### Funciona fora do Claude Desktop?

Sim. Qualquer cliente que fale MCP por stdio serve: Cursor, Cline, Continue ou um agente próprio. Muda só onde fica o arquivo de configuração.

### Por que o servidor não aparece no cliente depois de configurado?

Na maioria das vezes o `command` não está no PATH do processo do cliente, que não herda o virtualenv ativo no seu terminal. Troque `mcp-aws-sa` pelo caminho absoluto em `.venv/bin/` e reinicie o cliente.

### Posso adicionar padrões de diagrama ou serviços ao catálogo?

Sim, os dados ficam no próprio pacote em `src/mcp_aws_sa/`. Como a saída é determinística, cada padrão novo deve vir com teste em `tests/` cobrindo a entrada e a saída esperada.

## Referências

- [GitHub: fernando-moretes/app-mcp-aws-solution-architect](https://github.com/fernando-moretes/app-mcp-aws-solution-architect)
- [Documentação do projeto / Project docs](https://fernando-moretes.github.io/app-mcp-aws-solution-architect/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/)
- [AWS Pricing Calculator](https://calculator.aws/)

## Quando usar

Use quando você já trabalha com um assistente compatível com MCP e quer que o rascunho de arquitetura (serviços, diagrama, custo de ordem de grandeza, checagem de pilares e ADR) saia igual para a mesma entrada, sem credencial AWS e sem custo de token na ferramenta. Não use como fonte de preço para proposta nem como substituto de uma revisão Well-Architected formal: ele acelera a primeira hora da conversa, não a decisão final. Se você precisa de saída mais rica e aceita a variabilidade, o ponto de extensão para o Bedrock é o caminho, sabendo que a partir daí entram credencial, custo e teste não determinístico.

## Links

- [GitHub repository](https://github.com/fernando-moretes/app-mcp-aws-solution-architect)
- [Homepage](https://fernando-moretes.github.io/app-mcp-aws-solution-architect/)