Audio Transcriber

CLI oder API | MCP | Agent

Version: 2.1.0

Dokumentation — Installation, Bereitstellung und Nutzung über die CLI, die Python-API, den MCP-Server und den A2A-Agenten werden in der offiziellen Dokumentation verwaltet.

Related MCP server: audio-transcription-mcp

Übersicht

Audio Transcriber ist ein produktionsreifer Agent- und Model Context Protocol (MCP)-Server, mit dem Sie Ihre .wav-.mp4-.mp3-.flac-Dateien direkt in Text transkribieren oder eigenes Audio aufnehmen können.

Hauptfunktionen

• Konsolidierte, aktionsgeroutete MCP-Tools: Reduziert den Token-Overhead und vermeidet Tool-Aufblähung in LLM-Kontexten, indem Methoden in optimierte, zuschaltbare Tool-Module gruppiert werden.

• Sicherheit auf Enterprise-Niveau: Umfassende Unterstützung für Eunomia-Richtlinien, OIDC-Token-Delegation und granulare Ausführungskontext-Nachverfolgung.

• Integrierter Graph-Agent: Integrierter Pydantic-AI-Agent mit Unterstützung für das Agent Control Protocol (ACP) und standardmäßige Web-Schnittstellen (AG-UI).

• Native Telemetrie & Tracing: OpenTelemetry-Exporte out-of-the-box und natives Langfuse-Tracing.

CLI oder API

Dieser Agent kapselt die API, mit der Ihre .wav-.mp4-.mp3-.flac-Dateien in Text transkribiert werden können oder eigenes Audio aufgezeichnet wird. Sie können programmatisch oder über die integrierten Ausführungseinstiegspunkte darauf zugreifen.

Detaillierte Anweisungen zur Verwendung der zugrunde liegenden API-Wrapper, der erweiterten Schema-Bindungen und der SDK-Referenzen sind in docs/index.md zu finden.

MCP

Dieser Server nutzt dynamische, aktionsgeroutete Tools, um den Token-Overhead zu optimieren und die IDE-Kompatibilität zu maximieren.

Verfügbare MCP-Tools

Die folgende Tabelle wird automatisch aus dem live Server generiert — nicht von Hand bearbeiten.

Kompakte aktionsgeroutete Tools (MCP_TOOL_MODE=condensed)

Ausführliche 1:1-API-zugeordnete Tools (MCP_TOOL_MODE=verbose oder both)

4 aktionsgeroutete(s) Tool(s) · 7 ausführliche 1:1-Tool(s). Jedes Tool ist aktiviert, sofern nicht sein <DOMAIN>TOOL-Schalter auf false gesetzt ist; MCP_TOOL_MODE wählt die Oberfläche (**intent Standard* — die sechs Verb-Tools, granulare Set bei Bedarf geladen · condensed aktionsgeroutet · verbose 1:1 · both). Automatisiert generiert — nicht bearbeiten.*

Detaillierte Tool-Schemas, Parameterformen und Validierungsbedingungen sind in docs/usage.md dokumentiert.

Dynamische Tool-Auswahl und Sichtbarkeit

Dieser MCP-Server unterstützt dynamische Auswahl und Sichtbarkeitsfilterung der Tool-Mengen zur Laufzeit. Damit können Sie die Menge der angezeigten Tools einschränken und so das Aufblähen des Langkontexts verhindern verwenden.

Channels für den Tool-Filter:

• CLI-Argumente: Übergeben Sie --tools oder --toolsets (oder die deaktivierten Sichtstücke --disabled-tools und --disabled-toolsets) beim Start.

• Umgebungsvariablen: Definieren Sie die Standard-Umgebungsvariablen:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP-SSE-Request-Header: Übergeben Sie benutzerdefinierte Header bei der Transportinitialisierung:

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

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

• HTTP-SSE-Query-Parameter: Hängen Sie die Query-Parameter direkt an die URL der Transport-Verbindung an:

  • ?tools=tool1,tool2

  • ?tags=tag1

Wenn Query-Strings oder Parameter angegeben werden, gleicht eine LLM-freie Knowledge Graph-Auflösungsschicht (mit DynamicToolOrchestrator) die Anfrage-Absichten mit bekannten Tool-Tags, -Namen oder -Beschreibungen ab — inklusive sicherem Dezframe und automatisiertem 24-Stunden-Cache-Refresh im Hintergrund.

MCP-Konfigurationsbeispiele

Installieren Sie das verbindungsorientierte [mcp]-Extra. Die Beispiele verwenden audio-transcriber[mcp], um über agent-utilities[mcp] „FastMCP / FastAPI" hinzuzufügen; der benötigte Agent-Utilities-Kern lädt weiterhin epistemic-graph[full]. Das Extra [agent-runtime] aktiviert zusätzlich die Modell-Orchestrierung.

stdio-Transport (lokale IDEs — 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"
      }
    }
  }
}

Laufzeit-References erfordern einen alias-bewussten Launcher wie GraphOS. Andere Launcher müssen diese Einträge weglassen und die aufgelösten Werte über ihre eigene Geheimnis-Grenze zur Laufzeit injizieren.

Streamable-HTTP-Transport (Netzwerk / Produktion)

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

Alternativ können Sie über url eine Verbindung zu einer bereits bereitgestellten Streamable-HTTP-Instanz herstellen:

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

Sie können ein geprüftes Container-Image als stdio-Kindprozess mit minimalen Privilegien ausführen (ohne Listener oder veröffentlichten Port):

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

Für containerisierten Netzwerk-HTTP-Dienst stellen Sie einen authentifizierten TLS-Ingress (oder direktes Server-TLS), die exakten MCP_ALLOWED_HOSTS und eine genaue vertrauenswürdige-CIDR-Proxypolicy über das Deployment-Profil des Betreibers bereit. Der Generator erzeugt keinen unauthentifizierten Non-Loopback-Listener.

Automatisch generiert auf EM Basis der Code analysierten Env-Oberfläche (MCP_TOOL_MODE + Paketvariablen) — nicht bearbeiten.

Weitere Deployment-Optionen

audio-transcriber kann als lokaler stdio-Prozess oder Container laufen, bei behindertem Remote-Webrunden Sendegrenze nicht erforderlich. Die Deployment-Anleitung enthält alle Details zum Transportvertrag.

• Lokaler Container — Starten Sie ein geprüftes unveränderliches Image als stdio-Kindprozess mit minimalem-Command none, ohne Listener naht veröffentlichten Port hinzufügen.

• Remote-URL — Stellen Sie über einen vom Betreiber bereitgestellten authentifizierten HTTPS-Ingress her. Bitte URL, nicht ausgehende Identitätsreferenzen, das Vertrauebensprofil und die exakten MCP_ALLOWED_HOSTS in der AgentConfig.

Agent

Dieses Repository enthält einen vollständig integrierten Pydantic-AI-Graph-Agenten. Dieser kommuniziert über das Agent Control Protocol (ACP) und interagiert einsatzbereit mit der Agent Web UI (AG-UI) und der Terminal-Schnittstelle.

CLI-Agent ausführen

So starten Sie den interaktiven Agenten über das Befehlszeilen-Interface:

# 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-Orchestrierung

Die folgende docker/agent.compose.yml konfiguriert Agent, Web-Benutzeroberfläche und Terminal-Oberfläche zusammen:

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"

Detaillierte Erläuterungen zur Graph-Knoten-Architektur, zu Konfiguration eigener Fähigkeiten und zu Agent-Trace-Anleitungen sind in docs/deployment.md verfügbar.

Sicherheit und Governance

Direkt auf Basis des Enterprise-Fähigen agent-utilities werden die Standard-Sicherheitsparameter vollständig unterstützt:

Zugriffskontrolle und Richtliniendurchsetzung

• Eunomia-Richtlinien: Fein abgestufte, richtliniengesteuerte Tool-Autorisierung. Unterstützt none, lokale embedded (mcp_policies.json), oder zentral remote Varianten.

• OIDC-Token-Delegation: Konform mit RFC 8693 Token Exchange, um authentifizierte Nutzeranmelde informationen von Web UI / ACP → Agent → MCP weiterzuleiten.

• Awckreide Anmeldeinformationen: Ausführungskontexte werden auf die Identität des jeweiligen Aufrufers begrenzt.

Laufzeit-Sicherheitsmatrix

Umgebungsvariablen

Paket-Umgebungsvariablen

Geerbte agent-utilities-Variablen (gelten für jeden Connector)

16 Paket- + 16 geerbte Variable(n). Automatisch generiert aus .env.example + dem gemeinsamen agent-utilities-Satz — nicht bearbeiten.

Jede Variable, die der Server liest, gruppiert nach Zweck.

Transkription

MCP-Server / Transport

Tool-Schalter

Jedes aktionsgesteuerte Tool kann einzeln über seine Schalter-Umgebungsvariable deaktiviert werden (auf false setzen). Siehe die Tabelle Verfügbare MCP-Tools oben für die maßgeblichen Namen.

Telemetrie & Governance

Agent-CLI (nur vollständige [agent]-Laufzeit)

Siehe .env.example für einen Kopier-und-Einfügen-Ausgangspunkt.

Installation

Wählen Sie das Extra, das zu dem passt, was Sie ausführen möchten:

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

Container-Images (:mcp vs. :agent)

Ein mehrstufiges docker/Dockerfile erstellt zwei passend dimensionierte Images, ausgewählt über --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 startet den connector-fokussierten :mcp-Server; docker/agent.compose.yml startet den Agenten (immutable agent digest) mit einem ko-lokalisierten :mcp-Sidecar.

Knowledge-Graph-Datenbank (epistemic-graph)

Sowohl [mcp] als auch [agent] enthalten die epistemic-graph-Engine über die erforderliche Kernabhängigkeit von Agent Utilities (epistemic-graph[full]). Das [mcp]-Extra hält den Server connector-fokussiert; [agent] ermöglicht zusätzlich die Modell-Orchestrierung. Lokale Bereitstellungen können die gebündelte Engine verwenden. Für Produktion oder geteilten Zustand betreiben Sie epistemic-graph als dedizierten Datenbankdienst und konfigurieren Sie die Laufzeitumgebung so, dass sie diesen verwendet. Bereitstellungsrezepte (Single-Node + Raft-HA), Verbindungskonfiguration und Architekturdiagramme sind im epistemic-graph-Bereitstellungsleitfaden dokumentiert.

Repository-Besitzer

Dokumentation

Die vollständige Dokumentation ist als offizielle Dokumentationsseite veröffentlicht und die empfohlene Referenz für Installation, Bereitstellung und den täglichen Betrieb.

Mitwirken

Beiträge sind willkommen! Bitte stellen Sie die Codequalität sicher, indem Sie vor dem Einreichen von Pull Requests lokale Prüfungen ausführen:

• Formatieren Sie den Code mit ruff format .

• Linten Sie den Code mit ruff check .

• Validieren Sie die Typsicherheit mit mypy .

• Führen Sie die Testsuiten mit pytest aus

Bereitstellen mit agent-utilities-deployment

Stellen Sie dieses Paket mit dem konsolidierten agent-utilities-deployment-Workflow bereit. Er wählt einen Pfad für installiertes Paket, bearbeitbare Quelle oder unveränderlichen Container aus; erfasst nur Referenzen auf Laufzeit-Secrets und TLS-Profile in AgentConfig; führt Doctor-, Registrierungs-, Richtlinien-, Observability- und Rollback-Gates aus. Bitten Sie Ihren Agenten, „audio-transcriber mit agent-utilities-deployment bereitzustellen“.

Das Repository enthält kein Bereitstellungsprofil, keinen Anmeldedatenwert, keinen Zertifikatspfad und keinen umgebungsspezifischen Endpunkt. Stellen Sie diese zur Laufzeit über AgentConfig und den konfigurierten Secret-Provider bereit.

Governed-Capability-Vertrag

Dieses Paket enthält eine kompakte kanonische Skill-Oberfläche, deren spezialisierte Verfahren als referenzierte Workflows hinterlegt sind. Die aktuellen MCP-Tools, Skill-Metadaten, connector_manifest.yml, Ontologie, Mappings, Shapes, Fixtures, Migrationen, Tool-Schema-Fingerabdrücke und Zertifizierungsmetadaten bilden einen versionierten Capability-Vertrag. Validieren Sie sie gemeinsam; verlassen Sie sich nicht auf veraltete Tool-Namen oder historische aufgabenspezifische Skill-Wrapper.

Laufzeit-Endpunkte, Anmeldedaten, Zertifikatsvertrauen, Mandantenidentität, Aufbewahrung und Observability-Richtlinien sind Bereitstellungs-Eingaben und niemals verpackte Werte. Siehe Konfiguration, Vertrauen und Datenschutz, bevor Sie einen Netzwerktransport, eine Connector-Ingestion, eine GraphOS-Delegierung oder einen Trace-Export aktivieren.