Audio Transcriber

CLI или API | MCP | Агент

Версия: 2.1.0

Документация — Инструкции по установке, развёртыванию и использованию через CLI, Python API, MCP-сервер и A2A-агента поддерживаются в официальной документации.

Related MCP server: audio-transcription-mcp

Обзор

Audio Transcriber — это производственный агент и сервер Model Context Protocol (MCP), предназначенный для прямого взаимодействия с сервисом транскрибации ваших .wav .mp4 .mp3 .flac файлов в текст или записи собственного аудио.

Ключевые особенности

• Консолидированные инструменты MCP с маршрутизацией по действиям: минимизируют накладные расходы на токены и устраняют раздувание инструментов в контекстах LLM, группируя методы в оптимизированные переключаемые модули инструментов.

• Безопасность корпоративного уровня: всесторонняя поддержка политик Eunomia, делегирования токенов OIDC и детального отслеживания контекста выполнения.

• Встроенный графовый агент: встроенный агент Pydantic AI, поддерживающий Agent Control Protocol (ACP) и стандартные веб-интерфейсы (AG-UI).

• Встроенная телеметрия и трассировка: готовые экспортёры OpenTelemetry и нативная трассировка Langfuse.

CLI или API

Этот агент оборачивает API «Транскрибируйте ваши .wav .mp4 .mp3 .flac файлы в текст или записывайте собственное аудио!». Вы можете взаимодействовать с ним программно или через встроенные точки входа для выполнения.

Подробные инструкции по использованию базовых обёрток API, расширенных привязок схем и справочников SDK для разработчиков поддерживаются в docs/index.md.

MCP

Этот сервер использует динамические инструменты action-routed для оптимизации накладных расходов на токены и максимальной совместимости с IDE.

Доступные инструменты MCP

Таблица ниже автоматически генерируется из работающего сервера — не редактируйте вручную.

Сокращённые инструменты с маршрутизацией по действиям (MCP_TOOL_MODE=condensed)

Подробные инструменты с прямым сопоставлением 1:1 с API (MCP_TOOL_MODE=verbose или both)

4 инструмента с маршрутизацией по действиям · 7 подробных инструментов 1:1. Каждый включён, если только его переключатель <DOMAIN>TOOL не установлен в false; MCP_TOOL_MODE выбирает поверхность (**intent по умолчанию* — шесть глагольных инструментов, детальный набор загружается по требованию · condensed с маршрутизацией по действиям · verbose 1:1 · both). Автоматически сгенерировано — не редактировать.*

Подробные схемы инструментов, формы параметров и ограничения валидации сохраняются в docs/usage.md.

Динамический выбор инструментов и видимость

Этот MCP-сервер поддерживает динамический выбор набора инструментов и фильтрацию видимости во время выполнения. Это позволяет ограничить набор открытых инструментов, чтобы не раздувать контекстное окно LLM.

Вы можете настроить фильтрацию инструментов через несколько каналов ввода:

• Аргументы CLI: передавайте --tools или --toolsets (или их отключённые аналоги --disabled-tools и --disabled-toolsets) при запуске.

• Переменные окружения: определите стандартные переменные окружения:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• Заголовки HTTP SSE-запросов: передавайте пользовательские заголовки при инициализации транспорта:

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

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

• Query-параметры HTTP SSE-запросов: добавляйте query-параметры непосредственно к URL вашего транспортного соединения:

  • ?tools=tool1,tool2

  • ?tags=tag1

Когда указаны query-строки или параметры, не использующий LLM уровень разрешения графа знаний (на основе DynamicToolOrchestrator) сопоставляет намерения запросов с известными тегами, именами или описаниями инструментов, с безопасным возвратом к запасному варианту и автоматическим фоновым обновлением кэша каждые 24 часа.

Примеры конфигурации MCP

Установите дополнительный пакет [mcp], ориентированный на подключение. В примерах используется audio-transcriber[mcp] для добавления FastMCP / FastAPI через agent-utilities[mcp]; требуемое ядро Agent Utilities по-прежнему включает epistemic-graph[full]. Дополнительный пакет [agent-runtime] дополнительно включает оркестрацию моделей.

Транспорт stdio (локальные IDE — 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"
      }
    }
  }
}

Ссылки времени выполнения требуют лаунчера с поддержкой алиасов, такого как GraphOS. Другие лаунчеры должны опускать эти записи и внедрять разрешённые значения через собственную границу секретов времени выполнения.

Транспорт Streamable-HTTP (сетевой / продакшен)

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

В качестве альтернативы подключитесь к предварительно развёрнутому экземпляру Streamable-HTTP по url:

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

Запустите проверенный образ контейнера как дочерний процесс stdio с минимальными привилегиями (без слушателя или опубликованного порта):

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

Для контейнеризованного сетевого HTTP укажите аутентифицированный TLS-вход (или прямой серверный TLS), точный MCP_ALLOWED_HOSTS и точную политику CIDR для доверенного прокси через профиль развёртывания, принадлежащий оператору. Генератор не создаёт неаутентифицированный non-loopback слушатель.

Автоматически сгенерировано из env-поверхности, считываемой из кода (MCP_TOOL_MODE + переменные пакета) — не редактировать.

Дополнительные параметры развёртывания

audio-transcriber может работать как локальный stdio-процесс или контейнер, либо за удалённой сетевой границей. Руководство по развёртыванию содержит подробный транспортный контракт.

• Локальный контейнер — запускайте проверенный неизменяемый образ как дочерний процесс stdio с минимальными привилегиями, без слушателя или опубликованного порта.

• Удалённый URL — подключайтесь через аутентифицированный HTTPS-вход, предоставленный оператором. Храните его URL, ссылки на исходящие учётные данные, профиль доверия и точный MCP_ALLOWED_HOSTS в AgentConfig.

Агент

В этом репозитории представлен полностью интегрированный графовый агент Pydantic AI. Он общается через Agent Control Protocol (ACP) и бесшовно взаимодействует с Agent Web UI (AG-UI) и терминальным интерфейсом.

Запуск CLI агента

Чтобы запустить интерактивного агента с интерфейсом командной строки:

# 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

Оркестрация с помощью Docker Compose

Следующий файл docker/agent.compose.yml настраивает агента, веб-интерфейс и терминальный интерфейс вместе:

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"

Подробные объяснения архитектуры графовых узлов, конфигурации пользовательских навыков и руководства по агентной трассировке доступны в docs/deployment.md.

Безопасность и управление

Основанная непосредственно на готовом к корпоративному использованию ядре agent-utilities, система полностью поддерживает стандартные параметры безопасности:

Контроль доступа и применение политик

• Политики Eunomia: детальная авторизация инструментов на основе политик. Поддерживает режимы none, локальный embedded (mcp_policies.json) или централизованный remote.

• Делегирование токенов OIDC: соответствует обмену токенами RFC 8693 для передачи аутентифицирующих учётных данных пользователя от Web UI / ACP → агент → MCP.

• Ограниченные учётные данные: контекст выполнения ограничен конкретной личностью вызывающего.

Таблица безопасности времени выполнения

Переменные окружения

Переменные окружения пакета

Унаследованные переменные agent-utilities (применяются к каждому коннектору)

16 переменных пакета + 16 унаследованных переменных. Автоматически сгенерировано из .env.example и общего набора agent-utilities — не редактируйте.

Все переменные, которые читает сервер, сгруппированы по назначению.

Транскрипция

MCP-сервер / транспорт

Переключатели инструментов

Каждый инструмент с маршрутизацией по действиям можно отключить отдельно с помощью своей переменной-переключателя (установите значение false). Официальные названия приведены в таблице Available MCP Tools выше.

Телеметрия и управление

CLI агента (только полный рантайм [agent])

Готовую стартовую конфигурацию можно скопировать из .env.example.

Установка

Выберите вариант, который соответствует тому, что вы хотите запустить:

# 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]"

Образы контейнеров (:mcp vs :agent)

Один многоступенчатый docker/Dockerfile собирает два образа нужного размера, выбираемые с помощью --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 запускает ориентированный на коннектор сервер :mcp; docker/agent.compose.yml запускает агента (immutable agent digest) с совместно размещённым сайдкаром :mcp.

База данных графа знаний (epistemic-graph)

И [mcp], и [agent] включают движок epistemic-graph через обязательную основную зависимость Agent Utilities (epistemic-graph[full]). Дополнительный вариант [mcp] сохраняет сервер ориентированным на коннектор; [agent] дополнительно включает оркестрацию моделей. Локальные развёртывания могут использовать встроенный движок. Для продакшена или общего состояния запускайте epistemic-graph как выделенный сервис базы данных и настройте среду выполнения на его использование. Рецепты развёртывания (одиночный узел + Raft HA), настройка подключения и диаграммы архитектуры описаны в руководстве по развёртыванию epistemic-graph.

Владельцы репозитория

Документация

Полная документация опубликована на официальном сайте документации и является рекомендуемым справочником по установке, развёртыванию и повседневной эксплуатации.

Вклад в проект

Вклад приветствуется! Пожалуйста, обеспечьте качество кода, выполнив локальные проверки перед отправкой pull requests:

• Форматируйте код с помощью ruff format .

• Проверяйте код линтером с помощью ruff check .

• Проверяйте типобезопасность с помощью mypy .

• Выполняйте тестовые наборы с помощью pytest

Развёртывание с помощью agent-utilities-deployment

Разверните этот пакет с помощью консолидированного рабочего процесса agent-utilities-deployment. Он выбирает путь установленного пакета, редактируемого исходного кода или неизменяемого контейнера; записывает в AgentConfig только ссылки на секреты времени выполнения и TLS-профили; и запускает контрольные проверки doctor, регистрации, политики, наблюдаемости и отката. Попросите вашего агента "развернуть audio-transcriber с помощью agent-utilities-deployment".

Репозиторий не содержит встроенного профиля развёртывания, значений учётных данных, путей к сертификатам или конечных точек, зависящих от окружения. Укажите их во время выполнения через AgentConfig и настроенный провайдер секретов.

Контракт управляемых возможностей

Этот пакет включает компактную каноническую поверхность навыков, а специализированные процедуры хранятся как ссылочные рабочие процессы. Текущие MCP-инструменты, метаданные навыков, connector_manifest.yml, онтология, сопоставления, shapes, фикстуры, миграции, отпечатки схем инструментов и метаданные сертификации образуют единый версионируемый контракт возможностей. Проверяйте их вместе; не полагайтесь на устаревшие названия инструментов или исторические обёртки навыков для отдельных задач.

Конечные точки времени выполнения, учётные данные, доверие к сертификатам, идентичность тенанта, политика хранения данных и наблюдаемости являются входными данными развёртывания и никогда не упаковываются как значения. См. Конфигурация, доверие и конфиденциальность перед включением сетевого транспорта, приёма данных коннектора, делегирования GraphOS или экспорта трассировок.