MCP Server Whisper

MCP Server Whisper

[!WARNING] Este proyecto se ha trasladado. El desarrollo activo ha migrado a TJC-LP/sanzaru. Este repositorio ya no se mantiene y será archivado. Actualice sus dependencias y problemas al nuevo repositorio.

Descripción general

MCP Server Whisper proporciona una forma estandarizada de procesar archivos de audio a través de los servicios de transcripción y voz más recientes de OpenAI. Al implementar el Model Context Protocol, permite que asistentes de IA como Claude interactúen sin problemas con las capacidades de procesamiento de audio.

Características principales:

• 🔍 Búsqueda avanzada de archivos con patrones regex, filtrado de metadatos de archivos y capacidades de ordenación
• ⚡ Procesamiento paralelo nativo de MCP: llame a múltiples herramientas simultáneamente
• 🔄 Conversión de formato entre tipos de audio compatibles
• 📦 Compresión automática para archivos de gran tamaño
• 🎯 Transcripción multimodelo con soporte para todos los modelos de audio de OpenAI
• 🗣️ Chat de audio interactivo con modelos de audio GPT-4o
• ✏️ Transcripción mejorada con indicaciones especializadas y soporte de marcas de tiempo
• 🎙️ Generación de texto a voz con voces, instrucciones y velocidad personalizables
• 📊 Metadatos completos que incluyen duración, tamaño de archivo y soporte de formato
• 🚀 Caché de alto rendimiento para operaciones repetidas
• 🔒 Respuestas seguras de tipos con modelos Pydantic para todas las salidas de herramientas

Nota: Este proyecto no es oficial y no está afiliado, respaldado ni patrocinado por OpenAI. Proporciona una interfaz de Model Context Protocol para las API públicas de OpenAI.

Instalación

# 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

Configuración del entorno

Cree un archivo .env basado en el .env.example proporcionado:

cp .env.example .env

Edite .env con sus valores reales:

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

Nota: Las variables de entorno deben estar disponibles en tiempo de ejecución. Para el desarrollo local con Claude, use una herramienta como dotenv-cli para cargarlas (consulte la sección de Uso a continuación).

Uso

Desarrollo local con Claude

El proyecto incluye un archivo de configuración .mcp.json para el desarrollo local con Claude. Para usarlo:

1. Asegúrese de que su archivo .env esté configurado con las variables de entorno requeridas
2. Inicie Claude con las variables de entorno cargadas:

bunx dotenv-cli -- claude

Esto hará lo siguiente:

• Cargar las variables de entorno desde su archivo .env
• Iniciar Claude con el servidor MCP configurado según .mcp.json
• Habilitar la recarga en caliente durante el desarrollo

La configuración de .mcp.json:

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

Herramientas MCP expuestas

Gestión de archivos de audio

• list_audio_files - Lista archivos de audio con opciones completas de filtrado y ordenación:
  • Filtrar por coincidencia de patrones regex en nombres de archivo
  • Filtrar por tamaño de archivo, duración, hora de modificación o formato
  • Ordenar por nombre, tamaño, duración, hora de modificación o formato
  • Devuelve FilePathSupportParams seguro de tipos con metadatos completos
• get_latest_audio - Obtiene el archivo de audio modificado más recientemente con información de soporte del modelo

Procesamiento de audio

• convert_audio - Convierte archivos de audio a formatos compatibles (mp3 o wav)
  • Devuelve AudioProcessingResult con la ruta de salida
• compress_audio - Comprime archivos de audio que superan los límites de tamaño
  • Devuelve AudioProcessingResult con la ruta de salida

Transcripción

• transcribe_audio - Transcripción avanzada utilizando los modelos de OpenAI:

  • Compatible con whisper-1, gpt-4o-transcribe y gpt-4o-mini-transcribe
  • Indicaciones personalizadas para transcripción guiada
  • Granularidades de marca de tiempo opcionales para sincronización a nivel de palabra y segmento
  • Opción de formato de respuesta JSON
  • Devuelve TranscriptionResult con texto, datos de uso y marcas de tiempo opcionales

• chat_with_audio - Análisis de audio interactivo utilizando modelos de audio GPT-4o:

  • Compatible con gpt-4o-audio-preview (recomendado) y versiones con fecha
  • Nota: gpt-4o-mini-audio-preview tiene limitaciones con el chat de audio y no se recomienda
  • Indicaciones personalizadas de sistema y usuario
  • Proporciona respuestas conversacionales al contenido de audio
  • Devuelve ChatResult con el texto de respuesta

• transcribe_with_enhancement - Transcripción mejorada con plantillas especializadas:

  • detailed - Incluye tono, emoción y detalles de fondo
  • storytelling - Transforma la transcripción en forma narrativa
  • professional - Crea transcripciones formales y apropiadas para negocios
  • analytical - Añade análisis de patrones de habla y puntos clave
  • Devuelve TranscriptionResult con salida mejorada

Texto a voz

• create_audio - Genera audio de texto a voz utilizando la API TTS de OpenAI:
  • Compatible con gpt-4o-mini-tts (preferido) y otros modelos de voz
  • Múltiples opciones de voz (alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar)
  • Ajuste de velocidad e instrucciones personalizadas
  • Rutas de archivo de salida personalizables
  • Maneja textos de cualquier longitud dividiendo y uniendo automáticamente los segmentos de audio
  • Devuelve TTSResult con la ruta de salida

Formatos de audio compatibles

Nota: Los archivos de más de 25MB se comprimen automáticamente para cumplir con los límites de la API.

Ejemplo de uso con 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.

Configuración con Claude Desktop

Para uso en producción con Claude Desktop (a diferencia del desarrollo local), agregue esto a su 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"
      }
    }
  }
}

Recomendación (solo Mac OS)

• Instale Screen Recorder By Omi (gratis)
• Establezca AUDIO_FILES_PATH en /Users/<user>/Movies/Omi Screen Recorder y reemplace <user> con su nombre de usuario
• Mientras graba audio con la aplicación, puede transcribir múltiples archivos en paralelo con Claude

Desarrollo

Este proyecto utiliza herramientas modernas de desarrollo de Python, incluyendo uv, pytest, ruff y 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

Flujo de trabajo CI/CD

El proyecto utiliza GitHub Actions para CI/CD:

1. Lint y verificación de tipos: garantiza la calidad del código con ruff y verificación estricta de tipos con mypy
2. Pruebas: ejecuta pruebas en múltiples versiones de Python (3.10, 3.11, 3.12, 3.13, 3.14, 3.14t)
3. Lanzamiento y publicación: flujo de trabajo de doble activación para una gestión flexible de lanzamientos

Nota: Python 3.14t es la compilación de subprocesos libres (sin GIL) para probar el paralelismo real.

Creación de un nuevo lanzamiento

El flujo de trabajo de lanzamiento admite dos enfoques:

Opción 1: Lanzamiento automatizado (recomendado)

Empuje una etiqueta para crear automáticamente un lanzamiento y publicarlo en 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

Esto hará lo siguiente:

• Verificará que la versión de la etiqueta coincida con pyproject.toml
• Compilará el paquete
• Creará un lanzamiento de GitHub con notas generadas automáticamente
• Publicará automáticamente en PyPI

Opción 2: Lanzamiento manual

Cree un lanzamiento manualmente a través de la interfaz de GitHub y luego publique opcionalmente:

1. Vaya a Releases en GitHub
2. Haga clic en "Draft a new release"
3. Cree una nueva etiqueta o seleccione una existente
4. Complete los detalles del lanzamiento
5. Haga clic en "Publish release"

Cuando publique el lanzamiento, el flujo de trabajo publicará automáticamente en PyPI. También puede crear un lanzamiento borrador para retrasar la publicación.

Filosofía de diseño de API

MCP Server Whisper sigue un diseño de API plano y seguro de tipos optimizado para clientes MCP:

• Argumentos planos: todas las herramientas aceptan parámetros planos en lugar de objetos anidados para llamadas más simples e intuitivas
• Respuestas seguras de tipos: cada herramienta devuelve un modelo Pydantic fuertemente tipado (TranscriptionResult, ChatResult, AudioProcessingResult, TTSResult)
• Operaciones de un solo elemento: una llamada procesa un archivo, con el protocolo MCP manejando el paralelismo de forma nativa
• Manejo de errores por archivo: los fallos se aíslan a operaciones individuales, no a lotes completos
• Autodocumentado: las sugerencias de tipo proporcionan autocompletado y validación en IDE y modelos de IA

Este diseño facilita significativamente que los asistentes de IA usen las herramientas correctamente y manejen los resultados de manera confiable.

Cómo funciona

Para obtener información detallada sobre la arquitectura, consulte Architecture Documentation.

MCP Server Whisper está construido sobre el Model Context Protocol, que estandariza cómo los modelos de IA interactúan con herramientas externas y fuentes de datos. El servidor:

1. Expone capacidades de procesamiento de audio: a través de interfaces de herramientas MCP estandarizadas con API planas y seguras de tipos
2. Implementa procesamiento paralelo: usando concurrencia estructurada de anyio; los clientes MCP manejan el paralelismo de forma nativa
3. Gestiona operaciones de archivos: maneja detección, validación, conversión y compresión
4. Proporciona transcripción enriquecida: a través de diferentes modelos de OpenAI y plantillas de mejora
5. Optimiza el rendimiento: con mecanismos de caché para operaciones repetidas
6. Garantiza la seguridad de tipos: todas las respuestas usan modelos Pydantic para validación y soporte de IDE

Internamente, utiliza:

• pydub para manipulación de archivos de audio (con audioop-lts para Python 3.13+)
• anyio para concurrencia estructurada y gestión de grupos de tareas
• aioresult para recopilar resultados de grupos de tareas paralelas
• Los modelos de transcripción más recientes de OpenAI (incluyendo gpt-4o-transcribe)
• Los modelos de audio GPT-4o de OpenAI para una comprensión mejorada
• gpt-4o-mini-tts de OpenAI para síntesis de voz de alta calidad
• FastMCP para una implementación simplificada del servidor MCP
• Sugerencias de tipo y validación estricta de mypy en todo el código

Contribuciones

¡Las contribuciones son bienvenidas! Siga estos pasos:

1. Haga un fork del repositorio
2. Cree una nueva rama para su función (git checkout -b feature/amazing-feature)
3. Realice sus cambios
4. Ejecute las pruebas y el linting (uv run pytest && uv run ruff check src && uv run mypy --strict src)
5. Haga commit de sus cambios (git commit -m 'Add some amazing feature')
6. Empuje a la rama (git push origin feature/amazing-feature)
7. Abra un Pull Request

Licencia

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

Agradecimientos

• Protocolo de Contexto de Modelo (MCP) - Para la especificación del protocolo
• pydub - Para procesamiento de audio
• OpenAI Whisper - Para transcripción de audio
• FastMCP - Para implementación de servidor MCP
• Anthropic Claude - Para interacción en lenguaje natural
• MCP Review - Este servidor MCP está certificado por MCP Review