# moretes-aws-architect-mcp

MCP de arquitetura: 48 ferramentas determinísticas, zero chamadas a modelo

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

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

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

- Homepage: https://fernando.moretes.com/mcp

- Language: TypeScript

- Topics: aws, claude, codex, kiro, mcp, model-context-protocol, serverless, solution-architecture, typescript

- Stars: 1

- Forks: 0

- Updated: 2026-11-08T11:34:26Z

---

O moretes-aws-architect-mcp é um servidor MCP open source que coloca 48 ferramentas determinísticas de arquitetura e 10 personas de arquiteto dentro do seu agente de código, sem chamar modelo nenhum e sem pedir chave de API.

## Por que este servidor existe

Agente de código é bom para raciocinar e ruim para fazer conta. Peça uma API e ele sugere arquitetura antes de saber o volume, o SLO ou o regime regulatório. Peça um orçamento de latência e ele devolve um número plausível, não um número somado.

A pergunta que me fez escrever isto não foi "o modelo sabe arquitetura?", foi "quem confere o que ele afirmou?". Daí a divisão de responsabilidades: **o modelo do seu cliente raciocina; o servidor devolve cálculos, estruturas, fontes oficiais e lacunas explícitas.** Quando falta um dado, a resposta diz que falta, em vez de inventar.

É o que eu uso para decidir arquitetura no dia a dia, aberto para a comunidade usar, auditar e estender. A licença é MIT, a versão atual é a 0.5.0, roda em Node 22 e 24 e está listado no MCP Registry como `io.github.fernando-moretes/moretes-aws-architect-mcp`.

O escopo cobre o ciclo de uma decisão: levantamento de requisitos, ADRs, cálculos (latência, por exemplo), apoio a revisão (como a revisão de `terraform plan`) e consulta à documentação oficial da AWS. O mesmo motor responde dentro do agente e, offline, como CLI no pipeline.

## O que ele entrega

- **48 ferramentas determinísticas:** mesma entrada, mesma saída. Nenhuma depende de temperatura de modelo.
- **10 personas de arquiteto:** `architect_panel` reúne pontos de vista diferentes sobre a mesma proposta.
- **Zero chamadas a modelo e zero chave de API:** o servidor nunca acessa a sua conta AWS pela internet.
- **Dois transportes:** HTTP remoto em `https://mcp.moretes.com/mcp` ou stdio local via `dist/stdio.js`.
- **Modo CLI para pipeline:** saída em Markdown, JSON ou SARIF e exit code por severidade.
- **Oito clientes documentados:** Claude Code, Codex, Kiro, Cursor, VS Code, Gemini CLI, Amazon Q e Claude Desktop.

## Onde o raciocínio termina e o cálculo começa

O diagrama responde uma pergunta: quem faz o quê. O modelo fica no cliente; o servidor só executa ferramentas determinísticas, seja pelo endpoint remoto ou pelo processo stdio local. O CLI usa o mesmo motor no pipeline, sem agente nenhum. A seta tracejada para a documentação da AWS indica referência citada na resposta, não acesso à sua conta.

### Your machine

- Developer (user)
- Coding agent Claude Code, Kiro, Codex (ai)
- CI pipeline CLI, SARIF (ci)

### MCP server

- Remote endpoint mcp.moretes.com/mcp (edge)
- Local process dist/stdio.js (compute)
- Deterministic engine 48 tools, 10 personas (compute)

### Sources

- AWS documentation official sources (external)

### Fluxos

- dev -> agent: pede
- agent -> remote: HTTPS
- agent -> stdio: stdio
- remote -> engine: executa
- stdio -> engine: executa
- pipe -> engine: revisa plano
- engine -> docs: cita

## Como funciona na prática

Três exemplos mostram o contrato melhor que uma lista de recursos.

**Pergunta antes de sugerir:** você pede uma API e o agente chama `requirements_check` e depois `architect_panel`. A primeira devolve o que falta saber (volume, latência alvo, dados sensíveis); a segunda organiza a avaliação das personas. Nenhum número é inventado no caminho.

**Calcula em vez de chutar:** `latency_budget` soma os passos em série, pega o maior dos paralelos e mostra onde o tempo vai. No exemplo que está no README, o fluxo fecha em 1460 de 2000 ms, com 900 ms no pagamento. Esse é o tipo de dado que muda a conversa: o problema deixa de ser "a API está lenta" e passa a ser um passo específico.

**Revisa o que vai para produção:** `terraform_plan_review` lê o plano e classifica os achados por severidade. Dentro do agente, vira explicação; no CLI, vira exit code.

Os JSON completos dessas chamadas estão em `docs/examples` no repositório, e os GIFs do README são trechos do curso gratuito em vídeo, com as chamadas e respostas reais do servidor.

_Conectar ao endpoint remoto: sem chave, sem cadastro_

```bash
# Claude Code
claude mcp add --transport http moretes-architect https://mcp.moretes.com/mcp

# Codex
codex mcp add moretes-architect --url https://mcp.moretes.com/mcp

# Gemini CLI
gemini mcp add --transport http moretes-architect https://mcp.moretes.com/mcp

# Kiro (.kiro/settings/mcp.json), Cursor (.cursor/mcp.json), Amazon Q (mcp.json)
# {
#   "mcpServers": {
#     "moretes-architect": { "url": "https://mcp.moretes.com/mcp", "autoApprove": [] }
#   }
# }

# VS Code (.vscode/mcp.json)
# { "servers": { "moretes-architect": { "type": "http", "url": "https://mcp.moretes.com/mcp" } } }
```

## Do primeiro uso ao pipeline

1. **Conecte o cliente**: Use o comando do seu cliente no bloco acima. Cursor e VS Code têm botão de instalação em um clique no README. O passo a passo de cada cliente, com verificação e erros comuns, está em `docs/clients.md`.

2. **Confirme que as ferramentas apareceram**: Liste os servidores MCP no cliente e procure `moretes-architect`. Depois peça algo concreto, como "monte o orçamento de latência deste fluxo", e confira se o agente chamou `latency_budget` em vez de responder de cabeça.

3. **Rode local quando precisar de stdio**: Claude Desktop e qualquer cliente stdio apontam para o build local: `{ "command": "node", "args": ["/CAMINHO/ABSOLUTO/dist/stdio.js"] }`. Clone o repositório e siga a seção "Rodar local" do README para instalar e gerar o `dist/`.

4. **Leve a revisão para o pipeline**: O CLI roda offline sobre o mesmo motor, com saída em Markdown, JSON ou SARIF. Achado `high` em `terraform_plan_review` devolve exit code 1, o que basta para travar o job antes do `apply`.

> **Cota do endpoint público:** O endpoint remoto aceita 300 requisições por dia por cliente e 3.000 no total; acima disso, responde `429`. Para uso intenso, para dados que não devem sair da máquina ou para CI, rode local: o motor é o mesmo e não há cota.

## Por que determinístico importa no pipeline

Um revisor baseado em modelo dentro do CI tem dois custos que aparecem só depois: o resultado varia entre execuções, e cada execução cobra tokens. Gate de pipeline que reprova hoje e aprova amanhã o mesmo plano é pior que não ter gate, porque o time aprende a reexecutar até passar.

O motor aqui não tem esse problema. O mesmo `terraform plan` gera os mesmos achados, com a mesma severidade, em toda execução. O formato SARIF existe para que esses achados entrem onde o time já olha alertas de código, em vez de virarem mais um log que ninguém abre.

O custo que importa, no fim, não é o de rodar a ferramenta, é o de manter a regra. Regra determinística tem teste, tem diff e tem dono; regra escondida num prompt muda quando o modelo muda. Foi por isso que mantive o servidor sem chamada a modelo nenhuma, inclusive nas personas: elas estruturam a avaliação, quem raciocina sobre ela continua sendo o agente que você já usa.

O repositório tem CI e análise CodeQL ligados, o que vale conferir antes de adotar qualquer servidor MCP de terceiro.

## Perguntas frequentes

### Preciso de conta AWS ou de credenciais?

Não. O servidor não pede chave de API e nunca acessa a sua conta pela internet. Ele trabalha sobre o que você passa na chamada, como um plano do Terraform ou uma lista de passos com latência.

### Quem paga o modelo?

O seu cliente, como já paga hoje. O servidor faz zero chamadas a modelo, então não acrescenta custo de token além do que o agente gasta para chamar a ferramenta e ler a resposta.

### Serve só para AWS?

A documentação oficial consultada é a da AWS, mas boa parte das ferramentas é agnóstica: requisitos, ADRs, orçamento de latência e revisão de plano valem para qualquer nuvem.

### Remoto ou local?

Remoto para experimentar em 30 segundos. Local quando o volume passa da cota, quando o cliente só fala stdio, ou quando o conteúdo do plano não deve sair da sua máquina.

## Referências

- [GitHub: fernando-moretes/moretes-aws-architect-mcp](https://github.com/fernando-moretes/moretes-aws-architect-mcp)
- [Tutorial e página do MCP / MCP tutorial page](https://fernando.moretes.com/mcp)
- [Curso gratuito em vídeo / Free video course](https://fernando.moretes.com/courses/mcp-architect-workbench)
- [MCP Registry: io.github.fernando-moretes/moretes-aws-architect-mcp](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.fernando-moretes/moretes-aws-architect-mcp)
- [Guia por cliente / Per-client guide (docs/clients.md)](https://github.com/fernando-moretes/moretes-aws-architect-mcp/blob/main/docs/clients.md)

## Para quem é

Use quando você já decide arquitetura com um agente de código e quer que número, estrutura e fonte venham de algo verificável, não da memória do modelo. Comece pelo endpoint remoto para avaliar em minutos; migre para local quando passar de 300 requisições por dia, quando o cliente for stdio ou quando o plano não puder sair da máquina. Se você procura um agente que decida sozinho, este servidor não é isso: ele devolve cálculo e lacuna, e a decisão continua sendo sua.

## Links

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