# mcp-aws-solution-architect Servidor MCP que transforma qualquer assistente IA em copiloto para arquitetos 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/fernandofatech/mcp-aws-solution-architect - Homepage: https://mcp-aws.moretes.com - 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-05-16T02:24:59Z --- mcp-aws-solution-architect é um servidor MCP em Python que expõe cinco ferramentas determinísticas — sugestão de serviços, geração de diagramas, estimativa de custos, revisão Well-Architected e criação de ADRs — para qualquer cliente compatível com MCP, como Claude Desktop, Cursor ou agentes customizados. ## Por que este projeto existe Arquitetos de Soluções repetem o mesmo trabalho de modelagem em cada projeto: mapear um caso de uso para os serviços AWS corretos, esboçar um diagrama de arquitetura, verificar conformidade com o Well-Architected Framework, estimar um custo mensal aproximado e redigir um ADR antes que a decisão se perca. Nada disso exige um LLM para ser útil — exige estrutura, consistência e velocidade. Este servidor empacota essas tarefas como **ferramentas MCP invocáveis**. O cliente (Claude Desktop, Cursor, Cline, Continue ou qualquer agente que fale o Model Context Protocol) decide quando invocá-las; o servidor retorna saída estruturada e tipada. Não há dependência oculta de LLM: as ferramentas rodam deterministicamente contra um catálogo de serviços AWS e uma tabela de preços embutidos. Um backend opcional do Amazon Bedrock pode ser conectado para saídas mais ricas e generativas, mas não é necessário para funcionar. O projeto também serve como artefato de portfólio. Tem formato de produção: tipado com mypy, lintado com Ruff, testado com pytest, escaneado com CodeQL, Trivy, Gitleaks e pip-audit, e implantado via GitHub Actions. O site de documentação roda em MkDocs Material; a landing page é um build estático sem dependências implantado no Vercel. ## O que as cinco ferramentas fazem - **suggest_services** — mapeia uma descrição de caso de uso em linguagem natural para uma lista curada de serviços AWS com justificativa para cada escolha. - **generate_architecture_diagram** — gera um diagrama Mermaid para padrões comuns: web app, pipeline RAG, event-driven e processamento em batch. - **estimate_cost** — retorna uma estimativa mensal aproximada a partir de uma lista de itens `{service, usage}` usando uma tabela de preços embutida; sem chamada à API da AWS. - **review_well_architected** — executa uma revisão leve nos seis pilares do Well-Architected Framework e retorna achados com recomendações acionáveis. - **generate_adr** — formata um Architecture Decision Record no estilo MADR a partir de entradas estruturadas: contexto, opções consideradas, decisão tomada e consequências. ## Como uma requisição flui pelo sistema O cliente MCP envia uma chamada de ferramenta via transporte stdio. O servidor roteia para a ferramenta correta, que lê dados locais (catálogo, preços) e opcionalmente chama o Amazon Bedrock antes de retornar a saída estruturada. ### 💻 MCP Client - Claude Desktop Cursor / Cline Custom Agent (user) ### ⚙️ MCP Server - mcp-aws-sa stdio transport (compute) - Tools Layer 5 typed tools (compute) ### 📦 Local Data - Service Catalog + Pricing Table (data) ### ☁️ AWS (optional) - Amazon Bedrock Claude / Nova (ai) ### Fluxos - client -> server: chamada de ferramenta (stdio) - server -> tools: roteia requisição - tools -> catalog: lê catálogo / preços - tools -> bedrock: enriquecimento opcional - tools -> client: saída estruturada ## Instalar e conectar 1. **Clonar e criar um ambiente virtual** — Python 3.11 ou mais recente é necessário. Clone o repositório e isole as dependências em um venv antes de instalar qualquer coisa. 2. **Instalar em modo editável com extras de desenvolvimento** — Executar `pip install -e '.[dev]'` instala o pacote mais Ruff, mypy, pytest e outras ferramentas de desenvolvimento declaradas em `pyproject.toml`. 3. **Iniciar o servidor MCP** — O entry point `mcp-aws-sa` inicia o servidor no transporte stdio. Ele permanece em execução aguardando mensagens de chamada de ferramenta de um cliente conectado. 4. **Registrar o servidor no Claude Desktop** — Edite `~/Library/Application Support/Claude/claude_desktop_config.json` para adicionar a entrada `aws-solution-architect` em `mcpServers`, depois reinicie o Claude Desktop. As cinco ferramentas ficam disponíveis em todas as sessões de chat. 5. **Enviar um prompt multi-ferramenta para verificar** — Peça ao assistente para sugerir serviços, gerar um diagrama e estimar custos para um único cenário. O cliente encadeará as três chamadas de ferramenta automaticamente e retornará a saída consolidada. _Sequência completa de instalação até execução_ ```bash # 1. Clone git clone git@github.com:fernandofatech/mcp-aws-solution-architect.git cd mcp-aws-solution-architect # 2. Virtual environment python -m venv .venv && source .venv/bin/activate # 3. Install (with dev extras for lint/test) pip install -e ".[dev]" # 4. Run the server (stdio transport — keep this terminal open) mcp-aws-sa # 5. In a second terminal: run the test suite pytest # 6. Lint + type-check ruff check . && mypy src/ ``` _Config do Claude Desktop — conectar o servidor em um bloco_ ```json { "mcpServers": { "aws-solution-architect": { "command": "mcp-aws-sa", "args": [] } } } ``` ## Higiene de engenharia e pipeline de CI O repositório é estruturado como um projeto de formato de produção, não um script jogado em uma pasta. O código-fonte fica em `src/mcp_aws_sa/`, o que impõe empacotamento correto. Os testes ficam em `tests/` e rodam com pytest. O diretório `docs/` é um site completo em MkDocs Material que compila de forma estrita e é implantado no GitHub Pages a cada push para a main. O diretório `frontend/` é uma landing page estática sem dependências implantada no Vercel via integração Git, com URLs de preview automáticas em pull requests. O pipeline de CI cobre várias camadas. **Qualidade de código:** Ruff para linting e formatação, mypy para verificação estática de tipos. **Segurança:** CodeQL para SAST, pip-audit para CVEs conhecidos em dependências Python, Trivy para varredura do sistema de arquivos, Gitleaks para detecção de segredos e a action de revisão de dependências do GitHub em cada pull request. **Frontend:** lint npm, verificação de build estático e `npm audit`. **Manutenção:** o Dependabot é configurado separadamente para GitHub Actions, dependências Python e dependências frontend, então atualizações de versão chegam como PRs pequenos e revisáveis em vez de acumular drift. Conventional Commits é adotado, o que mantém o log do git legível por máquina e torna a geração de changelog direta. > **Determinístico por padrão, generativo quando necessário:** Todas as cinco ferramentas rodam sem nenhuma chamada a LLM ou API externa. O catálogo de serviços e os dados de preços estão embutidos no pacote. Isso significa que o servidor inicia instantaneamente, funciona offline e produz saída consistente entre execuções — útil quando você precisa de resultados reproduzíveis em um pipeline de CI ou uma demo que não pode depender de disponibilidade de rede. O Amazon Bedrock é uma camada opcional que você pode habilitar quando uma saída mais rica e contextualizada justifica a latência e o custo. ## Perguntas frequentes ### Isso funciona com clientes além do Claude Desktop? Sim. Qualquer cliente que implemente o Model Context Protocol via transporte stdio funcionará: Cursor, Cline, Continue ou um agente customizado. O servidor não assume nada sobre o cliente além da especificação MCP. ### As estimativas de custo são precisas o suficiente para usar em uma proposta? Não. São valores aproximados de ordem de grandeza de uma tabela de preços estática embutida. Use-os para verificações rápidas e discussões internas, não para compromissos com clientes. Para estimativas precisas, use a Calculadora de Preços da AWS com sua configuração específica. ### Posso adicionar minhas próprias ferramentas? Sim. A camada de ferramentas está em `src/mcp_aws_sa/`. Cada ferramenta é uma função Python tipada registrada no servidor MCP. Adicionar uma nova ferramenta significa escrever a função, registrá-la e adicionar testes. O documento de arquitetura em `ARCHITECTURE.md` cobre os pontos de extensão. ### O que o diretório frontend contém? Uma landing page estática sem dependências (HTML, CSS, JavaScript) implantada no Vercel. É separada do site de documentação MkDocs, que é implantado no GitHub Pages. A landing fica em mcp-aws.moretes.com; a documentação fica na URL do GitHub Pages. ## Para quem é e quando usar Este projeto é diretamente útil se você trabalha como Arquiteto de Soluções ou tech lead e já usa um assistente compatível com MCP no seu fluxo de trabalho diário. As cinco ferramentas cobrem as tarefas de modelagem mais repetitivas — seleção de serviços, diagramação, estimativa de custos, revisão Well-Architected e documentação de decisões — sem exigir que você elabore prompts longos ou lembre detalhes do framework a cada vez. Também é uma referência concreta se você está construindo seu próprio servidor MCP em Python. O projeto demonstra uma configuração completa: ferramentas tipadas, dados embutidos, backend LLM opcional, CI completo com varredura de segurança, site de documentação e landing page estática — tudo conectado e publicamente visível. Não é um substituto para a Calculadora de Preços da AWS, a ferramenta oficial Well-Architected Tool ou uma revisão de arquitetura adequada. As estimativas de custo são aproximadas, os achados do WAR são superficiais e os diagramas são pontos de partida. O valor está na velocidade e estrutura na fase inicial de modelagem, não na precisão no momento da decisão. ## Links - [GitHub — fernandofatech/mcp-aws-solution-architect](https://github.com/fernandofatech/mcp-aws-solution-architect) - [Live site — mcp-aws.moretes.com](https://mcp-aws.moretes.com) - [Project documentation (GitHub Pages)](https://fernandofatech.github.io/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/) - [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) ## Links - [GitHub repository](https://github.com/fernandofatech/mcp-aws-solution-architect) - [Homepage](https://mcp-aws.moretes.com)