Audio Transcriber

CLI 或 API | MCP | Agent

版本: 2.1.0

文档 — 安装、部署以及跨 CLI、Python API、MCP 服务器和 A2A 代理的使用说明均维护在官方文档中。

Related MCP server: audio-transcription-mcp

概述

Audio Transcriber 是一个生产级 Agent 和模型上下文协议（MCP）服务器，旨在直接与“将您的 .wav .mp4 .mp3 .flac 文件转录为文本或录制您自己的音频！”接口对接。

主要特性

• 整合的操作路由 MCP 工具： 通过将方法分组为优化的、可切换的工具模块，最小化 token 开销并消除 LLM 上下文中的工具冗余。

• 企业级安全： 全面支持 Eunomia 策略、OIDC 令牌委派和细粒度的执行上下文跟踪。

• 集成图代理： 内置 Pydantic AI 代理，支持代理控制协议（ACP）和标准 Web 接口（AG-UI）。

• 原生遥测与追踪： 开箱即用的 OpenTelemetry 导出和原生 Langfuse 追踪。

CLI 或 API

该代理封装了“将您的 .wav .mp4 .mp3 .flac 文件转录为文本或录制您自己的音频！”API。您可以通过编程方式或通过其集成的执行入口点与之交互。

有关如何使用底层 API 包装器、扩展模式绑定和开发者 SDK 参考的详细说明，请参阅 docs/index.md。

MCP

该服务器利用动态操作路由工具来优化 token 开销并最大化 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

• HTTP SSE 请求查询参数： 直接将查询参数附加到您的传输连接 URL：

  • ?tools=tool1,tool2

  • ?tags=tag1

当提供查询字符串或参数时，一个无 LLM 的知识图谱解析层（使用 DynamicToolOrchestrator）将查询意图与已知的工具标签、名称或描述进行匹配，并具有安全回退和自动 24 小时后台缓存刷新功能。

MCP 配置示例

安装面向连接器的 [mcp] 附加组件。 示例使用 audio-transcriber[mcp] 通过 agent-utilities[mcp] 添加 FastMCP / FastAPI；所需的 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"
      }
    }
  }
}

或者，通过 url 连接到预先部署的 Streamable-HTTP 实例：

{
  "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、出站身份引用、信任配置文件和精确的 MCP_ALLOWED_HOSTS 保存在 AgentConfig 中。

Agent

该仓库具有一个完全集成的 Pydantic AI 图代理。它通过**代理控制协议（ACP）进行通信，并与代理 Web UI（AG-UI）**和终端界面无缝交互。

运行 Agent 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 将 Agent、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 令牌委派： 符合 RFC 8693 令牌交换，用于从 Web UI / ACP → Agent → MCP 流转经过身份验证的用户凭据。

• 作用域凭据： 执行上下文运行限制为特定的调用者身份。

运行时安全网格

环境变量

包环境变量

继承的 agent-utilities 变量（适用于每个连接器）

16 个包变量 + 16 个继承变量。由 .env.example 和共享的 agent-utilities 集合自动生成——请勿编辑。

服务器读取的每个变量，按用途分组。

转录

MCP 服务器 / 传输

工具开关

每个按操作路由的工具都可以通过其开关环境变量单独禁用（设置为 false）。 权威名称请参见上方的可用 MCP 工具表。

遥测与治理

代理 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 与 :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 运行 agent（immutable agent digest），并带有一个同址的 :mcp sidecar。

知识图谱数据库（epistemic-graph）

[mcp] 和 [agent] 都通过必需的 Agent Utilities 核心依赖（epistemic-graph[full]）携带 epistemic-graph 引擎。[mcp] 扩展依赖保持服务器面向连接器；[agent] 则额外启用模型编排。本地部署可以使用内置引擎。对于生产环境或共享状态，请将 epistemic-graph 作为独立的数据库服务运行，并将运行时配置为使用它。部署方案（单节点 + Raft HA）、连接配置和架构图详见 epistemic-graph 部署指南。

仓库所有者

文档

完整文档已发布为官方文档站点，是安装、部署及日常操作的最佳参考资料。

参与贡献

欢迎贡献！请先运行本地检查以确保代码质量，然后再提交 pull request：

• 使用 ruff format . 格式化代码

• 使用 ruff check . 检查代码风格

• 使用 mypy . 验证类型安全

• 使用 pytest 执行测试套件

使用 agent-utilities-deployment 部署

通过统一的 agent-utilities-deployment 工作流来配置此软件包。它会在已安装包、可编辑源码或不可变容器三种目标之间选择；在 AgentConfig 中仅记录运行时密钥和 TLS 配置引用；并运行 doctor、registration、policy、observability 和 rollback 门禁。请让您的 agent 执行 “deploy audio-transcriber with agent-utilities-deployment”。

该仓库未内嵌任何部署配置、凭据值、证书路径或环境特定端点。请在运行时通过 AgentConfig 和配置的密钥提供方提供这些内容。

受治理能力契约

本软件包提供一个精简而规范的能力面，专家流程以引用的工作流形式维护。当前的 MCP 工具、技能元数据、connector_manifest.yml、本体、映射、形状、fixtures、迁移、工具架构指纹以及认证元数据共同构成一份版本化的能力契约。请将它们整体验证；不要依赖过时的工具名或历史遗留的按任务划分的技能包装。

运行时端点、凭据、证书信任、租户身份、保留策略和可观测性策略均属于部署输入，绝不会打包为内置值。在启用网络传输、连接器、GraphOS 委托或 trace 导出之前，请阅读配置、信任和隐私说明。