Whissle MCP 服务器

一个基于Python的服务器，提供对Whissle API端点的访问，用于语音转文字、说话人识别、翻译和文本摘要。

⚠️ 重要注意事项

• 该服务器提供对可能产生费用的Whissle API端点的访问。
• 每个进行API调用的工具都会标记有费用警告。
• 请遵循以下指南：
  1. 仅在用户明确请求时使用工具。
  2. 对于处理音频的工具，请考虑音频长度，因为它会影响成本。
  3. 某些操作如翻译或摘要可能具有更高的成本。
  4. 描述中没有费用警告的工具是免费使用的，因为它们只读取现有数据。

预备条件

• Python 3.8 或更高版本
• pip（Python 包管理器）
• 一个 Whissle API 认证令牌

安装

1. 克隆仓库：

   git clone <repository-url>
   cd whissle_mcp
   

2. 创建并激活虚拟环境：

   python -m venv venv
   source venv/bin/activate  # 在Windows上使用：venv\Scripts\activate
   

3. 安装所需包：

   pip install -e .
   

4. 设置环境变量： 在项目根目录创建一个.env文件，内容如下：

   WHISSLE_AUTH_TOKEN=insert_auth_token_here  # 替换为你的实际Whissle API令牌
   WHISSLE_MCP_BASE_PATH=/path/to/your/base/directory
   

   ⚠️ 重要：切勿将实际令牌提交到仓库。.env文件被包含在.gitignore中以防止意外提交。

5. 配置Claude集成： 复制claude_config.example.json到claude_config.json并更新路径：

   {
       "mcpServers": {
           "Whissle": {
               "command": "/path/to/your/venv/bin/python",
               "args": [
                   "/path/to/whissle_mcp/server.py"
               ],
               "env": {
                   "WHISSLE_AUTH_TOKEN": "insert_auth_token_here"
               }
           }
       }
   }
   

   • 将/path/to/your/venv/bin/python替换为虚拟环境中Python解释器的实际路径
   • 将/path/to/whissle_mcp/server.py替换为你server.py文件的实际路径

配置

环境变量

• WHISSLE_AUTH_TOKEN：你的Whissle API认证令牌（必需）
  • 这是一个敏感凭证，不应共享或提交到版本控制中
  • 联系管理员获取有效令牌
  • 在本地.env文件中安全存储它
• WHISSLE_MCP_BASE_PATH：文件操作的基本目录（可选，默认为用户的桌面）

支持的音频格式

服务器支持以下音频格式：

• WAV (.wav)
• MP3 (.mp3)
• OGG (.ogg)
• FLAC (.flac)
• M4A (.m4a)

文件大小限制

• 最大文件大小：25 MB
• 超过此限制的文件将被拒绝

可用工具

1. 语音转文字

使用Whissle API将语音转换为文本。

response = speech_to_text(
    audio_file_path="path/to/audio.wav",
    model_name="en-NER",  # 默认模型
    timestamps=True,      # 包含单词时间戳
    boosted_lm_words=["特定", "术语"],  # 在识别中提升的词语
    boosted_lm_score=80   # 提升词语的得分（0-100）
)

2. 语音说话人识别

将语音转换为文本，并识别说话人。

response = diarize_speech(
    audio_file_path="path/to/audio.wav",
    model_name="en-NER",  # 默认模型
    max_speakers=2,       # 要识别的最大说话人数
    boosted_lm_words=["特定", "术语"],
    boosted_lm_score=80
)

3. 文本翻译

将文本从一种语言翻译成另一种语言。

response = translate_text(
    text="你好，世界！",
    source_language="zh",
    target_language="es"
)

4. 文本摘要

使用LLM模型对文本进行摘要。

response = summarize_text(
    content="需要摘要的长文本...",
    model_name="openai",  # 默认模型
    instruction="提供简要摘要"  # 可选
)

5. 列出ASR模型

列出所有可用的ASR模型及其能力。

response = list_asr_models()

响应格式

语音转文字和说话人识别

{
    "transcript": "转录的文字",
    "duration_seconds": 10.5,
    "language_code": "zh",
    "timestamps": [
        {
            "word": "你好",
            "startTime": 0,
            "endTime": 100,
            "confidence": 0.95
        }
    ],
    "diarize_output": [
        {
            "text": "转录的文字",
            "speaker_id": 1,
            "start_timestamp": 0,
            "end_timestamp": 10.5
        }
    ]
}

翻译

{
    "type": "text",
    "text": "翻译：\n翻译后的文本"
}

摘要

{
    "type": "text",
    "text": "摘要：\n摘要后的文本"
}

错误响应

{
    "error": "错误信息"
}

错误处理

服务器包括强大的错误处理机制：

• 自动重试HTTP 500错误
• 不同失败场景下的详细错误消息
• 文件验证（存在性、大小、格式）
• 认证检查

常见错误类型：

• HTTP 500：服务器错误（带有重试机制）
• HTTP 413：文件太大
• HTTP 415：不支持的文件格式
• HTTP 401/403：认证错误

运行服务器

1. 启动服务器：

   mcp serve
   

2. 服务器将在默认的MCP端口（通常是8000）上可用。

测试

提供了一个测试脚本来验证所有工具的功能：

python test_whissle.py

测试脚本将：

1. 检查认证令牌
2. 测试所有可用工具
3. 提供每个操作的详细输出
4. 优雅地处理错误

支持

对于问题或疑问，请：

1. 查看错误消息的具体细节
2. 验证你的认证令牌
3. 确保你的音频文件符合要求
4. 联系Whissle支持解决与API相关的问题

许可

[在此添加您的许可信息]