Whissle MCP Server

Acesse a API Whissle para conversão de fala em texto, diarização, tradução e sumarização de texto.

Documentação

Servidor Whissle MCP

Um servidor baseado em Python que fornece acesso aos endpoints da API Whissle para conversão de fala em texto, diarização, tradução e sumarização de texto.

⚠️ Notas Importantes

Este servidor fornece acesso aos endpoints da API Whissle, que podem gerar custos
Cada ferramenta que faz uma chamada de API é marcada com um aviso de custo
Por favor, siga estas diretrizes:
1. Use as ferramentas somente quando solicitado explicitamente pelo usuário
2. Para ferramentas que processam áudio, considere a duração do áudio, pois isso afeta os custos
3. Algumas operações, como tradução ou sumarização, podem ter custos mais altos
4. Ferramentas sem avisos de custo em sua descrição são gratuitas, pois apenas leem dados existentes

Pré-requisitos

Python 3.8 ou superior
pip (instalador de pacotes Python)
Um token de autenticação da API Whissle

Instalação

Clone o repositório:

git clone <repository-url>
cd whissle_mcp

Crie e ative um ambiente virtual:

python -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate

Instale os pacotes necessários:
```
pip install -e .
```
Configure as variáveis de ambiente: Crie um arquivo .env na raiz do projeto com o seguinte conteúdo:
```
WHISSLE_AUTH_TOKEN=insert_auth_token_here  # Replace with your actual Whissle API token
WHISSLE_MCP_BASE_PATH=/path/to/your/base/directory
```
⚠️ Importante: Nunca envie seu token real para o repositório. O arquivo .env está incluído no .gitignore para evitar commits acidentais.

Configure a Integração com Claude: Copie claude_config.example.json para claude_config.json e atualize os caminhos:

{
    "mcpServers": {
        "Whissle": {
            "command": "/path/to/your/venv/bin/python",
            "args": [
                "/path/to/whissle_mcp/server.py"
            ],
            "env": {
                "WHISSLE_AUTH_TOKEN": "insert_auth_token_here"
            }
        }
    }
}

Substitua /path/to/your/venv/bin/python pelo caminho real do seu interpretador Python no ambiente virtual
Substitua /path/to/whissle_mcp/server.py pelo caminho real do seu arquivo server.py

Configuração

Variáveis de Ambiente

WHISSLE_AUTH_TOKEN: Seu token de autenticação da API Whissle (obrigatório)
- Esta é uma credencial sensível que nunca deve ser compartilhada ou enviada para o controle de versão
- Contate seu administrador para obter um token válido
- Armazene-o com segurança no seu arquivo .env local
WHISSLE_MCP_BASE_PATH: Diretório base para operações de arquivo (opcional, padrão: Área de Trabalho do usuário)

Formatos de Áudio Suportados

O servidor suporta os seguintes formatos de áudio:

WAV (.wav)
MP3 (.mp3)
OGG (.ogg)
FLAC (.flac)
M4A (.m4a)

Limites de Tamanho de Arquivo

Tamanho máximo do arquivo: 25 MB
Arquivos maiores que este limite serão rejeitados

Ferramentas Disponíveis

1. Conversão de Fala em Texto

Converta fala em texto usando a API Whissle.

response = speech_to_text(
    audio_file_path="path/to/audio.wav",
    model_name="en-NER",  # Default model
    timestamps=True,      # Include word timestamps
    boosted_lm_words=["specific", "terms"],  # Words to boost in recognition
    boosted_lm_score=80   # Score for boosted words (0-100)
)

2. Diarização de Fala

Converta fala em texto com identificação do falante.

response = diarize_speech(
    audio_file_path="path/to/audio.wav",
    model_name="en-NER",  # Default model
    max_speakers=2,       # Maximum number of speakers to identify
    boosted_lm_words=["specific", "terms"],
    boosted_lm_score=80
)

3. Tradução de Texto

Traduza texto de um idioma para outro.

response = translate_text(
    text="Hello, world!",
    source_language="en",
    target_language="es"
)

4. Sumarização de Texto

Resuma texto usando um modelo LLM.

response = summarize_text(
    content="Long text to summarize...",
    model_name="openai",  # Default model
    instruction="Provide a brief summary"  # Optional
)

5. Listar Modelos ASR

Liste todos os modelos ASR disponíveis e suas capacidades.

response = list_asr_models()

Formato de Resposta

Conversão de Fala em Texto e Diarização

{
    "transcript": "The transcribed text",
    "duration_seconds": 10.5,
    "language_code": "en",
    "timestamps": [
        {
            "word": "The",
            "startTime": 0,
            "endTime": 100,
            "confidence": 0.95
        }
    ],
    "diarize_output": [
        {
            "text": "The transcribed text",
            "speaker_id": 1,
            "start_timestamp": 0,
            "end_timestamp": 10.5
        }
    ]
}

Tradução

{
    "type": "text",
    "text": "Translation:\nTranslated text here"
}

Sumarização

{
    "type": "text",
    "text": "Summary:\nSummarized text here"
}

Resposta de Erro

{
    "error": "Error message here"
}

Tratamento de Erros

O servidor inclui tratamento robusto de erros com:

Tentativas automáticas para erros HTTP 500
Mensagens de erro detalhadas para diferentes cenários de falha
Validação de arquivos (existência, tamanho, formato)
Verificações de autenticação

Tipos comuns de erro:

HTTP 500: Erro do servidor (com mecanismo de tentativa)
HTTP 413: Arquivo muito grande
HTTP 415: Formato de arquivo não suportado
HTTP 401/403: Erro de autenticação

Executando o Servidor

Inicie o servidor:
```
mcp serve
```
O servidor estará disponível na porta MCP padrão (geralmente 8000)

Testes

Um script de teste é fornecido para verificar a funcionalidade de todas as ferramentas:

python test_whissle.py

O script de teste irá:

Verificar o token de autenticação
Testar todas as ferramentas disponíveis
Fornecer saída detalhada de cada operação
Tratar erros de forma adequada

Suporte

Para problemas ou dúvidas, por favor:

Verifique as mensagens de erro para obter detalhes específicos
Verifique seu token de autenticação
Certifique-se de que seus arquivos de áudio atendem aos requisitos
Contate o suporte da Whissle para problemas relacionados à API

Licença

[Adicione suas informações de licença aqui]