Typecast API

typecast-api-mcp-server

Servidor MCP para typecast-api, permitindo integração perfeita com clientes MCP. Este projeto fornece uma forma padronizada de interagir com a API Typecast por meio do Model Context Protocol.

Sobre

Este projeto implementa um servidor Model Context Protocol para a API Typecast, permitindo que clientes MCP interajam com a API Typecast de forma padronizada.

Modelos Suportados

Modelo	Descrição	Controle de Emoção
ssfm-v30	Modelo mais recente (recomendado)	Predefinição + Modo Inteligente
ssfm-v21	Modelo de produção estável	Somente predefinição

Recursos do ssfm-v30

• 7 Predefinições de Emoção: normal, feliz, triste, bravo, sussurro, tom acima, tom abaixo
• Modo Inteligente: A IA infere automaticamente a emoção a partir do contexto usando previous_text e next_text
• 37 Idiomas: Suporte estendido a idiomas

Status de Implementação de Recursos

Recurso	Status
Gerenciamento de Voz
Documentação de Pesquisa	✅
Obter Vozes (API V2)	✅
Obter Vozes com filtro use_cases	✅
Obter Voz (API V2)	✅
Recomendar Vozes	✅
Texto para Fala	✅
Texto para Fala (Streaming)	✅
Texto para Fala (com Timestamps)	✅
Obter Minha Assinatura	✅
Reproduzir Áudio	✅
Controles de Saída
Normalização de loudness target_lufs	✅
Suporte ssfm-v30
Modo Predefinição	✅
Modo Inteligente	✅
Clonagem Rápida de Voz
Clonar Voz	✅
Excluir Voz Clonada	✅

Clonagem Rápida de Voz

O servidor MCP expõe duas ferramentas para fluxos de trabalho temporários de voz personalizada:

• clone_voice: cria uma voz personalizada clonada rapidamente a partir de um arquivo WAV ou MP3 local.
• delete_cloned_voice: exclui um ID de voz clonada que começa com uc_.

Restrições da clonagem rápida:

• O nome da voz deve ter de 1 a 30 caracteres.
• A amostra de áudio deve ser WAV ou MP3.
• A amostra de áudio deve ter 25 MB ou menos.
• Use ssfm-v30 a menos que você tenha um motivo específico de compatibilidade.

Fluxo típico:

1. Execute clone_voice com name, audio_file_path e model opcional.
2. Use o next_step_voice_id e next_step_model retornados em text_to_speech, text_to_speech_stream ou text_to_speech_with_timestamps.
3. Execute delete_cloned_voice quando a voz clonada temporária não for mais necessária.

Recomendações de Voz

Use recommend_voices quando você souber o estilo, o humor, o idioma ou o caso de uso desejado, mas ainda não souber o ID exato da voz. Ele chama GET /v1/voices/recommendations e retorna candidatos ordenados por pontuação.

A resposta da recomendação contém intencionalmente apenas voice_id, voice_name e score. Se um agente precisar de detalhes sobre uma voz recomendada, chame get_voice para cada ID retornado ou get_voices para uma lista filtrada mais ampla antes de usar o ID no TTS.

Configuração

Servidor Hospedado

O endpoint HTTP Streamable hospedado é:

https://typecast-api-docs-web-production.up.railway.app/mcp

Sem autenticação, o servidor expõe apenas search_documentation. Envie uma chave da API Typecast em cada solicitação MCP para desbloquear as ferramentas da API Typecast:

X-API-KEY: YOUR_TYPECAST_API_KEY

Authorization: Bearer YOUR_TYPECAST_API_KEY também é suportado. O servidor hospedado não armazena a chave. O áudio gerado é retornado como uma URL de download privada e impossível de adivinhar, que expira após uma hora. play_audio continua sendo uma ferramenta somente local, pois um servidor hospedado não pode reproduzir som no dispositivo do cliente MCP.

No servidor hospedado, clone_voice aceita apenas audio_base64 juntamente com um audio_filename que termina em .wav ou .mp3. audio_file_path está disponível somente quando este servidor MCP é executado localmente.

Variáveis de Ambiente

Defina as seguintes variáveis de ambiente:

TYPECAST_API_KEY=<your-api-key>
TYPECAST_OUTPUT_DIR=<your-output-directory> # default: ~/Downloads/typecast_output

Uso com Claude Desktop / Cursor

Você pode adicionar o seguinte ao seu claude_desktop_config.json ou às configurações MCP do Cursor:

Recomendado: Usando uvx (sem necessidade de instalação)

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/neosapience/typecast-api-mcp-server.git",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

Este método busca e executa automaticamente o servidor do GitHub sem clonagem manual.

Nota para usuários de Linux: Se você estiver executando no Linux, você precisa adicionar a variável de ambiente XDG_RUNTIME_DIR à seção env:

"env": {
  "TYPECAST_API_KEY": "YOUR_API_KEY",
  "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR",
  "XDG_RUNTIME_DIR": "/run/user/1000"
}

Alternativa: Instalação Local

Se você preferir clonar e executar localmente:

Git Clone

git clone https://github.com/neosapience/typecast-api-mcp-server.git
cd typecast-api-mcp-server

Dependências

Este projeto requer Python 3.10 ou superior e usa uv para gerenciamento de pacotes.

# Create virtual environment and install packages
uv venv
uv pip install -e .

Configuração Local

{
  "mcpServers": {
    "typecast-api-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/PATH/TO/YOUR/PROJECT",
        "run",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR"
      }
    }
  }
}

Substitua /PATH/TO/YOUR/PROJECT pelo caminho real onde seu projeto está localizado.

Execução Manual

Você também pode executar o servidor manualmente:

uv run python app/main.py

Contribuindo

Contribuições são sempre bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT