Moretes Architect MCP

Claude Code · Codex · Kiro · Cursor · VS Code · Gemini CLI · Amazon Q · Claude Desktop
Conectar · Ver funcionando · Ferramentas · Pipeline · Privacidade · Tutorial e curso · English

Um servidor MCP que coloca 48 ferramentas determinísticas de arquitetura e 10 personas de arquiteto dentro do seu agente de código. O modelo do seu cliente raciocina; o servidor devolve cálculos, estruturas, fontes oficiais e lacunas explícitas. O servidor nunca chama um modelo, nunca acessa a sua conta pela internet e não precisa de chave de API.

Feito por Fernando Azevedo, Arquiteto de Tecnologia da Informação Especialista e AWS Community Builder (AI Engineering). É o que eu uso para decidir arquitetura no dia a dia, aberto para a comunidade usar, auditar e estender.

Veja funcionando

Pede uma API, ele pergunta antes de sugerir. O agente chama requirements_check e depois architect_panel; nenhum número é inventado.

Calcula, não chuta. No Kiro, latency_budget soma os passos em série, pega o maior dos paralelos e mostra onde o tempo vai.

Trava o apply perigoso no pipeline. O mesmo motor roda offline como CLI, com Markdown, JSON ou SARIF e exit code por severidade.

Os GIFs são trechos dos vídeos do curso gratuito, narrados na minha voz, com as chamadas e as respostas reais do servidor. Os JSON completos estão em docs/examples.

Conecte em 30 segundos

Sem chave, sem cadastro:

# Claude Code
claude mcp add --transport http moretes-architect https://m9od37vm41.execute-api.us-east-1.amazonaws.com/mcp

# Codex
codex mcp add moretes-architect --url https://m9od37vm41.execute-api.us-east-1.amazonaws.com/mcp

# Gemini CLI
gemini mcp add --transport http moretes-architect https://m9od37vm41.execute-api.us-east-1.amazonaws.com/mcp

{
  "mcpServers": {
    "moretes-architect": {
      "url": "https://m9od37vm41.execute-api.us-east-1.amazonaws.com/mcp",
      "autoApprove": []
    }
  }
}

{
  "servers": {
    "moretes-architect": { "type": "http", "url": "https://m9od37vm41.execute-api.us-east-1.amazonaws.com/mcp" }
  }
}

{ "mcpServers": { "moretes-architect": { "command": "node", "args": ["/CAMINHO/ABSOLUTO/dist/stdio.js"] } } }

Cota pública: 300 requisições por dia por cliente e 3.000 no total; acima disso, 429. O mesmo servidor responde em https://fernando.moretes.com/api/mcp, mas esse endereço passa pelo site e todos os seus usuários dividem uma única cota diária; use a URL direta para ter a sua. Para volume ou entradas privadas, rode local.

Depois de conectar, peça ao agente:

"Use o Moretes Architect. Preciso de uma API de pedidos para um marketplace, 300 pedidos por minuto no pico. Pergunte o que falta antes de sugerir, convoque os arquitetos de solução, segurança e FinOps, compare Lambda e ECS, desenhe o C4 e registre a decisão em um ADR."

O que ele faz

iam_policy_review lê política IAM da AWS, role definition do Azure e bindings do Google Cloud (provider). Toda ferramenta de cálculo e revisão publica outputSchema, e o cliente valida a saída.

Mais 20 prompts (10 fluxos e um architect_<papel> por persona), 18 resources (moretes://guide, moretes://boundaries, moretes://tools, moretes://personas/<id>, moretes://skills/<id>) e, só no modo local, 5 ferramentas opcionais de conta AWS e federação com os servidores oficiais.

Guia de cada ferramenta: docs/tools-guide.md · Schemas: docs/tools.md · Saídas reais: docs/examples · Personas: docs/personas.md

Saída real: um C4 desenhado pelo c4_model

Entrada: pessoas, sistemas e relações explícitas. Saída: Mermaid validado (id duplicado, aresta solta e rótulo com sintaxe perigosa são recusados). O GitHub renderiza abaixo exatamente o que a ferramenta devolveu em docs/examples/c4_model.json:

flowchart TB
  buyer(["Buyer<br/>Places and tracks orders"])
  subgraph system_Orders_platform["Orders platform"]
    web["Storefront [Next.js]"]
    api["Orders API [Node.js on Fargate]"]
    db["Orders DB [PostgreSQL]"]
    bus["Order events [EventBridge]"]
  end
  psp[["Payment provider [REST + webhooks]"]]
  buyer -->|"uses"| web
  web -->|"calls (HTTPS/JSON)"| api
  api -->|"reads and writes"| db
  api -->|"authorizes payment"| psp
  psp -->|"webhook: payment captured"| api
  api -->|"publishes OrderPlaced"| bus
  classDef person fill:#1f3b63,stroke:#5b9bd5,color:#fff
  class buyer person
  classDef external fill:#4a4a4a,stroke:#9a9a9a,color:#fff
  class psp external

Saída real: revisando um servidor MCP envenenado

mcp_server_review recebe o tools/list de outro servidor e procura texto de instrução escondido na descrição, parâmetros perigosos, anotação mentirosa e nomes duplicados. Contra o servidor de exemplo em docs/examples/mcp_server_review.json:

{
  "summary": { "high": 5, "medium": 1, "info": 0 },
  "verdict": "Do not auto-approve; review each high finding with the server author or pin to an allowlist",
  "findings": [
    { "severity": "high", "target": "read_file", "message": "Description contains instruction-like text (references local secret files); tool-poisoning indicator." },
    { "severity": "high", "target": "read_file", "message": "Parameters that typically carry commands, raw queries, URLs or paths: path. Require an allowlist and per-call approval." }
  ]
}

Por que existe

Os servidores MCP de nuvem são operacionais: executam na conta. Faltava a parte de antes: levantar requisitos, comparar com honestidade entre provedores, calcular em vez de chutar, revisar com evidências e registrar a decisão. Este projeto faz essa parte, no mesmo lugar onde o código nasce, sem custo de inferência no servidor e sem receber credenciais.

Três regras atravessam todas as ferramentas:

1. Pergunta antes de assumir. Requisito que falta volta como pergunta, não como valor típico.
2. Calcula com entrada auditável. Preço só com fonte e data; fórmula explícita na saída.
3. Heurística é triagem. Controle marcado como atendido sem evidência volta como desconhecido; toda revisão diz o que não cobre.

No pipeline

git clone https://github.com/fernando-moretes/moretes-aws-architect-mcp.git
cd moretes-aws-architect-mcp && npm ci --ignore-scripts && npm run build

terraform show -json tfplan > plan.json
node dist/cli.js call terraform_plan_review --input plan.json --format sarif --fail-on high > review.sarif
# exit 0: ok · 1: achados no nível --fail-on ou acima · 2: erro de uso ou entrada

Roda offline e sem cota. O SARIF entra no code scanning do GitHub; o Markdown vai para o resumo do job. GitHub Actions, GitLab CI e pre-commit prontos em docs/pipelines.md.

Rodar local

npm ci --ignore-scripts && npm run build
npm start            # MCP stdio (o protocolo usa o stdout; não é um chat)
npm run http         # http://127.0.0.1:8787/mcp e a landing local
node dist/cli.js list

As ferramentas de conta AWS (identidade STS, recursos por tag, histórico de custo) e a federação com os servidores oficiais são opt-in por variável de ambiente e só existem no stdio: o HTTP público nunca as expõe. Detalhes em docs/clients.md e docs/integrations.md. Ainda não há publicação no npm; use o clone de uma tag.

Tutorial em vídeo e curso grátis

Em fernando.moretes.com/mcp: conexão por cliente, um playground que chama o servidor de verdade, as ferramentas por grupo, as personas, troubleshooting e FAQ. O curso tem dez aulas, cada uma com vídeo, áudio e texto, quizzes e certificado:

Playground: escolha um exemplo, edite o JSON, chame a ferramenta.	Aula 05: números que defendem a decisão.

Privacidade e limites

• O servidor público processa a entrada em memória e registra só id da requisição, status e duração. Nunca argumentos, prompts ou resultados.
• Só duas famílias saem para a internet: aws_knowledge_* (a consulta vai para o MCP oficial da AWS) e github_public_repository (api.github.com). Todo o resto é cálculo local.
• A cota por cliente usa sha256(dia + IP) com validade de dois dias; o IP bruto não é guardado.
• Não envie segredos, dados de clientes ou arquitetura confidencial ao endpoint público; para isso existe o modo local.
• Sem SLA. Serviço comunitário, mantido por uma pessoa, com orçamento alvo de US$ 30 por mês.

Tudo em PRIVACY.md e SECURITY.md.

Arquitetura

flowchart LR
  C[Claude Code / Codex / Kiro / Cursor / VS Code] -->|Streamable HTTP| G[API Gateway: 5 rps, rajada 20]
  G --> L[Lambda arm64: 48 ferramentas públicas]
  L --> Q[DynamoDB: cota global e por cliente]
  L --> K[AWS Knowledge MCP oficial]
  L --> H[GitHub: metadados públicos]
  C -->|stdio, opcional| S[MCP local]
  S --> A[Credenciais do SDK + guarda de conta]
  A --> R[3 ferramentas de conta, somente leitura]
  A --> F[Servidores oficiais instalados + allowlist exata]
  P[CLI moretes-architect] --> T[Mesmas ferramentas, offline]

A role da Lambda só escreve na tabela de cota e nos próprios logs. Deploy por change set CloudFormation revisado. Design · Custos · Runbook · Evidências do deploy

Qualidade

npm run typecheck && npm test && npm run build && npm audit --omit=dev
npm run smoke -- https://m9od37vm41.execute-api.us-east-1.amazonaws.com/mcp   # consulta pública real
node scripts/examples.mjs    # regenera docs/examples com as saídas reais

41 testes offline, 99% das linhas cobertas, cobrem protocolo, cálculos, revisões, isolamento entre público e local, limites de entrada e federação. CI em Node 22 e 24, CodeQL, Dependabot e SBOM CycloneDX a cada release. Cada saída documentada em docs/examples é um teste: se uma ferramenta mudar de comportamento, o CI acusa. docs/tools.lock.json guarda o hash do nome, da descrição e do schema de cada ferramenta, então qualquer mudança no que o modelo do cliente lê aparece no diff.

Contribua

Issues e PRs em português ou inglês. Use os templates: bug ou proposta de ferramenta (problema, entrada, saída esperada, limite). Uma ferramenta nova precisa de schema estrito, fronteira de dados externos explícita, limitações na saída e teste. Se você é AWS Community Builder, organiza User Group ou dá aula: o curso e os vídeos são livres para usar em sala.

Clientes · Ferramentas · Personas · Pipelines · FAQ · Troubleshooting · Glossário · Novidades · Workshop · Contribuir · Conduta · Roadmap · Changelog · Atribuições

_{Projeto independente. Não é um produto da AWS, nem revisão Well-Architected oficial, nem certificação de segurança, nem cotação de preço. AWS e outros nomes pertencem aos seus donos.}