ZPL Engine MCP

Servidor MCP ZPL Engine MCP

Servidor Model Context Protocol (MCP) para o Zero Point Logic Engine — um sistema pós-binário de análise de estabilidade e neutralidade.

Conecta qualquer cliente de IA compatível com MCP (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) à API do ZPL Engine para detecção de viés em tempo real, pontuação de estabilidade e análise de neutralidade em múltiplos domínios.

69 ferramentas (65 exclusivas + 4 aliases de compatibilidade reversa) em 11 categorias: Core, Finance, Gaming, AI/ML, Security, Crypto, Certification, Advanced, Universal, Meta e AI Eval.

Destaques da linha 4.x

Para saber o que mudou na versão que você está instalando, consulte CHANGELOG.md.

Dois meses de trabalho incremental consolidados. 21 bugs corrigidos, 308 testes (259 unitários + 49 de integração MCP ao vivo), Windows + Linux verificados. Compatibilidade reversa — chaves legadas zpl_u_<48hex> continuam funcionando, todas as 69 ferramentas mantêm o mesmo formato de entrada.

Novos comandos

• npx zpl-engine-mcp setup — agora com memória. Detecta configuração existente e oferece manter / reconfigurar / corrigir apenas em vez de forçar um novo login. --force ignora.
• npx zpl-engine-mcp whoami — mostra em qual conta esta instalação está conectada.
• npx zpl-engine-mcp repair — apaga a configuração local e remove a entrada de cada config de cliente MCP (Claude Desktop, Cursor, Windsurf). Preserva entradas não relacionadas. --yes pula a confirmação.
• npx zpl-engine-mcp --help / --version — flags de uso e versão padrão POSIX.
• Ferramenta MCP zpl_diagnose — relatório completo de saúde (config + chave + engine + auth) para relatórios de problemas.

Correções críticas

• Regex de chave de API agora aceita chaves emitidas pelo assistente com prefixos de tipo (zpl_u_mcp_, zpl_u_cli_, zpl_u_default_). Antes da 4.0, a instalação pelo assistente sempre falhava silenciosamente.
• Respostas HTML do Cloudflare explicadas — mensagens de erro acionáveis com ID cf-ray em vez de 403 genérico.
• Teste de fumaça ao final da configuração — detecta atraso de replicação entre a aprovação do assistente e a aceitação pelo engine.
• Sanitizador de segredos no histórico — não vaza mais chaves ZPL prefixadas pelo assistente nem tokens completos do Anthropic sk-ant-* (o regex estava truncando no primeiro hífen).
• Limites de segurança em variáveis de ambiente numéricas — ZPL_RATE_LIMIT limitado a [1, 600], ZPL_MAX_RETRIES a [0, 5].

Correções de ferramentas

• zpl_simulate resultado 0/0 em entradas positivas (mudou para distributionBias + curto-circuito de entrada idêntica).
• zpl_liquidity desalinhamento entre tabela/veredito (o veredito agora cita contagens por pool).
• zpl_quota detecção automática de plano a partir do config.toml (env > config > "free").
• zpl_quota + zpl_alert precisão da estimativa de tokens — 22 ferramentas agora persistem o tokens_used real em vez de heurística fixa.
• zpl_teach snippet referenciando nome de pacote @zeropointlogic/engine-mcp nunca publicado.
• Entradas duplicadas do Claude Desktop são deduplicadas automaticamente no setup.
• LANGUAGE variável de ambiente de código morto removida.

Consulte CHANGELOG para a lista completa com justificativas.

Novidades na v3.7.0

• O assistente de configuração agora configura automaticamente Cursor e Windsurf, não apenas Claude Desktop. Cada execução corrige claude_desktop_config.json, ~/.cursor/mcp.json e ~/.codeium/windsurf/mcp_config.json em uma única passada. Clientes não instalados são ignorados silenciosamente; cada correção é isolada para que um cliente ausente nunca bloqueie os demais. Arquivos de configuração pré-existentes vazios (comuns no stub {"mcpServers":{}} do Cursor) agora são tratados corretamente.

Novidades na v3.6.1

• Cota do plano gratuito corrigida — todos os docs/cópias agora mostram 5.000 tokens/mês (estava erroneamente "500 tokens / ~14 dias" no rascunho inicial de migração). No lado do engine já era 5.000; esta versão apenas sincroniza o MCP. Consulte CHANGELOG.

Novidades na v3.6.0

• npx zpl-engine-mcp setup — assistente de fluxo de dispositivo em um comando: abre o navegador, autentica com sua conta ZPL, cria uma chave de API por máquina e corrige automaticamente o claude_desktop_config.json. Sem mais copiar e colar.
• Somente chave de usuário — fallback ZPL_SERVICE_KEY removido. O MCP exige uma chave de usuário zpl_u_... para que os limites do plano sejam aplicados por conta.

Novidades na v3.4.3

• Correção de dev local — com ZPL_ENGINE_ALLOW_INSECURE_LOCAL=1, localhost / 127.0.0.1 / ::1 são aceitos como hostnames do engine (não apenas produção). Use com http://127.0.0.1:PORT para um engine local.
• Versão a partir de package.json — o campo version do MCP, a verificação de atualização e os rodapés de relatório não codificam mais strings semver.
• npm test — testes de regressão para validação de URL do engine (npm run build && node --test test/engine-url.test.mjs).

Novidades na v3.4.2

• Reforço de URL do engine — a allowlist padrão é apenas engine.zeropointlogic.io. Engines auto-hospedados: defina ZPL_ENGINE_HOST_ALLOWLIST=your.hostname. HTTP local: ZPL_ENGINE_ALLOW_INSECURE_LOCAL=1 com http://127.0.0.1 apenas. ZPL_ENGINE_DISABLE_URL_GUARD=1 opcional desativa verificações de hostname (não recomendado). Todas as chamadas fetch do engine usam redirect: "error" para que redirecionamentos não possam levar seu token Bearer a uma nova origem.

Novidades na v3.4.1

• v3.4.1 — Correções de bugs: corrigida a inversão de viés do zpl_consistency_test (respostas inconsistentes agora reduzem corretamente o AIN), contagem dupla de orçamento de sessão nas ferramentas de avaliação Claude (reserva antecipada em vez de pós-incremento), cálculo de orçamento do zpl_alert que silenciosamente sempre dizia "OK" (agora usa a mesma estimativa do zpl_quota), estouro de pilha do zpl_validate_input em arrays muito grandes (loop de redução em vez de Math.min(...values)), cache de verificação de versão ignorando sua própria janela de 24h (nome de arquivo corrigido em vez de sufixo PID), strings de versão obsoletas na saída de zpl_account/zpl_report. A Store agora honra ZPL_STORE_PATH (documentado) além do legado ZPL_STORE_DIR. A exportação CSV agora escapa vírgulas/aspas incorporadas. O formato da chave de API é validado no lado do cliente (falha rápida em colagem obviamente errada, evita vazamento acidental de segredos não relacionados no cabeçalho Authorization). Removida uma referência interna de método do engine da saída de zpl_check_response. O zpl_sweep e o zpl_analyze principais agora honram o limitador de taxa por minuto.
• v3.4.0 — 8 novas ferramentas AI Eval (zpl_consistency_test, zpl_sycophancy_score, zpl_refusal_balance, zpl_language_equity, zpl_persona_drift, zpl_safety_boundary, zpl_hallucination_consistency, zpl_emotional_stability) que executam prompts pelo Claude e pontuam distribuições de resposta com o engine ZPL. Exige uma variável de ambiente ANTHROPIC_API_KEY separada. Limite de orçamento de sessão de 100 chamadas Claude por processo para evitar gastos acidentais. Atualização multilíngue de detecção de propaganda para zpl_news_bias / zpl_review_bias: listas de palavras-chave EN + RO + FR + DE + ES + IT com penalidade simétrica de uniformidade (textos 100% apenas positivos OU 100% apenas negativos acionam o mesmo bônus).
• v3.3.0 — Adicionados 4 aliases mais claros com prefixo "balance": zpl_balance_check (= zpl_decide), zpl_balance_compare (= zpl_versus), zpl_balance_pair (= zpl_compare), zpl_balance_rank (= zpl_rank). Tanto os nomes antigos quanto os novos funcionam; os nomes antigos recebem uma nota DEPRECATED na descrição. Usuários existentes continuam funcionando sem alterações.
• v3.2.0 — 4 novas ferramentas: zpl_about (informações do projeto, sem auth), zpl_quota (tokens restantes), zpl_score_only (JSON mínimo para CI/CD), zpl_validate_input (validação gratuita). Verificação automática de atualização, mensagem de cadastro mais amigável, avisos explícitos em ferramentas de hipótese/viés, avisos de tamanho de amostra RNG, e ferramentas de viés reformuladas como "equilíbrio de linguagem" em vez de "falso/parcial".
• v3.1.0 — Adicionada a variável de ambiente ZPL_MODE (pure | coach). O modo puro oculta as pontuações AIN da IA nas ferramentas de avaliação de texto (zpl_check_response, zpl_news_bias, zpl_review_bias) para evitar viés de reatividade / efeito observador.
• v3.0.0 (QUEBRA) — Removidas 5 ferramentas que criavam risco de falsa autoridade: zpl_ask, zpl_certify, zpl_certificate, zpl_predict, zpl_auto_certify. AIN é uma medida de ESTABILIDADE apenas — nunca uma previsão ou recomendação.

Configuração (gratuita, 15 segundos)

Execute isto no seu terminal — ele autentica você, cria uma chave de API e escreve a configuração do seu Claude Desktop para você:

npx zpl-engine-mcp@latest setup

O assistente irá:

1. Abrir seu navegador para aprovar o CLI (cadastre-se se não tiver conta — gratuito, 5.000 tokens/mês, sem cartão de crédito)
2. Salvar a chave em ~/.zpl/config.toml (chmod 600)
3. Corrigir a config MCP de cada cliente suportado que estiver instalado:
   • Claude Desktop — claude_desktop_config.json
   • Cursor — ~/.cursor/mcp.json
   • Windsurf — ~/.codeium/windsurf/mcp_config.json
4. Exibir quais clientes foram configurados e quais devem ser reiniciados.

É isso. Clientes não instalados são ignorados silenciosamente. Se você estiver usando um cliente que não detectamos automaticamente (Claude Code, VS Code, Zed, ...), o assistente imprime o trecho JSON exato para colar na config MCP desse cliente.

{
  "mcpServers": {
    "zpl-engine": {
      "command": "npx",
      "args": ["-y", "zpl-engine-mcp@latest"],
      "env": {
        "ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE",
        "ZPL_MODE": "pure"
      }
    }
  }
}

O que é o ZPL Engine?

O ZPL Engine calcula o AIN (AI Neutrality Index) — uma medida matemática de quão estável ou tendencioso um sistema é. Ele funciona em:

• Finanças — estabilidade de mercado, viés de portfólio, concentração de risco, pares forex, medo e ganância
• Jogos — equilíbrio econômico, justiça de loot, matchmaking, auditoria de gacha, equilíbrio PvP
• IA/ML — justiça de modelo, viés de previsão, equilíbrio de dataset, teste de prompts, benchmarks
• Segurança — distribuição de vulnerabilidades, matriz de risco, pontuação de conformidade
• Crypto — concentração de baleias, risco DeFi, análise de liquidez, tokenomics
• Certificação — verificação de equilíbrio de linguagem em texto, equilíbrio de debate, equilíbrio de notícias, autenticidade de avaliações
• Universal — decisões rápidas, comparação estruturada, ranking AIN, verificação de equilíbrio de resposta

Um engine, múltiplos domínios. O engine não sabe o que seus dados representam — "lentes" de domínio traduzem seus dados específicos para o framework matemático universal.

Lendo os números

• ain — retornado pelo engine em escala 0.0 – 1.0 com 6 casas decimais. A saída legível por humanos mostra em escala 0 – 100 mantendo as casas decimais (93.24/100), nunca arredondado para número inteiro. zpl_score_only retorna o valor bruto do engine sem alterações.
• ain_status — qualidade do equilíbrio: CERTIFIED_NEUTRAL, HIGHLY_NEUTRAL, NEUTRAL, MODERATE_BIAS, SIGNIFICANT_BIAS, HIGH_BIAS.
• status — um campo diferente: o regime de estabilidade, STABLE, ACTIVE, INHIBITED_HIGH, INHIBITED_LOW. Não existe um valor INHIBITED simples. Etapas de varredura carregam status, não ain_status.

Modos (ZPL_MODE)

O ZPL Engine MCP suporta dois modos para como os resultados de avaliação de texto são retornados:

Por que isso importa: a pontuação de estabilidade só funciona se a medição não alterar aquilo que mede. Se uma IA vê "AIN = 42" e depois escreve o próximo parágrafo, sua linguagem naturalmente deriva para justificar a pontuação. O modo puro quebra esse ciclo de feedback.

Defina via env: "ZPL_MODE": "pure" ou "ZPL_MODE": "coach".

Instalação

Via npm (recomendado):

npm install zpl-engine-mcp

Ou clone e compile:

git clone https://github.com/cicicalex/zpl-engine-mcp.git
cd zpl-engine-mcp
npm install
npm run build

Configs alternativas de cliente

Claude Code CLI (.claude/settings.json)

{
  "mcpServers": {
    "zpl-engine": {
      "command": "npx",
      "args": ["-y", "zpl-engine-mcp@latest"],
      "env": {
        "ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE",
        "ZPL_MODE": "pure"
      }
    }
  }
}

Build local

{
  "mcpServers": {
    "zpl-engine": {
      "command": "node",
      "args": ["/path/to/engine-mcp/dist/index.js"],
      "env": {
        "ZPL_API_KEY": "zpl_u_YOUR_KEY_HERE"
      }
    }
  }
}

Cursor / Windsurf

Adicione à sua configuração MCP seguindo a documentação do respectivo IDE, com a mesma estrutura de comando/args/env.

Categorias de Ferramentas (69 ferramentas)

69 ferramentas em 11 categorias: 65 nomes únicos mais 4 aliases de compatibilidade reversa (os pares zpl_balance_*, que reutilizam o handler de outra ferramenta). Cada linha abaixo é um registro ativo, então a tabela soma os mesmos 69.

Novo na v3.2: Ferramentas Meta

Ferramentas Removidas na v3.0.0 (e o motivo)

Exemplos Rápidos

> Analyze my crypto portfolio for balance: BTC 40%, ETH 25%, SOL 15%, AVAX 10%, DOT 10%

> Check if this loot table is fair: Common 60%, Uncommon 25%, Rare 10%, Legendary 5%

> Is my ML model output balanced? Class A: 1200 predictions, Class B: 300 predictions

> Check this AI response for language balance

> Compare React vs Vue across 5 criteria

Planos de Preço

Todos os planos pagos oferecem 20% de desconto com cobrança anual.

Custo de Tokens

O custo de tokens depende do nível de dimensão:

Gerenciamento de Chaves de API

• As chaves são geradas em zeropointlogic.io/dashboard/api-keys
• Formato: zpl_u_ + 48 caracteres hexadecimais (chaves de usuário). v3.5.0+: o MCP aceita apenas chaves de usuário. Chaves de serviço (zpl_s_...) são apenas mecanismo-para-mecanismo — no lado do servidor, com restrição de IP, não utilizáveis via MCP.
• As chaves são submetidas a hash SHA-256 no lado do servidor — o texto simples é exibido uma vez na criação
• Para rotacionar uma chave: crie uma nova chave, atualize sua configuração MCP, reinicie o Claude e depois exclua a chave antiga
• Se uma chave for comprometida, exclua-a imediatamente do painel — ela é invalidada instantaneamente

Variáveis de Ambiente

Arquitetura

Your AI Client (Claude, Cursor, etc.)
    |
    v (MCP Protocol — stdio)
ZPL Engine MCP Server (this package)
    |
    +-- Tool modules (data -> engine params)
    |   +-- finance, gaming, ai-ml, security, crypto
    |   +-- certification, advanced, universal, meta
    |
    v (HTTPS — Bearer auth)
ZPL Engine API (engine.zeropointlogic.io)
    |
    v (Post-binary computation)
    AIN Result (0.0-1.0, 6 decimals)

O servidor MCP nunca vê ou contém a fórmula do mecanismo. Ele envia (d, bias, samples) e recebe (ain, deviation, status). Todo o cálculo acontece no lado do servidor.

Segurança

• Todas as entradas são validadas via esquemas Zod com limites estritos de maxLength
• Chaves de API nunca são registradas ou armazenadas em texto simples localmente
• Lista de permissão de URL do mecanismo — solicitações só vão para engine.zeropointlogic.io a menos que você adicione hosts com ZPL_ENGINE_HOST_ALLOWLIST. Rejeita userinfo incorporado em ZPL_ENGINE_URL (use variáveis de ambiente para chaves). fetch(..., { redirect: "error" }) impede o seguimento de redirecionamentos HTTP que poderiam enviar seu token Bearer para outro lugar.
• Limitação de taxa em memória (configurável)
• Repetição com backoff exponencial para falhas transitórias do mecanismo (apenas 5xx, não 4xx)
• Falha rápida na inicialização se ZPL_API_KEY não estiver definido (exceto para ferramentas sem autenticação)
• O histórico local sanitiza prefixos de chave de API antes de gravar

Proteção de Propriedade Intelectual (v3.0.0+)

O método de cálculo do ZPL Engine é um segredo comercial da Zero Point Logic. Este MCP foi reforçado para nunca expô-lo:

• As saídas das ferramentas retornam apenas pontuação AIN + status + tokens usados. Nenhum valor de viés, desvio, p-output, dimensão ou tempo é exposto.
• O MCP nunca recebe ou processa a fórmula do mecanismo — ele envia (d, bias, samples) ao servidor e recebe (ain, status) de volta.
• Todo o cálculo acontece no lado do servidor no mecanismo proprietário. O código do lado do cliente não contém segredos algorítmicos.
• A v3.0 removeu ferramentas que permitiam que pontuações fornecidas pelo usuário fossem apresentadas como medições oficiais de AIN (risco de autoridade falsa).

Licença

MIT (cobre apenas o código do cliente MCP). O algoritmo de cálculo do ZPL Engine, a fórmula AIN e o processamento no lado do servidor são segredos comerciais proprietários da Zero Point Logic e NÃO são cobertos por esta licença.

Publicador

Zero Point Logic

Links

• ZPL Engine — Site principal
• Finance Monitor — Análise financeira ao vivo
• Documentação da API — Referência completa da API
• Preços — Planos e chaves de API
• Registro Smithery — Descoberta de MCP

Consulte CHANGELOG.md para o histórico completo de versões.