Auphonic MCP

语音MCP服务器

用于语音音频处理的生产就绪HTTP模型上下文协议服务器。

概述

基于HTTP-的MCP服务器实现流式HTTP传输（规范2025-03-26），向OpenClaw、OpenCode和其他MCP客户端等AI代理展示Auphonic API功能。

主要特点：

• ✅ 完全符合MCP（方案2025-03-26）
• ✅ 具有安全UUID的会话管理
• ✅ 全面的错误处理
• ✅ 输入验证
• ✅ 生产状态跟踪
• ✅ 健康监测

快速开始

# Install Babashka
brew install borkdude/brew/babashka  # macOS
# OR
curl -sLO https://raw.githubusercontent.com/babashka/babashka/master/install
chmod +x install && ./install  # Linux

# Set environment variables
export AUPHONIC_API_KEY="your-api-key"
export AUPHONIC_PRESET_LUP="preset-uuid"
export AUPHONIC_PRESET_LAUNCH="preset-uuid"

# Run server
chmod +x auphonic-mcp-server.clj
./auphonic-mcp-server.clj 3003

服务器在上运行 http://localhost:3003 带端点 /mcp.

配置

环境变量

\*如果上传该节目的文件，则为必填项。

获取凭据：

1. API密钥：https://auphonic.com/account
2. 预设UUID：https://auphonic.com/presets → 单击预设→ 从URL复制UUID

显示配置

预配置显示：

• 土地：类型： bootleg, adfree, main
• 发射：类型： bootleg, main

通过编辑添加更多节目 show-types 在服务器文件中。

MCP能力

工具（6）

1. upload_audio -上传并开始处理

   {
     "show": "lup",
     "type": "bootleg",
     "file_path": "/absolute/path/to/file.mp3",
     "title": "Optional title",
     "subtitle": "Optional subtitle",
     "summary": "Optional summary"
   }

1. check_status -获取生产状态

   {
     "production_uuid": "abc123..."
   }

1. 列表_产品 -使用筛选列出产品

   {
     "limit": 20,
     "offset": 0,
     "status": 3
   }

1. 下载输出 -下载已处理文件

   {
     "production_uuid": "abc123...",
     "output_path": "/path/to/save",
     "format": "mp3"
   }

1. 删除生产 -删除生产

   {
     "production_uuid": "abc123..."
   }

1. list_presets -列出可用预设

   {}

资源（3）

• auphonic://config -服务器配置和显示设置
• auphonic://presets -所有可用预设
• auphonic://production/{uuid} -具体生产细节

提示（3）

• upload_and_process -引导上传工作流程
• analyze_production -生产分析
• check_recent_uploads -最近上传状态

协议

可流式HTTP传输

初始化会话：

curl -X POST http://localhost:3003/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": {"name": "my-client", "version": "1.0"},
      "capabilities": {}
    }
  }'

响应包括 Mcp-Session-Id 头球在所有后续请求中使用此选项：

curl -X POST http://localhost:3003/mcp \
  -H "Mcp-Session-Id: {session-id}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

终止会话：

curl -X DELETE http://localhost:3003/mcp \
  -H "Mcp-Session-Id: {session-id}"

会话管理

• 服务器在初始化时分配UUID
• 客户必须包括 Mcp-Session-Id init后所有请求的标头
• 除以下方法外，所有方法都需要会话 initialize
• 缺少会话ID→ 400 错误请求
• 会话ID无效→ 404 未找到

错误处理

JSON-RPC错误：

• -32700：解析错误（JSON格式错误）
• -32601：未找到方法
• -32602：无效参数
• -32603：内部错误
• -32000：应用程序错误（验证、API错误）

HTTP状态代码：

• 200 OK：成功
• 400 Bad Request：缺少会话，请求格式错误
• 404 Not Found：会话ID无效
• 415 Unsupported Media Type：内容类型错误
• 500 Internal Server Error：服务器错误

测试

运行测试套件

# Start server on port 3001
./auphonic-mcp-server.clj 3001 &

# Run tests
bb test-runner.clj

测试包括：

• 协议遵从
• 会话管理
• 输入验证
• 错误处理
• 工具功能
• 资源访问
• 并发请求

手动测试

健康检查：

curl http://localhost:3003/health

初始化：

curl -X POST http://localhost:3003/mcp \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}'

列出工具：

curl -X POST http://localhost:3003/mcp \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

集成示例

OpenClaw/OpenCode

在代理的MCP设置中配置：

{
  "mcpServers": {
    "auphonic": {
      "url": "http://localhost:3003/mcp",
      "env": {
        "AUPHONIC_API_KEY": "your-key",
        "AUPHONIC_PRESET_LUP": "preset-uuid",
        "AUPHONIC_PRESET_LAUNCH": "preset-uuid"
      }
    }
  }
}

自定义客户端

import requests

# Initialize
response = requests.post('http://localhost:3003/mcp', 
    headers={
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    json={
        'jsonrpc': '2.0',
        'id': 1,
        'method': 'initialize',
        'params': {
            'protocolVersion': '2025-03-26',
            'clientInfo': {'name': 'my-client', 'version': '1.0'},
            'capabilities': {}
        }
    })

session_id = response.headers['Mcp-Session-Id']

# Use tools
response = requests.post('http://localhost:3003/mcp',
    headers={
        'Mcp-Session-Id': session_id,
        'Content-Type': 'application/json'
    },
    json={
        'jsonrpc': '2.0',
        'id': 2,
        'method': 'tools/call',
        'params': {
            'name': 'list_presets',
            'arguments': {}
        }
    })

生产部署

系统化服务

[Unit]
Description=Auphonic MCP Server
After=network.target

[Service]
Type=simple
User=auphonic-mcp
Group=auphonic-mcp
WorkingDirectory=/opt/auphonic-mcp
EnvironmentFile=/etc/auphonic-mcp/secrets
ExecStart=/usr/local/bin/bb /opt/auphonic-mcp/auphonic-mcp-server.clj 3003
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

注： 将API密钥存储在 EnvironmentFile，不是内联 Environment= 价值观。

码头工人

FROM babashka/babashka:latest

WORKDIR /app
COPY auphonic-mcp-server.clj .

ENV AUPHONIC_API_KEY=""
ENV AUPHONIC_PRESET_LUP=""
ENV AUPHONIC_PRESET_LAUNCH=""

EXPOSE 3003

CMD ["bb", "auphonic-mcp-server.clj", "3003"]

docker build -t auphonic-mcp .
docker run -p 3003:3003 \
  -e AUPHONIC_API_KEY="your-key" \
  -e AUPHONIC_PRESET_LUP="preset-uuid" \
  -e AUPHONIC_PRESET_LAUNCH="preset-uuid" \
  auphonic-mcp

反向代理（nginx）

server {
    listen 80;
    server_name auphonic-mcp.example.com;

    location /mcp {
        proxy_pass http://localhost:3003/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /health {
        proxy_pass http://localhost:3003/health;
    }
}

Nixos模块

从薄片输入导入模块并配置：

{ config, pkgs, ... }:

let
  secretsFile = "/etc/nixos/secrets/auphonic-mcp.env";
in {
  imports = [ inputs.auphonic-mcp.nixosModules.default ];

  services.auphonic-mcp = {
    enable = true;
    port = 3003;
    openFirewall = true;
    environmentFile = secretsFile;
  };
}

创建机密文件(/etc/nixos/secrets/auphonic-mcp.env):

AUPHONIC_API_KEY=your-api-key
AUPHONIC_PRESET_LUP=preset-uuid
AUPHONIC_PRESET_LAUNCH=preset-uuid

家庭管理器模块

{ inputs, pkgs, ... }:

{
  imports = [ inputs.auphonic-mcp.homeManagerModules.default ];

  programs.auphonic-mcp = {
    enable = true;
    apiKeyFile = "/home/user/.config/auphonic-mcp/api-key";
    presets = {
      lup = "preset-uuid";
      launch = "preset-uuid";
    };
  };
}

安全

最佳实践

• ✅ 仅将API密钥存储在环境变量中
• ✅ 在生产环境中使用HTTPS（反向代理）
• ✅ 在反向代理上实施速率限制
• ✅ 验证所有用户输入
• ✅ 仅使用绝对文件路径
• ✅ 如果远程不需要，将服务器限制为本地主机
• ✅ 在反向代理级别实现身份验证
• ✅ 监视器/健康端点
• ✅ 设置安全会话ID（UUID）
• ✅ 验证源标头（DNS重新绑定保护）

输入验证

服务器验证：

• 必填字段存在
• 显示白名单中的姓名
• 剧集类型匹配节目
• 文件路径存在
• UUID有效

无效的输入返回明确的错误消息。

建筑

┌─────────────┐
│ MCP Client  │
│ (Agent)     │
└──────┬──────┘
       │ HTTP POST /mcp
       │ (JSON-RPC 2.0)
       ↓
┌──────────────────────┐
│ Auphonic MCP Server  │
│ ┌──────────────────┐ │
│ │ Session Manager  │ │
│ ├──────────────────┤ │
│ │ JSON-RPC Handler │ │
│ ├──────────────────┤ │
│ │ Tool Handlers    │ │
│ │ Resource Handlers│ │
│ │ Prompt Handlers  │ │
│ ├──────────────────┤ │
│ │ Validation Layer │ │
│ ├──────────────────┤ │
│ │ HTTP Client      │ │
│ └──────────────────┘ │
└──────────┬───────────┘
           │ HTTPS
           ↓
    ┌──────────────┐
    │ Auphonic API │
    └──────────────┘

发展

代码结构

;; Configuration - Constants and defaults
;; State Management - Session and production tracking
;; Environment & Validation - Input validation helpers
;; HTTP Client - Auphonic API wrapper
;; Tool Implementations - MCP tool functions
;; Resource Handlers - MCP resource functions
;; Prompt Generators - MCP prompt functions
;; Protocol Handlers - MCP method handlers
;; JSON-RPC Handler - Protocol logic
;; HTTP Server - Transport layer
;; Main - Entry point

设计原则

1. 简单、直接的功能 -没有不必要的抽象
2. 显式验证 -在边界处验证
3. 清除错误消息 -帮助用户了解问题
4. 习语巴巴什卡 -正确使用fs、http客户端
5. 生产就绪 -错误处理、日志记录、监控

添加工具

;; 1. Implement tool function
(defn tool-my-new-tool [{:keys [arg1 arg2]}]
  (if-let [error (validate-required-fields ...)]
    {:error (:error error)}
    ;; Implementation
    {:content [{:type "text" :text "Result"}]}))

;; 2. Add to handle-tools-list
{:name "my_new_tool"
 :description "What it does"
 :inputSchema {:type "object"
               :properties {:arg1 {:type "string"}}
               :required ["arg1"]}}

;; 3. Add to handle-tools-call
"my_new_tool" (tool-my-new-tool arguments)

故障排除

服务器无法启动

# Check Babashka installed
bb --version

# Check port available
lsof -i :3003

# Check environment variables
env | grep AUPHONIC

API错误

# Test API key
curl -H "Authorization: Bearer $AUPHONIC_API_KEY" \
  https://auphonic.com/api/info.json

# Check preset exists
curl -H "Authorization: Bearer $AUPHONIC_API_KEY" \
  https://auphonic.com/api/preset/$AUPHONIC_PRESET_LUP.json

会话错误

• 服务器重新启动时会话过期
• 会话在使用前需要初始化
• 检查标头中的会话ID是否与服务器的会话ID匹配

上传失败

• 使用绝对路径： /Users/you/file.mp3 不 ~/file.mp3
• 验证文件是否存在： ls -lh /path/to/file.mp3
• 检查文件是否可读
• 确保Auphonic帐户上有足够的磁盘空间

演出

• 启动时间：~50ms（巴巴什卡本地人）
• 记忆：约30MB（巴巴什卡进程）
• 并发会话：用100测试+
• 请求延迟：＜10ms（不包括Auphonic API）

局限性

• 最大文件大小：取决于Auphonic客户计划
• 处理时间：通常每小时音频处理1-5分钟
• 大文件上传不支持流媒体
• 服务器重启时会话状态丢失

资源

• MCP规范: https://spec.modelcontextprotocol.io/
• 立体声API: https://auphonic.com/help/api/
• 巴巴什卡: https://babashka.org/

许可证

麻省理工学院