MCP Server Whisper

MCP Server Whisper

[!WARNING] Este projeto foi movido. O desenvolvimento ativo migrou para TJC-LP/sanzaru. Este repositório não é mais mantido e será arquivado. Atualize suas dependências e issues para o novo repositório.

Visão Geral

O MCP Server Whisper fornece uma forma padronizada de processar arquivos de áudio através dos serviços mais recentes de transcrição e fala da OpenAI. Ao implementar o Model Context Protocol, ele permite que assistentes de IA como o Claude interajam perfeitamente com capacidades de processamento de áudio.

Principais recursos:

• 🔍 Busca avançada de arquivos com padrões regex, filtragem de metadados de arquivos e capacidades de ordenação
• ⚡ Processamento paralelo nativo do MCP - chame múltiplas ferramentas simultaneamente
• 🔄 Conversão de formato entre tipos de áudio suportados
• 📦 Compressão automática para arquivos grandes demais
• 🎯 Transcrição multi-modelo com suporte para todos os modelos de áudio da OpenAI
• 🗣️ Chat de áudio interativo com modelos de áudio GPT-4o
• ✏️ Transcrição aprimorada com prompts especializados e suporte a timestamps
• 🎙️ Geração de texto-para-fala com vozes, instruções e velocidade personalizáveis
• 📊 Metadados abrangentes incluindo duração, tamanho do arquivo e suporte a formatos
• 🚀 Cache de alto desempenho para operações repetidas
• 🔒 Respostas type-safe com modelos Pydantic para todas as saídas das ferramentas

Nota: Este projeto é não oficial e não é afiliado, endossado ou patrocinado pela OpenAI. Ele fornece uma interface Model Context Protocol para as APIs publicamente disponíveis da OpenAI.

Instalação

# Clone the repository
git clone https://github.com/arcaputo3/mcp-server-whisper.git
cd mcp-server-whisper

# Using uv 
uv sync

# Set up pre-commit hooks
uv run pre-commit install

Configuração de Ambiente

Crie um arquivo .env com base no .env.example fornecido:

cp .env.example .env

Edite o .env com seus valores reais:

OPENAI_API_KEY=your_openai_api_key
AUDIO_FILES_PATH=/path/to/your/audio/files

Nota: As variáveis de ambiente devem estar disponíveis em tempo de execução. Para desenvolvimento local com Claude, use uma ferramenta como dotenv-cli para carregá-las (veja a seção Uso abaixo).

Uso

Desenvolvimento Local com Claude

O projeto inclui um arquivo de configuração .mcp.json para desenvolvimento local com Claude. Para usá-lo:

1. Garanta que seu arquivo .env esteja configurado com as variáveis de ambiente necessárias
2. Inicie o Claude com as variáveis de ambiente carregadas:

bunx dotenv-cli -- claude

Isso irá:

• Carregar variáveis de ambiente do seu arquivo .env
• Iniciar o Claude com o servidor MCP configurado conforme .mcp.json
• Habilitar hot-reload durante o desenvolvimento

A configuração .mcp.json:

{
  "mcpServers": {
    "whisper": {
      "command": "uv",
      "args": ["run", "mcp-server-whisper"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "AUDIO_FILES_PATH": "${AUDIO_FILES_PATH}"
      }
    }
  }
}

Ferramentas MCP Expostas

Gerenciamento de Arquivos de Áudio

• list_audio_files - Lista arquivos de áudio com opções abrangentes de filtragem e ordenação:
  • Filtrar por correspondência de padrão regex nos nomes de arquivos
  • Filtrar por tamanho do arquivo, duração, hora de modificação ou formato
  • Ordenar por nome, tamanho, duração, hora de modificação ou formato
  • Retorna FilePathSupportParams type-safe com metadados completos
• get_latest_audio - Obtém o arquivo de áudio modificado mais recentemente com informações de suporte do modelo

Processamento de Áudio

• convert_audio - Converte arquivos de áudio para formatos suportados (mp3 ou wav)
  • Retorna AudioProcessingResult com o caminho de saída
• compress_audio - Comprime arquivos de áudio que excedem os limites de tamanho
  • Retorna AudioProcessingResult com o caminho de saída

Transcrição

• transcribe_audio - Transcrição avançada usando os modelos da OpenAI:

  • Suporta whisper-1, gpt-4o-transcribe e gpt-4o-mini-transcribe
  • Prompts personalizados para transcrição guiada
  • Granularidades opcionais de timestamp para temporização em nível de palavra e segmento
  • Opção de formato de resposta JSON
  • Retorna TranscriptionResult com texto, dados de uso e timestamps opcionais

• chat_with_audio - Análise interativa de áudio usando modelos de áudio GPT-4o:

  • Suporta gpt-4o-audio-preview (recomendado) e versões datadas
  • Nota: gpt-4o-mini-audio-preview tem limitações com chat de áudio e não é recomendado
  • Prompts de sistema e usuário personalizados
  • Fornece respostas conversacionais ao conteúdo de áudio
  • Retorna ChatResult com o texto da resposta

• transcribe_with_enhancement - Transcrição aprimorada com templates especializados:

  • detailed - Inclui detalhes de tom, emoção e contexto
  • storytelling - Transforma a transcrição em forma narrativa
  • professional - Cria transcrições formais e apropriadas para negócios
  • analytical - Adiciona análise de padrões de fala e pontos-chave
  • Retorna TranscriptionResult com saída aprimorada

Texto-para-Fala

• create_audio - Gera áudio de texto-para-fala usando a API TTS da OpenAI:
  • Suporta gpt-4o-mini-tts (preferido) e outros modelos de fala
  • Múltiplas opções de voz (alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar)
  • Ajuste de velocidade e instruções personalizadas
  • Caminhos de arquivo de saída personalizáveis
  • Lida com textos de qualquer tamanho dividindo e unindo automaticamente segmentos de áudio
  • Retorna TTSResult com o caminho de saída

Formatos de Áudio Suportados

Nota: Arquivos maiores que 25MB são automaticamente comprimidos para atender aos limites da API.

Exemplo de Uso com Claude

Claude, please transcribe my latest audio file with detailed insights.

Claude, list all my audio files that are longer than 5 minutes and were created after January 1st, 2024, sorted by size.

Claude, find all MP3 files with "interview" in the filename and create professional transcripts for each one.

Claude, create audio with this script: "Welcome to our podcast! Today we'll be discussing artificial intelligence trends in 2025." Use the shimmer voice.

Configuração com Claude Desktop

Para uso em produção com Claude Desktop (em oposição ao desenvolvimento local), adicione isto ao seu claude_desktop_config.json:

UVX

{
  "mcpServers": {
    "whisper": {
      "command": "uvx",
      "args": ["mcp-server-whisper"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key",
        "AUDIO_FILES_PATH": "/path/to/your/audio/files"
      }
    }
  }
}

Recomendação (Somente Mac OS)

• Instale o Screen Recorder By Omi (gratuito)
• Defina AUDIO_FILES_PATH como /Users/<user>/Movies/Omi Screen Recorder e substitua <user> pelo seu nome de usuário
• Ao gravar áudio com o aplicativo, você pode transcrever múltiplos arquivos em paralelo com o Claude

Desenvolvimento

Este projeto usa ferramentas modernas de desenvolvimento Python, incluindo uv, pytest, ruff e mypy.

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Format code
uv run ruff format src

# Lint code
uv run ruff check src

# Run type checking (strict mode)
uv run mypy --strict src

# Run the pre-commit hooks
pre-commit run --all-files

Fluxo de Trabalho CI/CD

O projeto usa GitHub Actions para CI/CD:

1. Lint e Verificação de Tipos: Garante a qualidade do código com ruff e verificação estrita de tipos com mypy
2. Testes: Executa testes em múltiplas versões do Python (3.10, 3.11, 3.12, 3.13, 3.14, 3.14t)
3. Release e Publicação: Fluxo de trabalho com gatilho duplo para gerenciamento flexível de releases

Nota: Python 3.14t é a versão free-threaded (sem GIL) para testar paralelismo real.

Criando um Novo Release

O fluxo de trabalho de release suporta duas abordagens:

Opção 1: Release Automatizado (Recomendado)

Envie uma tag para criar automaticamente um release e publicar no PyPI:

# 1. Update version in pyproject.toml
# Edit the version field manually, e.g., "1.0.0" -> "1.1.0"

# 2. Update __version__ in src/mcp_server_whisper/__init__.py to match

# 3. Update the lock file
uv lock

# 4. Commit the version bump
git add pyproject.toml src/mcp_server_whisper/__init__.py uv.lock
git commit -m "chore: bump version to 1.1.0"

# 5. Create and push the version tag
git tag v1.1.0
git push origin main
git push origin v1.1.0

Isso irá:

• Verificar se a versão da tag corresponde ao pyproject.toml
• Compilar o pacote
• Criar um release no GitHub com notas geradas automaticamente
• Publicar automaticamente no PyPI

Opção 2: Release Manual

Crie um release manualmente pela interface do GitHub e depois publique opcionalmente:

1. Vá para Releases no GitHub
2. Clique em "Draft a new release"
3. Crie uma nova tag ou selecione uma existente
4. Preencha os detalhes do release
5. Clique em "Publish release"

Quando você publicar o release, o fluxo de trabalho publicará automaticamente no PyPI. Você também pode criar um release de rascunho para adiar a publicação.

Filosofia de Design da API

O MCP Server Whisper segue um design de API plano e type-safe otimizado para clientes MCP:

• Argumentos Planos: Todas as ferramentas aceitam parâmetros planos em vez de objetos aninhados para chamadas mais simples e intuitivas
• Respostas Type-Safe: Cada ferramenta retorna um modelo Pydantic fortemente tipado (TranscriptionResult, ChatResult, AudioProcessingResult, TTSResult)
• Operações de Item Único: Uma chamada processa um arquivo, com o protocolo MCP lidando com paralelismo nativamente
• Tratamento de Erros por Arquivo: Falhas são isoladas em operações individuais, não em lotes inteiros
• Autodocumentável: Type hints fornecem autocompletar e validação em IDEs e modelos de IA

Este design torna significativamente mais fácil para assistentes de IA usar as ferramentas corretamente e lidar com os resultados de forma confiável.

Como Funciona

Para informações detalhadas de arquitetura, veja a Documentação de Arquitetura.

O MCP Server Whisper é construído sobre o Model Context Protocol, que padroniza como modelos de IA interagem com ferramentas externas e fontes de dados. O servidor:

1. Expõe Capacidades de Processamento de Áudio: Através de interfaces padronizadas de ferramentas MCP com APIs planas e type-safe
2. Implementa Processamento Paralelo: Usando concorrência estruturada do anyio; clientes MCP lidam com paralelismo nativamente
3. Gerencia Operações de Arquivo: Lida com detecção, validação, conversão e compressão
4. Fornece Transcrição Rica: Via diferentes modelos da OpenAI e templates de aprimoramento
5. Otimiza o Desempenho: Com mecanismos de cache para operações repetidas
6. Garante Type Safety: Todas as respostas usam modelos Pydantic para validação e suporte a IDE

Por baixo dos panos, ele usa:

• pydub para manipulação de arquivos de áudio (com audioop-lts para Python 3.13+)
• anyio para concorrência estruturada e gerenciamento de grupos de tarefas
• aioresult para coletar resultados de grupos de tarefas paralelas
• Os modelos de transcrição mais recentes da OpenAI (incluindo gpt-4o-transcribe)
• Os modelos de áudio GPT-4o da OpenAI para compreensão aprimorada
• O gpt-4o-mini-tts da OpenAI para síntese de fala de alta qualidade
• FastMCP para implementação simplificada do servidor MCP
• Type hints e validação estrita com mypy em todo o código

Contribuindo

Contribuições são bem-vindas! Por favor, siga estes passos:

1. Faça um fork do repositório
2. Crie um novo branch para sua funcionalidade (git checkout -b feature/amazing-feature)
3. Faça suas alterações
4. Execute os testes e o linting (uv run pytest && uv run ruff check src && uv run mypy --strict src)
5. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
6. Envie para o branch (git push origin feature/amazing-feature)
7. Abra um Pull Request

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Agradecimentos

• Model Context Protocol (MCP) - Para a especificação do protocolo
• pydub - Para processamento de áudio
• OpenAI Whisper - Para transcrição de áudio
• FastMCP - Para implementação do servidor MCP
• Anthropic Claude - Para interação em linguagem natural
• MCP Review - Este servidor MCP é certificado pela MCP Review