# mcp-aws-solution-architect

Servidor MCP que dá ao seu assistente as cinco tarefas repetitivas do arquiteto 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-08T20:43:44Z

---

Um servidor MCP em Python que expõe cinco tarefas repetitivas do arquiteto de soluções AWS — sugerir serviços, desenhar diagrama, estimar custo, revisar pelo Well-Architected e formatar ADR — como ferramentas tipadas que Claude Desktop, Cursor ou qualquer agente chama, sem depender de LLM para rodar.

## Por que existe

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.

## 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 — o porquê, não só o nome.
- `generate_architecture_diagram`: gera um diagrama Mermaid para os padrões comuns — web app, RAG, event-driven, batch.
- `estimate_cost`: custo mensal aproximado a partir de itens `{service, usage}`, contra uma tabela de preços embutida.
- `review_well_architected`: passada leve pelos seis pilares, devolvendo findings e recomendações.
- `generate_adr`: formata um Architecture Decision Record no estilo MADR a partir de contexto, opções, decisão e consequências.

## Como uma chamada atravessa o servidor

O cliente MCP sobe o processo e conversa por stdio. Cada ferramenta lê dados versionados junto com o código; o Bedrock é um caminho opcional e tracejado — o único que custa por invocação.

### 💻 Cliente MCP

- Claude Desktop / Cursor / Agent MCP client (user)

### 🐍 mcp-aws-sa — processo local

- mcp-aws-sa stdio transport (compute)
- Tools layer 5 typed tools (compute)
- Service catalog embedded JSON (data)
- Pricing table embedded (data)

### 🟧 AWS — opcional

- Amazon Bedrock Claude / Nova (ai)

### Fluxos

- client -> server: stdio — tools/list, tools/call
- server -> tools: despacha por nome
- tools -> catalog: suggest_services, review
- tools -> pricing: estimate_cost
- tools -> bedrock: enriquecimento opcional

## Instalar e ligar no cliente

1. **Clone e instale em um venv (Python 3.11+)** — `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]"`. O extra `[dev]` traz Ruff, mypy e pytest — você vai querer os três antes de tocar no código.

2. **Suba o servidor** — `mcp-aws-sa`. O transporte é stdio: nenhuma porta abre, nenhum TLS para gerenciar. O processo espera o cliente falar; rodar direto no terminal só confirma que o entry point instalou.

3. **Registre no Claude Desktop** — Edite `~/Library/Application Support/Claude/claude_desktop_config.json` com o bloco `mcpServers` abaixo e reinicie o app. Cursor, Cline e Continue usam o mesmo formato em outro arquivo.

4. **Teste com um pedido encadeado** — Peça: "Sugira serviços AWS para um backend de jogo multiplayer em tempo real com jogadores globais. Depois desenhe um diagrama Mermaid e estime o custo mensal para 50k DAU." O assistente chama `suggest_services` → `generate_architecture_diagram` → `estimate_cost` sozinho.

5. **Rode as verificações antes de alterar qualquer coisa** — `ruff check . && mypy src && pytest`. É a mesma tríade do CI — se passa local, passa no push.

_claude_desktop_config.json — registro do servidor_

```json
{
  "mcpServers": {
    "aws-solution-architect": {
      "command": "mcp-aws-sa",
      "args": []
    }
  }
}
```

## Como funciona por dentro

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).

> **Onde o determinismo cobra o preço:** `estimate_cost` lê uma tabela de preços embutida — e tabela embutida envelhece. Preço muda por região, por tier e por anúncio de re:Invent. Use o número como ordem de grandeza para decidir entre duas arquiteturas; valide no AWS Pricing Calculator antes de colocar em proposta. O mesmo vale para `review_well_architected`: é uma passada leve pelos seis pilares, não substitui o Well-Architected Review formal com a ferramenta oficial e o time na sala.

## O que a esteira garante

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.

## Perguntas que recebo

### Preciso de conta AWS para usar?

Não. Sem o enriquecimento via Bedrock, tudo roda local a partir do catálogo e da tabela embutidos. Credenciais só entram se você ligar o caminho tracejado — e aí valem as regras de sempre: perfil dedicado, região explícita, sem chave estática no config do cliente.

### Funciona com Cursor, Cline ou Continue?

Sim. Qualquer cliente MCP com transporte stdio sobe o mesmo comando `mcp-aws-sa`; o que muda é o arquivo de configuração de cada um, não o formato do bloco.

### Como adiciono uma ferramenta?

Nova função tipada na camada de tools, um teste em `tests/` comparando com fixture e uma página em `docs/tools/`. Mantenha dados no catálogo, não em `if` dentro da função — é o que preserva o determinismo e deixa o mypy útil.

## Referências

- [fernando-moretes/app-mcp-aws-solution-architect — GitHub](https://github.com/fernando-moretes/app-mcp-aws-solution-architect)
- [Project docs (MkDocs, GitHub Pages)](https://fernando-moretes.github.io/app-mcp-aws-solution-architect/)
- [Model Context Protocol — specification](https://modelcontextprotocol.io/)
- [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html)
- [MADR — Markdown Architectural Decision Records](https://adr.github.io/madr/)

## Quando usar

Use quando: você já trabalha num cliente MCP, quer rascunho consistente de diagrama, custo e ADR no meio da conversa, e quer isso sem custo por token. Não use como fonte de preço final nem como substituto do Well-Architected Review formal — a tabela embutida envelhece e a revisão é leve por desenho. Para quem: arquitetos que querem ver como se estrutura um servidor MCP com tipagem, testes e esteira de segurança; ou quem quer um esqueleto para colocar o próprio catálogo de serviços e padrões no lugar do meu.

## Links

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