Summarize MCP

Convierte resúmenes de texto a voz usando la API de Text-to-Speech de OpenAI y los reproduce en segundo plano.

Documentación

summarize-mcp

🤖 Co-creado con Claude Code - ¡Haciendo audibles los resúmenes de IA desde 2025! 🔊

Un servidor de Model Context Protocol (MCP) que convierte resúmenes de texto en voz utilizando la API TTS de OpenAI y los reproduce en segundo plano en todas las principales plataformas (macOS, Windows, Linux).

🌟 Descripción general

summarize-mcp permite a los LLM convertir cualquier resumen de texto en voz de sonido natural utilizando los modelos de texto a voz de última generación de OpenAI. Perfecto para crear resúmenes de audio de documentos, artículos o cualquier contenido que se beneficie de una presentación auditiva.

🚀 Características principales

🎯 Simple y enfocado: Una herramienta que hace una cosa excepcionalmente bien
🎤 Múltiples voces: Elige entre 10 voces distintas de OpenAI (alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer)
🎨 Instrucciones personalizadas: Controla cómo debe hablarse el texto
🔧 Reproducción en segundo plano: El audio se reproduce en segundo plano sin bloquear
🌍 Multiplataforma: Funciona en macOS, Windows y Linux
💾 Preferencias persistentes: Guarda tu voz y tono favoritos
🎯 Múltiples herramientas: Configurar voz, configurar tono y reproducir resúmenes
🧹 Limpieza automática: Los archivos temporales se limpian automáticamente
🛡️ Seguridad de tipos: Sugerencias de tipo completas de Python con validación de Pydantic
📊 Registro completo: Modo de depuración para solucionar problemas
⚡ Rendimiento optimizado: Manejo y limpieza eficiente de archivos

📋 Requisitos previos

Python 3.8 o superior
Clave de API de OpenAI con acceso a los modelos TTS
Reproductor de audio (detectado automáticamente):
- macOS: afplay integrado (no se necesita instalación)
- Windows: Windows Media Player integrado (no se necesita instalación)
- Linux: Uno de: mpg123, sox (play), ffmpeg (ffplay), vlc (cvlc) o alsa-utils (aplay)

📦 Instalación

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

🏃 Configuración

Claude Desktop

Añade esta configuración a tu archivo de configuración de 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

Configuración:

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

Variables de entorno

OPENAI_API_KEY (obligatorio): Tu clave de API de OpenAI
DEBUG (opcional): Establécelo en "true" para un registro detallado

🛠️ Herramientas disponibles

play_summary

Convierte texto a voz y lo reproduce en segundo plano. Utiliza las preferencias guardadas de voz y tono a menos que se anulen.

Parámetros:

summary (obligatorio): El texto a convertir en voz
voice (opcional): Voz a utilizar - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage o shimmer (utiliza la preferencia guardada si no se especifica)
instructions (opcional): Instrucciones sobre cómo debe hablarse el texto (utiliza el tono guardado si no se especifica)

Ejemplo:

{
  "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

Establece la voz predeterminada para todas las conversiones de texto a voz futuras.

Parámetros:

voice (obligatorio): La voz a utilizar - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage o shimmer

Ejemplo:

{
  "voice": "nova"
}

set_tone

Establece el tono/instrucciones predeterminados sobre cómo debe hablarse el texto en todas las solicitudes TTS futuras.

Parámetros:

tone (obligatorio): El tono/instrucciones a utilizar (p. ej., "Habla lenta y calmadamente", "Sé entusiasta y enérgico")

Ejemplo:

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

📖 Ejemplos de uso

Resumen básico

"Please summarize this article and play it as audio"

El LLM:

Generará un resumen del contenido
Utilizará la herramienta play_summary para convertirlo en voz
El audio se reproducirá en segundo plano con las preferencias guardadas

Establecer voz predeterminada

"Set the default voice to nova"

Esto guardará "nova" como tu voz preferida para todos los resúmenes futuros.

Establecer tono predeterminado

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

Esto guardará tu preferencia de tono para todos los resúmenes futuros.

Voz personalizada (una sola vez)

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

Esto utilizará "sage" solo para este resumen, sin cambiar tu valor predeterminado.

Con instrucciones personalizadas (una sola vez)

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

Esto utilizará instrucciones personalizadas solo para este resumen.

🎯 Opciones de voz

Voz	Descripción
`alloy`	Neutral y equilibrada
`ash`	Cálida y cautivadora
`ballad`	Expresiva y dramática
`coral`	Clara y profesional (predeterminada)
`echo`	Suave y reflexiva
`fable`	Expresiva y animada
`nova`	Amigable y optimista
`onyx`	Profunda y autoritaria
`sage`	Sabia y mesurada
`shimmer`	Suave y delicada

🧪 Desarrollo

# 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

🏗️ Arquitectura

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

🔧 Detalles técnicos

Formato de audio: MP3 (formato de salida de OpenAI TTS)
Archivos temporales: Almacenados en el directorio temporal del sistema
Limpieza de archivos: Limpieza automática después de 10 segundos (configurable)
Purga de archivos antiguos: Los archivos con más de 1 hora se limpian al iniciar
Soporte de plataformas:
- macOS: Utiliza afplay integrado
- Windows: Utiliza PowerShell con Windows Media Player
- Linux: Detecta automáticamente el reproductor disponible (mpg123, sox, ffmpeg, vlc, alsa)
- Respaldo: Se abre con la aplicación de audio predeterminada del sistema
Gestión de estado:
- Preferencias guardadas en ~/.summarize-mcp-state.json
- Conserva la configuración de voz y tono entre sesiones
- Carga automática al iniciar
Manejo de errores: Manejo integral de errores con tipos de error específicos
Validación: Validación de entrada mediante modelos de Pydantic

🚨 Solución de problemas

"La variable de entorno OPENAI_API_KEY no está configurada"

Configura tu clave de API de OpenAI en la configuración de Claude Desktop.

"No hay reproductor de audio disponible"

Usuarios de Linux: Instala uno de los reproductores de audio compatibles:

# 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: La reproducción de audio debería funcionar sin configuración adicional.

El audio no se reproduce

Comprueba el volumen del sistema
Asegúrate de que no haya otros problemas de audio en tu sistema
Habilita el registro de depuración con DEBUG=true
Revisa los registros para ver si hay errores

📝 Registro de cambios

v2.0.0 (Reescritura en Python)

🐍 Reescritura completa en Python para un mejor soporte multiplataforma
🔧 Manejo asíncrono mejorado con asyncio de Python
📦 Instalación simplificada con pip
🛡️ Seguridad de tipos mejorada con Pydantic
🚀 Mejor rendimiento y fiabilidad

v1.2.0 (Preferencias persistentes)

💾 Se añadió gestión de estado persistente para las preferencias de voz y tono
🎯 Se añadió la herramienta set_voice para establecer la voz predeterminada
🎯 Se añadió la herramienta set_tone para establecer las instrucciones de habla predeterminadas
🎆 Se añadió soporte para nuevas voces de OpenAI: ash, ballad y sage
🔄 play_summary ahora utiliza las preferencias guardadas a menos que se anulen
📝 Estado guardado en ~/.summarize-mcp-state.json

v1.1.0 (Soporte multiplataforma)

🌍 Se añadió soporte para Windows mediante PowerShell/Windows Media Player
🐧 Se añadió soporte para Linux con detección automática de reproductores de audio
🔄 Se añadió respaldo al reproductor de audio predeterminado del sistema
📝 Se actualizó la documentación para uso multiplataforma

v1.0.0 (Lanzamiento inicial)

🎉 Lanzamiento inicial
✨ Funcionalidad TTS principal con integración de OpenAI
✨ Soporte para 7 voces diferentes
✨ Instrucciones de habla personalizadas
✨ Reproducción de audio en segundo plano en macOS
✨ Limpieza automática de archivos
✨ Implementación en TypeScript
✨ Manejo integral de errores

💰 Costos estimados

Esta herramienta utiliza el modelo gpt-4o-mini-tts de OpenAI para la conversión de texto a voz. Aquí está el desglose de precios:

Modelo	Precio de salida de audio	Costo estimado
`gpt-4o-mini-tts`	$12.00 por 1M de tokens	$0.015 por minuto de audio

Ejemplos de costos:

Resumen de 100 palabras (~30 segundos): ~$0.0075
Resumen de 500 palabras (~2.5 minutos): ~$0.0375
Resumen de 1000 palabras (~5 minutos): ~$0.075

El costo real depende de:

La longitud de tus resúmenes
La velocidad de habla (las instrucciones pueden afectar esto)
La frecuencia con la que utilizas la herramienta

Para obtener detalles de precios actuales, consulta la página de precios de OpenAI.

🔮 Hoja de ruta

Reproducción de audio multiplataforma (Windows, Linux)
Implementación en Python para un mejor soporte multiplataforma
Proveedores TTS adicionales (ElevenLabs, Amazon Polly)
Opciones de formato de audio (WAV, OGG)
Control de reproducción (pausa, reanudar, detener)
Gestión de cola para múltiples resúmenes
Caché de archivos de audio
Controles de velocidad y tono
Soporte SSML para control avanzado del habla

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Pull Request. Para cambios importantes, abre primero un issue para discutir lo que te gustaría cambiar.

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Haz commit de tus cambios (git commit -m 'Add some amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre una Pull Request

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

Construido sobre la especificación Model Context Protocol de Anthropic
Impulsado por la API TTS de OpenAI
Agradecimiento especial a la comunidad MCP por la inspiración y el apoyo