ZettaQuant V-SLM

zettaquant-vslm-mcp

Servidor MCP que expõe o ZettaQuant V-SLM para qualquer host LLM compatível com MCP.

Adicione três linhas à configuração do seu Claude Desktop / Cursor / Zed / Windsurf e seu modelo poderá filtrar contexto ruidoso (transcrições de teleconferências de resultados, artigos de notícias, relatórios longos, linhas de log) usando o classificador de relevância condicionado por tópico do ZettaQuant — normalmente reduzindo o gasto com tokens antes mesmo de o modelo de linguagem ver a entrada.

---

O que ele expõe

Uma ferramenta, via stdio, através do Model Context Protocol:

Ferramenta	Finalidade
vslm_predict(sentences, query)	Filtra sentences apenas para aqueles relevantes a query. Retorna relevant_sentences além de estatísticas. Usa o V-SLM de domínio amplo general_context_agent internamente.

O LLM decide quando chamá-lo por conta própria — nenhum código que você precise escrever no host.

---

Instalação e configuração

Você precisa de uma chave de API ZettaQuant com o escopo vslm. Obtenha uma em zettaquant.ai (ou fale com seu contato de conta).

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zettaquant-vslm": {
      "command": "uvx",
      "args": ["zettaquant-vslm-mcp"],
      "env": {
        "ZQ_API_KEY": "<your api key>"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas aparecem no menu "Tools".

Cursor

Edite ~/.cursor/mcp.json:

{
  "mcpServers": {
    "zettaquant-vslm": {
      "command": "uvx",
      "args": ["zettaquant-vslm-mcp"],
      "env": { "ZQ_API_KEY": "<your api key>" }
    }
  }
}

Reinicie o Cursor.

Zed

Em ~/.config/zed/settings.json:

{
  "context_servers": {
    "zettaquant-vslm": {
      "command": {
        "path": "uvx",
        "args": ["zettaquant-vslm-mcp"],
        "env": { "ZQ_API_KEY": "<your api key>" }
      }
    }
  }
}

Windsurf / outros hosts MCP

Qualquer host que suporte o formato de configuração padrão mcpServers funciona — use o mesmo bloco command + args + env acima.

---

Variáveis de ambiente

Variável	Obrigatória	Padrão	Observações
ZQ_API_KEY	Sim	—	Sua chave de API ZettaQuant. Deve ter o escopo vslm.
ZQ_BASE_URL		https://api.zettaquant.ai	Substituição para staging ou um gateway privado.

---

Exemplos de uso no LLM

Após a instalação, basta perguntar naturalmente. Alguns prompts que acionarão vslm_predict:

• "Aqui estão 40 frases da teleconferência de resultados do 3º trimestre da Apple. Separe as que falam sobre planos de capex em IA."
• "Filtre estas linhas de log para qualquer coisa relacionada a movimento lateral."
• "Colei uma seção de riscos de um 10-K. Mostre apenas frases sobre exposição na cadeia de suprimentos."

O modelo chama vslm_predict internamente, recebe as frases relevantes e trabalha a partir delas — mais barato e mais preciso do que ler a entrada completa.

---

Desenvolvimento

uv venv
uv pip install -e .
export ZQ_API_KEY="..."
python -m zettaquant_vslm_mcp

O servidor fala JSON-RPC em stdin/stdout. Para testá-lo manualmente, use o MCP Inspector:

npx @modelcontextprotocol/inspector uvx zettaquant-vslm-mcp

---

Solução de problemas

• "ZQ_API_KEY is not set" nos logs do host → o bloco env na sua configuração MCP não foi propagado. Confirme o caminho do arquivo de configuração e reinicie o host.
• 401 na saída da ferramenta → a chave é válida, mas está errada. Teste diretamente: curl -H "x-api-key: $ZQ_API_KEY" https://api.zettaquant.ai/v1/usage/me.
• ZettaQuant access denied (403) → sua chave não tem o escopo vslm. Entre em contato com a ZettaQuant.
• ZettaQuant quota exceeded (429) → você atingiu seu limite por período; a mensagem de erro inclui o horário de redefinição.

---

Licença

MIT.