DeuxOrders MCP

Camada MCP do DeuxOrders. Expõe as operações do sistema como capabilities de domínio para agentes de IA.

Claude Desktop ──(stdio)──┐
                          ├──> DeuxOrders MCP ──> DeuxOrders Backend ──> Services / Database
Hermes ──(HTTP + bearer)──┘

Todo cliente consome exatamente as mesmas capabilities — não existe implementação por canal.

O MCP não reimplementa regra de negócio. Toda validação de domínio, persistência e geração de documento continua no backend.

Construído com Invokta: a mesma capability é publicada por MCP HTTP, MCP stdio, CLI e chamada direta, sem código duplicado por canal.

Instalação

npm install
cp .env.example .env   # preencha os valores
npm run check          # typecheck + testes + build + conformance MCP

Requer Node.js 22.20 ou superior.

Related MCP server: Company API MCP Server

Configuração

Gere o token do MCP com openssl rand -base64 48. .env não é versionado.

Autenticação

São duas, distintas e independentes:

Cliente → MCP. Todo POST /mcp exige Authorization: Bearer <MCP_AUTH_TOKEN>. A comparação é em tempo constante; sem token válido, 401. É o canal do Hermes.

O Claude Desktop conecta por stdio, onde não há bearer: quem inicia o processo já provou ser o dono da máquina.

ChatGPT web não é suportado — conectores remotos do ChatGPT exigem OAuth e o Authorization Server não foi construído. É aditivo depois, sem mexer em capability nenhuma.

MCP → Backend. O connector faz login com o usuário de serviço, guarda o JWT em memória e o renova sozinho. A credencial do backend nunca aparece em prompt, description de tool, resposta ou log — há um teste que verifica isso.

Full access no MVP: cliente autenticado alcança todas as capabilities. Não há RBAC por capability.

Executando

npm run mcp:stdio     # Claude Desktop (ou npm run mcp:install para registrar)
npm run mcp:http      # Hermes
npm run devtools      # UI de desenvolvimento: invoca capabilities por qualquer canal
npm run smoke         # varredura de leitura contra o backend real

O passo a passo de lançamento está em DEPLOY.md.

Testando sem agente nenhum

O CLI executa pelo mesmo pipeline (engine.invoke) que o MCP — mesma validação, mesma autorização, mesmo connector:

npm run cli -- list
npm run cli -- describe orders.search
npm run cli -- run clients.search --input '{"search":"maria"}'

Capabilities

Datas, receita e Hermes

Pedidos, métricas do dashboard, rankings e exportações recebem from/to como dias inclusivos (AAAA-MM-DD, fuso America/Sao_Paulo) e dateField: DeliveryDate é o padrão; CreatedAt seleciona a criação quando solicitada. Os filtros opcionais clientId, status e isPaid podem ser combinados. orders.search também aceita productId para pedidos que contêm um item ativo do produto. products.stats aceita month e dateField.

Para períodos relativos, envie period sem from/to: today, yesterday, this_week, last_week, this_month, last_month, this_year, last_year ou last_n_days com days. O MCP calcula as datas pelo relógio de São Paulo em cada chamada e devolve resolvedPeriod com o intervalo aplicado. Semana atual vai de segunda até hoje; mês/ano atual começa no primeiro dia e termina hoje. Semana/mês/ano anterior inclui o período anterior inteiro.

Receita segue totalRevenue, após descontos e sem pedidos cancelados; omitir isPaid inclui pedidos pagos e não pagos. Caixa mantém a data de competência dos lançamentos. As regras de escrita e os cálculos continuam no backend.

O prompt do bot está em HERMES_SOUL.md. No Hermes, use o provedor nativo gemini, modelo gemini-3.5-flash-lite, raciocínio low e endpoint https://generativelanguage.googleapis.com/v1beta. A chave pertence ao .env do Hermes (GOOGLE_API_KEY), não ao código ou ao prompt.

Publique primeiro o backend com suporte a from/to/dateField, depois reconstrua e reinicie MCP e Hermes. Os antigos campos de tools createdAtFrom/To e deliveryFrom/To são rejeitados para evitar consultas sem o filtro pretendido. O backend preserva os parâmetros deliveryDateFrom/To usados pelo SaaS.

53 capabilities em 7 domínios. O mapeamento completo com os endpoints de origem está em MCP_CAPABILITY_MAP.md.

Um cliente MCP vê cada uma como uma tool (orders.create → orders_create). Não existe tool genérica de HTTP ou de banco: o agente só alcança o backend pelas operações declaradas aqui.

Tarefas compostas são composição de primitivas. "Cria um pedido igual ao último da cliente X" é clients.search → clients.list-orders → orders.get → orders.create.

Arquitetura

Capability (src/capabilities/)      contrato de domínio, schemas de entrada e saída
     ↓
BackendGateway (src/application/)   port
     ↓
connector (src/infrastructure/)     BACKEND_URL, login, headers, timeout, retry, erros
     ↓
DeuxOrders Backend

O connector é o único lugar que conhece o BACKEND_URL e a credencial. Retries acontecem só em GET, e só para falha de rede, 429 ou 5xx — escritas nunca são repetidas.

Erros do backend chegam ao agente traduzidos: uma violação de regra de negócio vira INPUT_INVALID com a mensagem original, que o agente consegue corrigir; um 5xx vira uma mensagem genérica que não vaza nada.

Auditoria

Toda invocação emite em stderr, como JSON de uma linha: timestamp, requestId, capability, canal (mcp-http, mcp-stdio, cli, direct), identidade do chamador, duração e código de erro. Segredos nunca são registrados.

Testes

npm test

Cobrem operação válida, entrada inválida, recurso inexistente, erro do backend, backend indisponível, resposta inesperada, retry, exportação grande demais, não vazamento de credencial e a ausência de tool genérica. O MCP é testável sem Hermes nem Claude.

npm test roda contra dublês. npm run smoke roda contra o backend de produção e é o que valida os contratos de saída contra respostas reais — rode antes de cada lançamento.