supertonic3-mcp

supertonic3-mcp

TTS local, no dispositivo, para Claude e Cursor, alimentado pelo Supertonic 3. Sem chave de API. Sem nuvem. Uma ferramenta interna de código aberto pela Halozen — construímos inteligência de conformidade de IA para construção.

Não afiliado à Supertone Inc.

Exponha speak, list_voices e list_expressions para Claude Desktop, Cursor ou qualquer cliente MCP via STDIO.

Início rápido (TTHW < 3 min)

git clone https://github.com/nextic-tech/supertonic3-mcp && cd supertonic3-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Optional: pre-download model for offline use (~400MB)
supertonic3-mcp preload

# Run MCP server (STDIO)
supertonic3-mcp

Configuração do MCP no Cursor

Adicione a .cursor/mcp.json (ou Configurações do Cursor → MCP):

{
  "mcpServers": {
    "supertonic3": {
      "command": "/absolute/path/to/supertonic-tts/.venv/bin/supertonic3-mcp",
      "args": []
    }
  }
}

A primeira inicialização do servidor baixa o modelo Supertonic para ~/.cache/supertonic3/ a menos que você tenha executado preload antes.

Ferramentas

Ferramenta	Descrição
speak	Sintetiza texto em um arquivo WAV; retorna caminho absoluto + metadados
list_voices	Vozes integradas (voice_id, gender)
list_expressions	Tags inline (<laugh>, <breath>, …) com descrições

Parâmetros de speak

• text — 1–5000 caracteres; tags de expressão permitidas
• voice_id — opcional (M1, F1, …)
• language — ISO 639-1 (en, ko, ja, …). Para texto não inglês, sempre defina language=. Padrão: en.
• speed — 0.7 a 2.0 (intervalo do SDK)
• play — se true, reproduz áudio nesta máquina via afplay (macOS) ou aplay (Linux). Não suportado no Windows.

Os arquivos WAV são gravados em /tmp/supertonic_*.wav (macOS/Linux). O Windows não é suportado para caminhos de saída de síntese na v1.0.

Exemplo de retorno:

Audio saved to /tmp/supertonic_abc123.wav (1.4s, voice: M1, lang: en)

Desempenho (este repositório)

Medido em Apple M3, supertonic 1.3.1 — veja benchmark/results.md.

Cenário	FSL mediano
Quente (modelo carregado)	~0,82s
Frio (novo TTS() por chamada)	~0,81s

FSL = tempo desde synthesize() até o WAV gravado (sem streaming, sem play=True).

Re-executar: python benchmark/run.py

Uso offline

supertonic3-mcp preload

Baixa os pesos ONNX atomicamente para ~/.cache/supertonic3/ e imprime somas de verificação SHA256. Após o pré-carregamento, a síntese funciona sem acesso à rede.

Desenvolvimento

pip install -e ".[dev]"
pytest

Os testes simulam o SDK Supertonic (sem rede no CI).

Novidades na v1.1

• listen() — Whisper fala para texto (pip install supertonic3-mcp[stt])
• Transporte SSE + imagem Docker para agentes remotos
• Fluxo de publicação no PyPI

Licença

MIT (este pacote). O SDK Supertonic é MIT; os pesos do modelo usam OpenRAIL-M.

Aviso legal

A fala gerada por IA não substitui orientação certificada de segurança, jurídica ou médica. Apenas para fins de demonstração.