Summarize MCP

Converte resumos de texto em fala usando a API de Texto-para-Fala da OpenAI e os reproduz em segundo plano.

Documentação

summarize-mcp

🤖 Co-autorado com Claude Code - Tornando resumos de IA audíveis desde 2025! 🔊

Um servidor Model Context Protocol (MCP) que converte resumos de texto em fala usando a API TTS da OpenAI e os reproduz em segundo plano em todas as principais plataformas (macOS, Windows, Linux).

🌟 Visão Geral

O summarize-mcp permite que LLMs convertam qualquer resumo de texto em fala com som natural usando os modelos de texto-para-fala de última geração da OpenAI. Perfeito para criar resumos em áudio de documentos, artigos ou qualquer conteúdo que se beneficie de uma apresentação auditiva.

🚀 Principais Recursos

🎯 Simples e Focado: Uma ferramenta que faz uma coisa excepcionalmente bem
🎤 Múltiplas Vozes: Escolha entre 10 vozes distintas da OpenAI (alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer)
🎨 Instruções Personalizadas: Controle como o texto deve ser falado
🔧 Reprodução em Segundo Plano: O áudio é reproduzido em segundo plano sem bloqueios
🌍 Multiplataforma: Funciona em macOS, Windows e Linux
💾 Preferências Persistentes: Salve suas configurações favoritas de voz e tom
🎯 Múltiplas Ferramentas: Definir voz, definir tom e reproduzir resumos
🧹 Limpeza Automática: Arquivos temporários são limpos automaticamente
🛡️ Type-Safe: Anotações de tipo completas em Python com validação Pydantic
📊 Logging Abrangente: Modo de depuração para solução de problemas
⚡ Otimizado para Desempenho: Manipulação e limpeza eficiente de arquivos

📋 Pré-requisitos

Python 3.8 ou superior
Chave da API OpenAI com acesso aos modelos TTS
Player de Áudio (detectado automaticamente):
- macOS: afplay integrado (sem necessidade de instalação)
- Windows: Windows Media Player integrado (sem necessidade de instalação)
- Linux: Um dos seguintes: mpg123, sox (play), ffmpeg (ffplay), vlc (cvlc) ou alsa-utils (aplay)

📦 Instalação

git clone https://github.com/FiveOhhWon/summarize-mcp.git
cd summarize-mcp
pip install -e .

🏃 Configuração

Claude Desktop

Adicione esta configuração ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuração:

{
  "mcpServers": {
    "summarize": {
      "command": "python",
      "args": ["/absolute/path/to/summarize-mcp/src/summarize_mcp/server.py"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

Variáveis de Ambiente

OPENAI_API_KEY (obrigatório): Sua chave da API OpenAI
DEBUG (opcional): Defina como "true" para logging detalhado

🛠️ Ferramentas Disponíveis

play_summary

Converte texto em fala e o reproduz em segundo plano. Usa as preferências salvas de voz e tom, a menos que sejam substituídas.

Parâmetros:

summary (obrigatório): O texto a ser convertido em fala
voice (opcional): Voz a ser usada - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage ou shimmer (usa a preferência salva se não for especificada)
instructions (opcional): Instruções sobre como o texto deve ser falado (usa o tom salvo se não for especificado)

Exemplo:

{
  "summary": "The quick brown fox jumps over the lazy dog. This pangram contains all letters of the alphabet.",
  "voice": "nova",
  "instructions": "Speak slowly and clearly, emphasizing each word."
}

set_voice

Define a voz padrão para todas as conversões futuras de texto-para-fala.

Parâmetros:

voice (obrigatório): A voz a ser usada - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage ou shimmer

Exemplo:

{
  "voice": "nova"
}

set_tone

Define o tom/instruções padrão para como o texto deve ser falado em todas as solicitações TTS futuras.

Parâmetros:

tone (obrigatório): O tom/instruções a serem usados (por exemplo, "Fale devagar e com calma", "Seja entusiasmado e energético")

Exemplo:

{
  "tone": "Speak in a warm, friendly manner with moderate pacing"
}

📖 Exemplos de Uso

Resumo Básico

"Please summarize this article and play it as audio"

O LLM irá:

Gerar um resumo do conteúdo
Usar a ferramenta play_summary para convertê-lo em fala
O áudio será reproduzido em segundo plano com as preferências salvas

Definir Voz Padrão

"Set the default voice to nova"

Isso salvará "nova" como sua voz preferida para todos os resumos futuros.

Definir Tom Padrão

"Set the tone to be warm and conversational with a slower pace"

Isso salvará sua preferência de tom para todos os resumos futuros.

Voz Personalizada (Uma Vez)

"Summarize this document and play it using the 'sage' voice"

Isso usará "sage" apenas para este resumo, sem alterar seu padrão.

Com Instruções Personalizadas (Uma Vez)

"Create an audio summary of this text. Make it sound enthusiastic and energetic."

Isso usará instruções personalizadas apenas para este resumo.

🎯 Opções de Voz

Voz	Descrição
`alloy`	Neutra e equilibrada
`ash`	Calorosa e envolvente
`ballad`	Expressiva e dramática
`coral`	Clara e profissional (padrão)
`echo`	Suave e reflexiva
`fable`	Expressiva e animada
`nova`	Amigável e otimista
`onyx`	Profunda e autoritativa
`sage`	Sábia e ponderada
`shimmer`	Suave e gentil

🧪 Desenvolvimento

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run the server
python -m summarize_mcp

# Run tests
python test.py

# Run with debug logging
DEBUG=true python -m summarize_mcp

🏗️ Arquitetura

summarize-mcp/
├── src/
│   └── summarize_mcp/
│       ├── __init__.py      # Package initialization
│       ├── __main__.py      # Entry point for python -m
│       └── server.py        # Main MCP server implementation
├── pyproject.toml           # Python project metadata
├── requirements.txt         # Python dependencies
├── test.py                  # Test script
└── README.md               # This file

🔧 Detalhes Técnicos

Formato de Áudio: MP3 (formato de saída TTS da OpenAI)
Arquivos Temporários: Armazenados no diretório temporário do sistema
Limpeza de Arquivos: Limpeza automática após 10 segundos (configurável)
Limpeza de Arquivos Antigos: Arquivos com mais de 1 hora são limpos na inicialização
Suporte a Plataformas:
- macOS: Usa o afplay integrado
- Windows: Usa PowerShell com Windows Media Player
- Linux: Detecta automaticamente o player disponível (mpg123, sox, ffmpeg, vlc, alsa)
- Fallback: Abre com o aplicativo de áudio padrão do sistema
Gerenciamento de Estado:
- Preferências salvas em ~/.summarize-mcp-state.json
- Persiste configurações de voz e tom entre sessões
- Carregamento automático na inicialização
Tratamento de Erros: Tratamento abrangente de erros com tipos de erro específicos
Validação: Validação de entrada usando modelos Pydantic

🚨 Solução de Problemas

"Variável de ambiente OPENAI_API_KEY não definida"

Defina sua chave da API OpenAI na configuração do Claude Desktop.

"Nenhum player de áudio disponível"

Usuários Linux: Instale um dos players de áudio suportados:

# Ubuntu/Debian
sudo apt-get install mpg123
# or
sudo apt-get install sox
# or
sudo apt-get install ffmpeg
# or
sudo apt-get install vlc

# Fedora/RHEL
sudo dnf install mpg123
# or similar for other players

# Arch
sudo pacman -S mpg123
# or similar for other players

Windows/macOS: A reprodução de áudio deve funcionar imediatamente.

O áudio não reproduz

Verifique o volume do sistema
Certifique-se de que não há outros problemas de áudio no seu sistema
Ative o logging de depuração com DEBUG=true
Verifique os logs para quaisquer erros

📝 Histórico de Alterações

v2.0.0 (Reescrita em Python)

🐍 Reescrita completa em Python para melhor suporte multiplataforma
🔧 Manipulação assíncrona aprimorada com asyncio do Python
📦 Instalação simplificada com pip
🛡️ Segurança de tipos aprimorada com Pydantic
🚀 Melhor desempenho e confiabilidade

v1.2.0 (Preferências Persistentes)

💾 Adicionado gerenciamento de estado persistente para preferências de voz e tom
🎯 Adicionada ferramenta set_voice para definir voz padrão
🎯 Adicionada ferramenta set_tone para definir instruções padrão de fala
🎆 Adicionado suporte para novas vozes da OpenAI: ash, ballad e sage
🔄 play_summary agora usa preferências salvas, a menos que sejam substituídas
📝 Estado salvo em ~/.summarize-mcp-state.json

v1.1.0 (Suporte Multiplataforma)

🌍 Adicionado suporte ao Windows usando PowerShell/Windows Media Player
🐧 Adicionado suporte ao Linux com detecção automática de players de áudio
🔄 Adicionado fallback para o player de áudio padrão do sistema
📝 Documentação atualizada para uso multiplataforma

v1.0.0 (Lançamento Inicial)

🎉 Lançamento inicial
✨ Funcionalidade TTS principal com integração OpenAI
✨ Suporte para 7 vozes diferentes
✨ Instruções personalizadas de fala
✨ Reprodução de áudio em segundo plano no macOS
✨ Limpeza automática de arquivos
✨ Implementação em TypeScript
✨ Tratamento abrangente de erros

💰 Custos Estimados

Esta ferramenta usa o modelo gpt-4o-mini-tts da OpenAI para conversão de texto-para-fala. Aqui está o detalhamento de preços:

Modelo	Preço de Saída de Áudio	Custo Estimado
`gpt-4o-mini-tts`	$12,00 por 1M de tokens	$0,015 por minuto de áudio

Exemplos de Custo:

Resumo de 100 palavras (~30 segundos): ~$0,0075
Resumo de 500 palavras (~2,5 minutos): ~$0,0375
Resumo de 1000 palavras (~5 minutos): ~$0,075

O custo real depende de:

Comprimento dos seus resumos
Velocidade de fala (as instruções podem afetar isso)
Frequência de uso da ferramenta

Para detalhes de preços atuais, consulte a página de preços da OpenAI.

🔮 Roadmap

Reprodução de áudio multiplataforma (Windows, Linux)
Implementação em Python para melhor suporte multiplataforma
Provedores TTS adicionais (ElevenLabs, Amazon Polly)
Opções de formato de áudio (WAV, OGG)
Controle de reprodução (pausar, retomar, parar)
Gerenciamento de fila para múltiplos resumos
Cache de arquivos de áudio
Controles de velocidade e tom
Suporte SSML para controle avançado de fala

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças significativas, abra uma issue primeiro para discutir o que você gostaria de alterar.

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

📄 Licença

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

🙏 Agradecimentos

Construído sobre a especificação Model Context Protocol da Anthropic
Desenvolvido com a API TTS da OpenAI
Agradecimentos especiais à comunidade MCP pela inspiração e suporte