Audio Transcriber

CLI 또는 API | MCP | 에이전트

버전: 2.1.0

문서 — CLI, Python API, MCP 서버 및 A2A 에이전트 전반의 설치, 배포, 사용 방법은 공식 문서에서 관리됩니다.

Related MCP server: audio-transcription-mcp

개요

Audio Transcriber는 Transcribe your .wav .mp4 .mp3 .flac files to text or record your own audio!와 직접 인터페이스하도록 설계된 프로덕션급 에이전트 및 Model Context Protocol (MCP) 서버입니다.

주요 기능

• 통합 액션 라우팅 MCP 도구: 메서드를 최적화된 토글 가능한 도구 모듈로 그룹화하여 LLM 컨텍스트의 토큰 오버헤드를 최소화하고 도구 비대화를 제거합니다.

• 엔터프라이즈급 보안: Eunomia 정책, OIDC 토큰 위임 및 세분화된 실행 컨텍스트 추적을 포괄적으로 지원합니다.

• 통합 그래프 에이전트: Agent Control Protocol (ACP) 및 표준 웹 인터페이스(AG-UI)를 지원하는 내장 Pydantic AI 에이전트를 포함합니다.

• 네이티브 원격 측정 및 추적: 기본 제공되는 OpenTelemetry 내보내기와 네이티브 Langfuse 추적을 지원합니다.

CLI 또는 API

이 에이전트는 Transcribe your .wav .mp4 .mp3 .flac files to text or record your own audio! API를 래핑합니다. 프로그래밍 방식 또는 통합 실행 진입점을 통해 이 에이전트와 상호작용할 수 있습니다.

기본 API 래퍼, 확장 스키마 바인딩 및 개발자 SDK 참조 사용 방법에 대한 자세한 지침은 docs/index.md에서 관리됩니다.

MCP

이 서버는 동적 액션 라우팅 도구를 활용하여 토큰 오버헤드를 최적화하고 IDE 호환성을 극대화합니다.

사용 가능한 MCP 도구

아래 표는 라이브 서버에서 자동으로 생성된 것입니다 — 수동으로 편집하지 마십시오.

축약형 액션 라우팅 도구 (MCP_TOOL_MODE=condensed)

상세 1:1 API 매핑 도구 (MCP_TOOL_MODE=verbose 또는 both)

액션 라우팅 도구 4개 · 상세 1:1 도구 7개. 각 도구는 해당 <DOMAIN>TOOL 토글이 false로 설정되지 않는 한 활성화됩니다. MCP_TOOL_MODE는 표면을 선택합니다(**intent 기본값* — 동사형 도구 6개, 요청 시 로드되는 세분화된 세트 · 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

• HTTP SSE 요청 쿼리 매개변수: 전송 연결 URL에 쿼리 매개변수를 직접 추가합니다:

  • ?tools=tool1,tool2

  • ?tags=tag1

쿼리 문자열 또는 매개변수가 제공되면 LLM 없는 지식 그래프 해석 계층(DynamicToolOrchestrator 사용)이 쿼리 의도를 알려진 도구 태그, 이름 또는 설명과 매칭하며, 안전한 폴백 및 자동 24시간 백그라운드 캐시 새로고침을 제공합니다.

MCP 구성 예시

커넥터 중심의 [mcp] 엑스트라를 설치하세요. 예시에서는 agent-utilities[mcp]를 통해 FastMCP / FastAPI를 추가하기 위해 audio-transcriber[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 정책을 제공하십시오. 생성기는 인증되지 않은 비루프백 리스너를 생성하지 않습니다.

코드에서 읽은 환경 표면(MCP_TOOL_MODE + 패키지 변수)에서 자동 생성됨 — 편집하지 마십시오.

추가 배포 옵션

audio-transcriber는 로컬 stdio 프로세스 또는 컨테이너로 실행하거나 원격 네트워크 경계 뒤에서 실행할 수 있습니다. 배포 가이드에 자세한 전송 계약이 설명되어 있습니다.

• 로컬 컨테이너 — 검토된 불변 이미지를 리스너 또는 게시된 포트 없이 최소 권한 stdio 자식 프로세스로 실행합니다.

• 원격 URL — 운영자가 제공한 인증된 HTTPS 인그레스를 통해 연결합니다. 해당 URL, 아웃바운드 ID 참조, 신뢰 프로필 및 정확한 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은 에이전트, Web UI 및 터미널 인터페이스를 함께 구성합니다:

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 토큰 위임: Web UI / ACP → 에이전트 → MCP로 인증 사용자 자격 증명을 전달하는 RFC 8693 토큰 교환을 준수합니다.

• 범위 지정 자격 증명: 실행 컨텍스트는 특정 호출자 ID로 제한되어 실행됩니다.

런타임 보안 그리드

환경 변수

패키지 환경 변수

모든 커넥터에 적용되는 상속된 agent-utilities 변수

패키지 16개 + 상속 변수 16개. .env.example + 공유 agent-utilities 세트에서 자동 생성됨 — 편집하지 마세요.

서버가 읽는 모든 변수를 용도별로 그룹화한 것입니다.

전사

MCP 서버 / 전송

도구 토글

각 액션 라우팅 도구는 해당 토글 환경 변수(false로 설정)를 통해 개별적으로 비활성화할 수 있습니다. 정확한 이름은 위의 사용 가능한 MCP 도구 표를 참조하세요.

텔레메트리 및 거버넌스

에이전트 CLI (전체 [agent] 런타임 전용)

복사해서 바로 쓸 수 있는 시작점은 .env.example을 참조하세요.

설치

실행하려는 항목에 맞는 extra를 선택하세요:

# 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 대 :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은 함께 배치된 :mcp 사이드카와 함께 에이전트(immutable agent digest)를 실행합니다.

지식 그래프 데이터베이스 (epistemic-graph)

[mcp]와 [agent]는 모두 필수 Agent Utilities 핵심 의존성(epistemic-graph[full])을 통해 epistemic-graph 엔진을 포함합니다. [mcp] 엑스트라는 서버를 커넥터 중심으로 유지하며, [agent]는 추가로 모델 오케스트레이션을 활성화합니다. 로컬 배포는 번들된 엔진을 사용할 수 있습니다. 프로덕션 또는 공유 상태가 필요하면 epistemic-graph를 전용 데이터베이스 서비스로 실행하고 런타임이 이를 사용하도록 구성하세요. 배포 레시피(단일 노드 + Raft HA), 연결 구성, 아키텍처 다이어그램은 epistemic-graph 배포 가이드에 문서화되어 있습니다.

저장소 소유자

문서

전체 문서는 공식 문서 사이트로 게시되며 설치, 배포, 일상 운영에 권장되는 참고 자료입니다.

기여

기여를 환영합니다! 풀 리퀘스트를 제출하기 전에 로컬 검사를 실행하여 코드 품질을 확인하세요:

• ruff format .로 코드 포맷

• ruff check .로 린트

• mypy .로 타입 안전성 검증

• pytest로 테스트 스위트 실행

agent-utilities-deployment로 배포

통합 agent-utilities-deployment 워크플로로 이 패키지를 프로비저닝하세요. 설치된 패키지, 편집 가능한 소스, 또는 불변 컨테이너 경로를 선택하고, AgentConfig에는 런타임 시크릿 및 TLS 프로필 참조만 기록하며, doctor, 등록, 정책, 관찰 가능성, 롤백 게이트를 실행합니다. 에이전트에게 **"agent-utilities-deployment로 audio-transcriber 배포"**를 요청하세요.

저장소에는 배포 프로필, 자격 증명 값, 인증서 경로, 환경별 엔드포인트가 포함되어 있지 않습니다. 이러한 항목은 AgentConfig와 구성된 시크릿 공급자를 통해 런타임에 제공하세요.

관리형 기능 계약

이 패키지는 전문 절차를 참조 워크플로로 유지하는 간결한 표준 스킬 표면을 제공합니다. 현재 MCP 도구, 스킬 메타데이터, connector_manifest.yml, 온톨로지, 매핑, 셰이프, 픽스처, 마이그레이션, 도구 스키마 지문, 인증 메타데이터가 하나의 버전 관리된 기능 계약을 구성합니다. 이들을 함께 검증하세요. 오래된 도구 이름이나 과거의 작업별 스킬 래퍼에 의존하지 마세요.

런타임 엔드포인트, 자격 증명, 인증서 신뢰, 테넌트 ID, 보존 및 관찰 가능성 정책은 배포 입력 값이며 패키지에 포함된 값이 아닙니다. 네트워크 전송, 커넥터 수집, GraphOS 위임 또는 트레이스 내보내기를 활성화하기 전에 구성, 신뢰 및 개인정보 보호를 참조하세요.