Transcripción de Audio

CLI o API | MCP | Agente

Versión: 2.1.0

Documentación — La instalación, el despliegue y el uso a través de la CLI, la API de Python, el servidor MCP y el agente A2A se mantienen en la documentación oficial.

Related MCP server: audio-transcription-mcp

Resumen

Audio Transcriber es un agente de nivel de producción y un servidor de Protocolo de Contexto de Modelo (MCP) diseñado para interactuar directamente con Transcribe tus archivos .wav .mp4 .mp3 .flac a texto o graba tu propio audio!.

Características principales

• Herramientas MCP consolidadas con enrutamiento por acciones: Minimiza la sobrecarga de tokens y elimina la inflación de herramientas en los contextos de LLM al agrupar métodos en módulos de herramientas optimizados y conmutables.

• Seguridad de nivel empresarial: Soporte integral para políticas de Eunomia, delegación de tokens OIDC y seguimiento granular del contexto de ejecución.

• Agente gráfico integrado: Agente Pydantic AI integrado que admite el Protocolo de Control de Agentes (ACP) e interfaces web estándar (AG-UI).

• Telemetría y trazabilidad nativas: Exportaciones de OpenTelemetry listas para usar y trazabilidad nativa de Langfuse.

CLI o API

Este agente envuelve la API de Transcribe tus archivos .wav .mp4 .mp3 .flac a texto o graba tu propio audio!. Puedes interactuar con él programáticamente o a través de sus puntos de entrada de ejecución integrados.

Las instrucciones detalladas sobre cómo usar los envoltorios de API subyacentes, los enlaces de esquema extendidos y las referencias del SDK para desarrolladores se mantienen en docs/index.md.

MCP

Este servidor utiliza herramientas dinámicas con enrutamiento por acciones para optimizar la sobrecarga de tokens y maximizar la compatibilidad con IDE.

Herramientas MCP disponibles

La siguiente tabla se genera automáticamente desde el servidor en vivo — no la edites manualmente.

Herramientas condensadas con enrutamiento por acciones (MCP_TOOL_MODE=condensed)

Herramientas detalladas 1:1 mapeadas a la API (MCP_TOOL_MODE=verbose o both)

4 herramienta(s) con enrutamiento por acciones · 7 herramienta(s) detalladas 1:1. Cada una está habilitada a menos que su conmutador <DOMINIO>TOOL se establezca en falso; MCP_TOOL_MODE selecciona la superficie (**intent predeterminado* — las seis herramientas de verbo, conjunto granular cargado bajo demanda · condensed con enrutamiento por acciones · verbose 1:1 · both). Generado automáticamente — no editar.*

Los esquemas detallados de las herramientas, las formas de los parámetros y las restricciones de validación se conservan en docs/usage.md.

Selección dinámica de herramientas y visibilidad

Este servidor MCP admite la selección dinámica de conjuntos de herramientas y el filtrado de visibilidad en tiempo de ejecución. Esto te permite restringir el conjunto de herramientas expuestas para evitar que se expanda la ventana de contexto del LLM.

Puedes configurar el filtrado de herramientas a través de múltiples canales de entrada:

• Argumentos de CLI: Pasa --tools o --toolsets (o sus contrapartes deshabilitadas --disabled-tools y --disabled-toolsets) durante el inicio.

• Variables de entorno: Define variables de entorno estándar:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• Encabezados de solicitud HTTP SSE: Pasa encabezados personalizados durante la inicialización del transporte:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• Parámetros de consulta de solicitud HTTP SSE: Añade parámetros de consulta directamente a la URL de conexión de tu transporte:

  • ?tools=tool1,tool2

  • ?tags=tag1

Cuando se proporcionan cadenas de consulta o parámetros, una capa de resolución de Grafo de Conocimiento sin LLM (usando DynamicToolOrchestrator) hace coincidir las intenciones de consulta con las etiquetas, nombres o descripciones de herramientas conocidas, con un respaldo seguro y un refresco automático de caché en segundo plano cada 24 horas.

Ejemplos de configuración de MCP

Instala el extra [mcp] centrado en el conector. Los ejemplos usan audio-transcriber[mcp] para añadir FastMCP / FastAPI a través de agent-utilities[mcp]; el núcleo requerido de Agent Utilities sigue incluyendo epistemic-graph[full]. El extra [agent-runtime] además habilita la orquestación de modelos.

Transporte stdio (IDEs locales — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "audio-transcriber-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "audio-transcriber[mcp]",
        "audio-transcriber-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "AUDIO_PROCESSINGTOOL": "True",
        "MEDIA_SIDECARTOOL": "True",
        "MISCTOOL": "True",
        "TRANSCRIBE_DIRECTORY": "/path/to/transcribe_directory",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

Las referencias de tiempo de ejecución requieren un lanzador consciente de alias como GraphOS. Otros lanzadores deben omitir esas entradas e inyectar los valores resueltos a través de su propio límite de secretos de tiempo de ejecución.

Transporte Streamable-HTTP (en red / producción)

{
  "mcpServers": {
    "audio-transcriber-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "audio-transcriber[mcp]",
        "audio-transcriber-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "AUDIO_PROCESSINGTOOL": "True",
        "MEDIA_SIDECARTOOL": "True",
        "MISCTOOL": "True",
        "TRANSCRIBE_DIRECTORY": "/path/to/transcribe_directory",
        "WHISPER_MODEL": "base"
      }
    }
  }
}

Alternativamente, conéctate a una instancia Streamable-HTTP previamente desplegada mediante url:

{
  "mcpServers": {
    "audio-transcriber-mcp": {
      "url": "http://localhost:8000/audio-transcriber-mcp/mcp"
    }
  }
}

Ejecuta una imagen de contenedor revisada como un hijo stdio con privilegios mínimos (sin listener ni puerto publicado):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e AUDIO_PROCESSINGTOOL=True \
  -e MEDIA_SIDECARTOOL=True \
  -e MISCTOOL=True \
  -e TRANSCRIBE_DIRECTORY=/path/to/transcribe_directory \
  -e WHISPER_MODEL=base \
  registry.example.invalid/audio-transcriber@sha256:<digest> audio-transcriber-mcp

Para HTTP de red en contenedores, proporciona una entrada TLS autenticada (o TLS directo del servidor), MCP_ALLOWED_HOSTS exactos y una política CIDR de proxy de confianza exacta a través del perfil de despliegue propiedad del operador. El generador no emite un listener no autenticado fuera de loopback.

Generado automáticamente desde la superficie de entorno leída del código (MCP_TOOL_MODE + variables del paquete) — no editar.

Opciones de despliegue adicionales

audio-transcriber puede ejecutarse como un proceso stdio local o contenedor, o detrás de un límite de red remoto. La Guía de despliegue contiene el contrato de transporte detallado.

• Contenedor local — lanza una imagen inmutable revisada como un hijo stdio con privilegios mínimos, sin listener ni puerto publicado.

• URL remota — conéctate a través de una entrada HTTPS autenticada proporcionada por el operador. Mantén su URL, referencias de identidad saliente, perfil de confianza y MCP_ALLOWED_HOSTS exactos en AgentConfig.

Agente

Este repositorio incluye un Agente Gráfico Pydantic AI totalmente integrado. Se comunica a través del Protocolo de Control de Agentes (ACP) e interactúa sin problemas con la Interfaz Web de Agente (AG-UI) y la interfaz de Terminal.

Ejecutar la CLI del agente

Para iniciar el agente interactivo de línea de comandos:

# Configure transcription (optional)
export WHISPER_MODEL="base"
export TRANSCRIBE_DIRECTORY="/path/to/transcribe_directory"

# Run the agent server
audio-transcriber-agent --provider openai --model-id gpt-4o

Orquestación con Docker Compose

El siguiente docker/agent.compose.yml configura el Agente, la Interfaz Web y la Interfaz de Terminal juntos:

version: '3.8'

services:
  audio-transcriber-mcp:
    image: example/audio-transcriber:mcp
    container_name: audio-transcriber-mcp
    hostname: audio-transcriber-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  audio-transcriber-agent:
    image: example/audio-transcriber@sha256:<digest>
    container_name: audio-transcriber-agent
    hostname: audio-transcriber-agent
    restart: always
    depends_on:
      - audio-transcriber-mcp
    env_file:
      - ../.env
    command: [ "audio-transcriber-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9014
      - MCP_URL=http://audio-transcriber-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9014:9014"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9014/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Las explicaciones detalladas de la arquitectura de nodos del grafo, las configuraciones de habilidades personalizadas y las guías de trazabilidad de agentes están disponibles en docs/deployment.md.

Seguridad y gobernanza

Construido directamente sobre el núcleo agent-utilities listo para empresas, los parámetros de seguridad estándar son totalmente compatibles:

Control de acceso y aplicación de políticas

• Políticas de Eunomia: Autorización de herramientas basada en políticas y de grano fino. Admite modos none, embedded local (mcp_policies.json) o remote centralizado.

• Delegación de tokens OIDC: Cumple con el intercambio de tokens RFC 8693 para transferir las credenciales de usuario autenticadas desde la Interfaz Web / ACP → Agente → MCP.

• Credenciales con ámbito: El contexto de ejecución se restringe a la identidad específica del llamador.

Cuadrícula de seguridad en tiempo de ejecución

Variables de entorno

Variables de entorno del paquete

Variables heredadas de agent-utilities (aplican a todos los conectores)

16 variables de paquete + 16 heredadas. Generado automáticamente desde .env.example + el conjunto compartido de agent-utilities — no editar.

Cada variable que lee el servidor, agrupada por propósito.

Transcripción

Servidor MCP / transporte

Conmutadores de herramientas

Cada herramienta enrutada por acción se puede deshabilitar individualmente mediante su variable de entorno de conmutación (establecer en false). Consulta la tabla Available MCP Tools anterior para conocer los nombres autorizados.

Telemetría y gobernanza

CLI del agente (solo runtime completo [agent])

Consulta .env.example para un punto de partida de copiar y pegar.

Instalación

Elige el extra que coincida con lo que quieres ejecutar:

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "audio-transcriber[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "audio-transcriber[agent]"

# Everything (development)
uv pip install "audio-transcriber[all]"      # or: python -m pip install "audio-transcriber[all]"

Imágenes de contenedor (:mcp vs :agent)

Un docker/Dockerfile de varias etapas construye dos imágenes de tamaño adecuado, seleccionadas por --target:

docker build --target mcp   -t example/audio-transcriber:mcp    docker/   # connector-focused MCP server
docker build --target agent -t example/audio-transcriber:agent-local docker/   # agent runtime

docker/mcp.compose.yml ejecuta el servidor :mcp centrado en el conector; docker/agent.compose.yml ejecuta el agente (immutable agent digest) con un sidecar :mcp co-ubicado.

Base de datos del grafo de conocimiento (epistemic-graph)

Tanto [mcp] como [agent] incluyen el motor epistemic-graph mediante la dependencia principal requerida de Agent Utilities (epistemic-graph[full]). El extra [mcp] mantiene el servidor centrado en el conector; [agent] habilita además la orquestación de modelos. Los despliegues locales pueden usar el motor incluido. Para producción o estado compartido, ejecuta epistemic-graph como un servicio de base de datos dedicado y configura el runtime para usarlo. Las recetas de despliegue (single-node + Raft HA), la configuración de conexión y los diagramas de arquitectura están documentados en la guía de despliegue de epistemic-graph.

Propietarios del repositorio

Documentación

La documentación completa está publicada como el sitio oficial de documentación y es la referencia recomendada para instalación, despliegue y operación diaria.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, asegura la calidad del código ejecutando comprobaciones locales antes de enviar pull requests:

• Formatea el código con ruff format .

• Ejecuta el linter con ruff check .

• Valida la seguridad de tipos con mypy .

• Ejecuta las suites de pruebas con pytest

Despliegue con agent-utilities-deployment

Aprovisiona este paquete con el flujo de trabajo consolidado agent-utilities-deployment. Selecciona una ruta de paquete instalado, fuente editable o contenedor inmutable; registra solo referencias de secretos de runtime y de perfiles TLS en AgentConfig; y ejecuta gates de doctor, registro, políticas, observabilidad y rollback. Pídele a tu agente que "despliegue audio-transcriber con agent-utilities-deployment".

El repositorio no incorpora ningún perfil de despliegue, valor de credencial, ruta de certificado ni endpoint específico del entorno. Proporciónalos en tiempo de ejecución a través de AgentConfig y del proveedor de secretos configurado.

Contrato de capacidad gobernada

Este paquete incluye una superficie de habilidades canónica y compacta, con procedimientos especializados mantenidos como flujos de trabajo referenciados. Las herramientas MCP actuales, los metadatos de habilidades, connector_manifest.yml, la ontología, los mapeos, las shapes, los fixtures, las migraciones, las huellas de tool-schema y los metadatos de certificación forman un contrato de capacidad versionado. Valídelos en conjunto; no confíe en nombres de herramientas obsoletos ni en envoltorios históricos de habilidades por tarea.

Los endpoints de runtime, las credenciales, la confianza de certificados, la identidad del tenant, la retención y la política de observabilidad son entradas de despliegue y nunca valores empaquetados. Consulta Configuración, confianza y privacidad antes de habilitar un transporte de red, la ingesta de conectores, la delegación de GraphOS o la exportación de trazas.