# Implemente e teste uma calculadora de capacidade MCP: lacunas, premissas explícitas e hospedagem AWS

Um passo a passo reproduzível: de um relato real de uso a resultados parciais, premissas explícitas, testes do protocolo e um runtime AWS restrito.

- URL: https://fernando.moretes.com/blog/mcp-capacidade-sem-chutes-validacao-evidencias-aws

- Markdown: https://fernando.moretes.com/blog/mcp-capacidade-sem-chutes-validacao-evidencias-aws/article.md?lang=pt

- Published: 2026-11-16T20:52:32.333859Z

- Category: IA & Agentes

- Tags: mcp, aws-lambda, ai-agents, solution-architecture, testing

- Reading time: 12 min

- Source: [capacity_plan implementation and acceptance lab v0.5.0](https://github.com/fernando-moretes/moretes-aws-architect-mcp/releases/tag/v0.5.0)

---

Apenas um pico de 500 requisições por segundo não permite estimar concorrência sem a duração do processamento. Execute uma calculadora MCP local, preserve essa lacuna e depois forneça uma duração explicitamente hipotética para testar o cenário.

## Uma fronteira AWS restrita

Capacidade é calculada em memória; cotas e logs são dependências operacionais, não evidências de negócio.

### AWS · public hosting

- API Gateway (edge)
- Lambda capacity_plan (compute)
- DynamoDB quota + usage (data)
- CloudWatch minimal logs (data)

### Fluxos

- client -> api: MCP / HTTP
- api -> lambda: invocar
- lambda -> quota: cotas + contadores
- lambda -> logs: logs operacionais

Uma equipe de produto informa um requisito: sua API de pedidos precisa suportar um pico de 500 requisições por segundo. Você está construindo um assistente de arquitetura que chama ferramentas e quer usá-lo em uma conversa inicial de capacidade. Antes de recomendar recursos, o que ele consegue calcular apenas com esse número?

Não consegue calcular concorrência. Neste exercício simplificado, concorrência é a quantidade de requisições processadas ao mesmo tempo, estimada pela taxa de chegada multiplicada pela duração do processamento. Se hipoteticamente adotarmos 250 milissegundos, teremos 500 × 0,250 = 125 requisições concorrentes. Com 30% de folga e arredondamento, chegamos a 163. São cálculos de cenário: a equipe não informou essa duração, portanto 163 não é um requisito aprovado para produção.

Este tutorial é para desenvolvedores que criam ferramentas MCP para assistentes de arquitetura. MCP permite que um cliente descubra e chame ferramentas de um servidor. Vamos acompanhar uma ferramenta determinística pequena, `capacity_plan`, para aprender a preservar informações ausentes no schema de entrada e na resposta. Você executará a implementação publicada, examinará as mudanças de código e testará respostas reais do protocolo. Não vamos construir um arquiteto autônomo, avaliar um modelo, escolher instâncias AWS nem implantar nova infraestrutura.

A implementação faz parte do meu workbench aberto Moretes Architect MCP, versão 0.5.0. Ele contém outras ferramentas, mas este artigo acompanha apenas `capacity_plan` e seu tratamento de validação. A implantação pública existente utiliza API Gateway, Lambda e uma tabela DynamoDB operacional. O exercício principal roda localmente, sem credenciais AWS nem modelo de linguagem; a seção final explica como essa ferramenta se encaixa na hospedagem AWS existente.

O problema concreto veio do relato de primeira utilização de Pin Xiong na issue #19 do GitHub do workbench. Um cliente chamou a ferramenta anterior com entradas incompletas e recebeu uma rejeição. Quando o chamador fornecia valores hipotéticos, a resposta não os separava claramente dos requisitos informados. Esse relato motivou a implementação 0.5.0 examinada aqui. É evidência sobre esta ferramenta, não uma afirmação de que todo assistente inventa entradas nem de que a correção elimina alucinações.

## O que será implementado e verificado

Vamos separar três situações: uma requisição inválida, que precisa de correção; um cenário válido porém incompleto, que deve conservar as lacunas; e um cenário completo com premissas, que pode produzir números sem se tornar um requisito aprovado.

O resultado executável será um cliente MCP no terminal e um teste de aceitação repetível. Primeiro, envie apenas o pico conhecido: espere concorrência null e a lista de campos ausentes. Depois, forneça entradas explicitamente hipotéticas: espere 125/163, ainda sem validação do workload. Por fim, teste entradas inválidas e repita as verificações por HTTP local. Os trechos explicam como implementar esse comportamento em sua própria ferramenta; instalar o pacote não implementa todo o seu fluxo de arquitetura.

Os pré-requisitos são Node.js 22.13 ou superior, npm e um terminal. A instalação dos pacotes utiliza rede. Os cálculos locais não precisam de credenciais AWS nem de um modelo pago. Um cliente de IDE que utilize seu próprio modelo continua sujeito ao plano desse cliente; o laboratório não mede o comportamento desse modelo.

## 1. Comece pelo que a equipe realmente informou

Execute a versão fixada e indique explicitamente que o tráfego é de pico:

```sh
npx --yes --package moretes-aws-architect-mcp@0.5.0 \
  moretes-architect call capacity_plan \
  --arg requestsPerSecond=500 --arg rateType=peak \
  --arg 'inputProvenance={"requestsPerSecond":"provided"}'
```

Os campos relevantes do resultado são:

```json
{
  "validated": false,
  "status": "insufficient-inputs",
  "insufficientInputs": ["durationMs", "payloadKB"],
  "averageConcurrency": null,
  "plannedConcurrency": null,
  "dailyRequests": null,
  "dailyPayloadGB": null
}
```

A chamada funcionou. O cenário de negócio é que está incompleto. O cliente pode perguntar pelos dados ausentes. Converter null em zero ou esconder esses campos na apresentação apagaria justamente a informação que interessa à decisão.

O parâmetro `rateType=peak` evita outra conclusão indevida. Um pico de 500 requisições/s não estabelece o volume diário. Por compatibilidade, `unspecified` ainda calcula um cenário condicionado a uma taxa sustentada: isso não é previsão de demanda. Declare o tipo de taxa em vez de depender desse default.

## 2. Corrija o contrato de entrada

Exigir todos os números transforma uma ferramenta em um formulário que o cliente pode preencher sem evidência. Na implementação, a taxa é obrigatória; duração e payload são opcionais:

```ts
const shape = {
  requestsPerSecond: z.number().nonnegative().max(1e9),
  durationMs: z.number().nonnegative().max(86400000).optional(),
  payloadKB: z.number().nonnegative().max(1e9).optional(),
  headroom: z.number().min(1).max(10).optional(),
  rateType: z.enum(['peak', 'sustained', 'unspecified'])
    .default('unspecified')
};
```

Esse trecho integra o registro de uma ferramenta existente; não constitui um servidor completo. A [implementação integral](https://github.com/fernando-moretes/moretes-aws-architect-mcp/blob/v0.5.0/src/architecture.ts) também declara o objeto estrito de proveniência por campo. Copiar somente o cálculo deixaria de fora a validação e o tratamento do protocolo.

Ao publicar o schema para o cliente, use o modo de entrada do Zod:

```ts
z.toJSONSchema(schema, { io: 'input' });
```

Entrada e saída deixam de ser contratos idênticos quando há defaults. Neste projeto, exportar o modo errado fazia campos com default parecerem obrigatórios na descoberta. O teste deve conferir o `tools/list` efetivo: o array `required` de `capacity_plan` contém somente `requestsPerSecond`.

## 3. Calcule apenas o que os dados permitem

O núcleo da conta pode continuar pequeno:

```ts
const headroom = a.headroom ?? 1.3;
const concurrency = a.durationMs === undefined
  ? null : a.requestsPerSecond * a.durationMs / 1000;
const dailyRequests = a.rateType === 'peak'
  ? null : a.requestsPerSecond * 86400;
const dailyPayloadGB = dailyRequests === null || a.payloadKB === undefined
  ? null : dailyRequests * a.payloadKB / 1e6;
```

Sem duração, não calculamos concorrência. Sem payload, não calculamos volume de dados; isso não impede a concorrência quando a duração foi fornecida. Uma taxa de pico não vira volume diário. Zero é um valor informado; undefined representa ausência. Por isso, verificações explícitas e o operador de coalescência nula são preferíveis a testes de truthiness.

Esses números descrevem um cenário, não determinam uma reserva de concorrência da Lambda, um pool de conexões, uma instância ou uma cota de serviço. Retries, batching, caudas de latência, distribuição das chegadas e saturação das dependências exigem evidências próprias. O nome legado `averageConcurrency` não significa medição: com uma taxa de pico, ele representa a conta sob aquela taxa escolhida.

## 4. Mantenha cada premissa ao lado do valor

Agora podemos experimentar valores hipotéticos, identificados como tais:

```sh
npx --yes --package moretes-aws-architect-mcp@0.5.0 \
  moretes-architect call capacity_plan \
  --arg requestsPerSecond=500 --arg durationMs=250 \
  --arg payloadKB=4 --arg headroom=1.3 --arg rateType=peak \
  --arg 'inputProvenance={"requestsPerSecond":"provided","durationMs":"assumed","payloadKB":"assumed","headroom":"assumed"}'
```

A conta resulta em `500 × 0,250 = 125`. Com a folga, `ceil(125 × 1,3) = 163`. São valores calculados para o cenário, não resultados de benchmark. O volume diário continua null porque a taxa é de pico.

Uma projeção do objeto `provenance` mostra:

```json
{
  "requestsPerSecond": { "value": 500, "origin": "provided" },
  "durationMs": { "value": 250, "origin": "assumed" },
  "payloadKB": { "value": 4, "origin": "assumed" },
  "headroom": { "value": 1.3, "origin": "assumed" }
}
```

Se headroom não for informado, sua origem será `server-default`. Um número recebido sem identificação será `caller-unspecified`. Rotular um valor ausente não faz esse valor existir.

O limite dessa solução precisa ficar explícito: o cliente pode chamar um chute de `measured`. O servidor não verifica a medição nem prova a aprovação do responsável pelo workload. Um fluxo de produção precisa de registro de evidências, data da medição e responsável. `validated: false` conserva a diferença entre executar aritmética e aprovar uma arquitetura.

## 5. Transforme o erro em uma pergunta acionável

Incompletude do cenário e entrada inválida não devem produzir a mesma mensagem opaca. Se a taxa obrigatória estiver ausente, uma projeção do resultado MCP é:

```json
{
  "isError": true,
  "structuredContent": {
    "kind": "input-validation-error",
    "validated": false,
    "missing": ["requestsPerSecond"],
    "issues": [{ "path": ["requestsPerSecond"], "code": "invalid_type" }]
  }
}
```

O resultado completo também tem um bloco de texto legível. Para uma taxa negativa, `missing` fica vazio e `issues` aponta o campo inválido. Caminhos aninhados podem identificar campos de um item sem depender da redação da mensagem.

A [especificação MCP citada](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) define resultados estruturados e schemas de saída. Conteúdo estruturado produzido pelo servidor não garante o texto que um modelo escreverá depois. Aqui, os testes verificam a descoberta e as chamadas pelo SDK real. O erro estruturado inclui caminhos e códigos, não os valores recebidos; nomes de campos também podem revelar contexto, então use apenas dados sintéticos no endpoint público.

## 6. Verifique o pacote publicado pelo protocolo

Baixe o [ZIP do laboratório](https://fernando.moretes.com/labs/mcp-capacity-evidence-0.5.0.zip), extraia em um diretório descartável novo e localize a pasta `lab/`. Ela contém dependências fixadas, lockfile e `acceptance.test.mjs`. Execute:

```sh
cd lab
npm ci --ignore-scripts --no-fund --no-audit
npm test
```

O teste inicia o servidor publicado por stdio com ferramentas de conta desabilitadas. Um cliente real do SDK verifica seis cenários:

| Cenário | Resultado verificado |
| --- | --- |
| Pico sem duração/payload | Saídas dependentes null e duas entradas ausentes |
| Premissas declaradas | 125 e 163, com as origens assumidas preservadas |
| Taxa obrigatória ausente | Erro estruturado apontando requestsPerSecond |
| Taxa negativa | Campo inválido, sem alegar ausência |
| Duração sem origem | caller-unspecified e cenário diário condicionado visível |
| Valores zero | Zero continua sendo dado informado |

O teste também confirma a indisponibilidade da ferramenta de identidade da conta nesse modo. As respostas sintéticas ficam em `evidence/stdio-results.json`; leia-as separadamente de qualquer explicação de modelo.

Em 9 de novembro de 2026, esse exercício local com o pacote publicado passou. Trata-se de um teste Node com os cenários acima, não de seis testes de carga. A suíte mais ampla do projeto 0.5.0 tem 60 testes; são escopos diferentes. Não medimos percentuais de redução de alucinação, economia, latência ou adoção.

### Inicie, verifique e encerre o transporte HTTP

No terminal A, dentro de `lab/`, execute o servidor publicado apenas em loopback:

```sh
HOST=127.0.0.1 PORT=18787 ENABLE_AWS_ACCOUNT_TOOLS=false \
  node node_modules/moretes-aws-architect-mcp/dist/http.js
```

No terminal B, no mesmo diretório:

```sh
curl -fsS http://127.0.0.1:18787/health
MCP_TEST_URL=http://127.0.0.1:18787/mcp npm test
```

O health deve informar versão 0.5.0 e `accountTools: false`. As mesmas verificações agora passam por um cliente Streamable HTTP real. Stdio e HTTP local passaram em 9 de novembro; os resultados ficam separados em `evidence/stdio-results.json` e `evidence/http-results.json`. O runner rejeita destinos HTTP remotos. Se a porta estiver ocupada, encerre sua própria instância anterior ou altere a porta de forma consistente; não finalize processos de terceiros.

Para limpar, pressione Ctrl+C no terminal A e confirme que o health não alcança mais aquela instância. Quando não precisar dos pacotes, remova somente o diretório descartável que você criou, preservando as evidências necessárias à revisão. O laboratório não cria recursos AWS, portanto não existe teardown AWS a executar. O serviço público é outra implantação e tem seu próprio runbook.

Se o servidor parecer parado ao ser iniciado diretamente, ele está esperando mensagens MCP por stdio: use o cliente ou o CLI. Se os resultados divergirem, confira a versão instalada e o lockfile. Se a IDE esconder o conteúdo estruturado, inspecione a trilha real de ferramentas em vez de tratar o texto do assistente como resposta do servidor.

## 7. A fronteira AWS deve ser menor que a capacidade do assistente

O caminho público é cliente → API Gateway → Lambda. A função usa DynamoDB para cotas/contadores agregados e CloudWatch para logs operacionais mínimos. O cálculo de capacidade permanece em memória: não chama Bedrock nem lê a infraestrutura do cliente.

Ferramentas autenticadas de conta são locais e opt-in. A role do runtime público está limitada aos próprios logs e à tabela de cotas/uso; não recebe credenciais de clientes. Anotações descrevem a intenção da ferramenta. O registro das ferramentas e o IAM delimitam os caminhos de implementação permitidos.

A separação permite um ciclo de validação local barato, um ponto compartilhado stateless na Lambda e uma cota hospedada que sobrevive a reinícios por estar no DynamoDB. Em troca, o endpoint público tem limites e dependências operacionais: não é um tenant isolado nem oferece SLA. Preservar null exige suporte do cliente; um formatador legado ainda pode esconder a lacuna. A superfície menor é uma escolha de engenharia, não uma recomendação de tornar pública qualquer tarefa de arquitetura.

O [manifesto público](https://mcp.moretes.com/manifest.json) permite comparar descritores, schemas de saída e anotações. Use uma baseline revisada e a versão exata. Um hash não é assinatura, auditoria de segurança nem prova de que o comportamento da implementação permaneceu igual.

Para revisar a hospedagem, consulte o [template](https://github.com/fernando-moretes/moretes-aws-architect-mcp/blob/v0.5.0/infra/service.json) e o [runbook](https://github.com/fernando-moretes/moretes-aws-architect-mcp/blob/v0.5.0/docs/operations.md). O script do mantenedor é intencionalmente fixado à conta do proprietário; não deve ser executado sem adaptação em outra conta. O exercício local não cria recursos. Implantar um fork revisado pode gerar consumo AWS; cotas e alertas de budget não são um limite financeiro absoluto.

## Checklist de aceitação

- Entradas opcionais ausentes continuam visíveis, com saídas dependentes null.
- Entradas obrigatórias inválidas produzem erros estruturados.
- Defaults e premissas mantêm origens distintas.
- Pico e tráfego sustentado são tratados separadamente.
- O cliente suporta resultados anuláveis e proveniência autodeclarada.
- Os testes verificam descoberta e protocolo, além da conta numérica.
- A superfície pública não tem caminho para credenciais de conta ou escritas de providers.
- Evidências externas, cálculos e explicações de modelo permanecem distinguíveis.

Um schema não torna um agente confiável por si só. Ele pode tornar a incerteza visível o suficiente para revisão. O passo seguinte é conectar essa visibilidade à coleta de evidências, à aprovação do responsável e a testes medidos do workload, antes que um cenário se torne uma decisão de produção.

## Referências e evidências

- [MCP: ferramentas e resultados estruturados, versão citada](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
- [Implementação de capacidade 0.5.0](https://github.com/fernando-moretes/moretes-aws-architect-mcp/blob/v0.5.0/src/architecture.ts)
- [Handler de validação estruturada](https://github.com/fernando-moretes/moretes-aws-architect-mcp/blob/v0.5.0/src/server.ts)
- [Relato de primeira utilização e respostas originais, com crédito a Pin Xiong](https://github.com/fernando-moretes/moretes-aws-architect-mcp/issues/19#issuecomment-6703772880)
- [Release e verificação de produção](https://github.com/fernando-moretes/moretes-aws-architect-mcp/releases/tag/v0.5.0)

**Para quem revisar:** qual entrada ausente mudaria sua próxima decisão? Que evidência você exigiria para aceitar um valor marcado como medido? Um contraexemplo útil vale mais que um elogio.

*Transparência: esta explicação foi preparada com apoio de IA. Os comandos do pacote e os cenários sintéticos foram executados; comportamento de modelos e desempenho do workload não foram medidos.*

## Revisão de produção pelos seis pilares

- **operational-excellence**: Fixe versões, inspecione a trilha real de ferramentas, retenha respostas sintéticas e revise mudanças de contrato antes de atualizar.
- **security**: Mantenha ferramentas de conta/providers fora do registro público e restrinja IAM aos próprios dados operacionais. Não envie entradas de clientes ao exercício público.
- **reliability**: Separe requisições inválidas de cenários incompletos válidos. Lacunas permanecem explícitas; cálculo bem-sucedido não garante disponibilidade.
- **performance**: Limite entradas e calcule localmente; obtenha distribuições do workload e evidências de cauda de latência antes de dimensionar dependências.
- **cost**: O laboratório local não cria recursos AWS. Requisições hospedadas consomem serviços; cotas e alertas de budget não são teto financeiro absoluto.
- **sustainability**: Reutilize cálculos determinísticos locais e encerre o HTTP descartável após verificar. Não há alegação de economia ambiental medida.

## Anti-patterns

- Substituir lacunas por zero ou defaults inventados.
- Tratar o pico como tráfego diário sustentado.
- Tratar o rótulo measured, um teste ou hash como evidência de negócio verificada independentemente.

## C4

Um cliente solicita aritmética de cenário ao workbench público; operações autenticadas de conta continuam locais e opt-in.

### Containers
- **MCP client** (MCP SDK / stdio or HTTP): Fornece entradas e apresenta resultados estruturados.
- **Public AWS runtime** (API Gateway / Lambda / DynamoDB / CloudWatch): API Gateway e Lambda atendem MCP stateless com armazenamento operacional restrito.

### Components
- **Input contract**: Schema estrito, lacunas opcionais e caminhos de erro estruturados.
- **Deterministic calculator**: Calcula valores dependentes somente com as entradas disponíveis.
- **Evidence projection**: Preserva origens autodeclaradas e limites visíveis.

## Veredito

Use resultados parciais tipados para tornar a incerteza revisável. Exija evidência do workload antes de aceitar uma decisão de capacidade.
