使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 构建的服务器示例，旨在将 Typecast API 的语音合成能力以标准化的 MCP 接口提供给各类 LLM 客户端。通过此服务器，LLM 应用可以方便地调用 Typecast API 的文本转语音功能，实现更丰富的交互体验。

主要功能点

获取语音列表 (Get Voices): 允许客户端查询 Typecast API 支持的所有语音模型和声音。
文本转语音 (Text to Speech): 将文本转换为语音，支持多种语音模型、情感预设、语速、语调等参数调节。
播放音频 (Play Audio): 提供本地音频播放功能，方便快速试听生成的语音。

安装步骤

克隆仓库:

git clone https://github.com/neosapience/typecast-api-mcp-server-sample.git
cd typecast-api-mcp-server-sample

安装依赖: 确保已安装 Python 3.10 或更高版本，并使用 'uv' 进行包管理。
```
uv venv
uv pip install -e .
```

配置环境变量: 设置以下环境变量，用于连接 Typecast API 和配置输出目录。

TYPECAST_API_HOST=https://api.typecast.ai  # Typecast API 主机地址
TYPECAST_API_KEY=<your-api-key>        # 你的 Typecast API 密钥
TYPECAST_OUTPUT_DIR=<your-output-directory> # 音频输出目录 (默认为 ~/Downloads/typecast_output)

请将 '<your-api-key>' 替换为你的实际 Typecast API 密钥，'<your-output-directory>' 替换为你希望保存生成音频的目录。

服务器配置

对于 MCP 客户端（例如 Claude Desktop），你需要在客户端的配置文件中添加以下服务器配置信息。这告诉客户端如何启动和连接到 Typecast API MCP 服务器。

{
  "mcpServers": {
    "typecast-api-mcp-server": {  // 服务器名称，客户端用以识别
      "command": "uv",          // 启动服务器的命令，这里使用 uv 运行器
      "args": [                 // 命令参数
        "--directory",        // 指定工作目录
        "/PATH/TO/YOUR/PROJECT", //  **[请替换为你的项目实际路径]**  指向你克隆的项目目录
        "run",                // uv 的 run 命令，用于运行 Python 脚本
        "typecast-api-mcp-server" //  实际执行的入口点，对应 app/main.py 中定义的 click 命令名称
      ],
      "env": {                   // 环境变量
        "TYPECAST_API_HOST": "https://api.typecast.ai", // Typecast API 主机地址
        "TYPECAST_API_KEY": "YOUR_API_KEY",           // **[请替换为你的 Typecast API 密钥]** 你的 Typecast API 密钥
        "TYPECAST_OUTPUT_DIR": "PATH/TO/YOUR/OUTPUT/DIR" // **[请替换为你希望的音频输出目录]** 音频输出目录
      }
    }
  }
}

请务必将上述配置中的 '/PATH/TO/YOUR/PROJECT'、'YOUR_API_KEY' 和 'PATH/TO/YOUR/OUTPUT/DIR' 替换为你的实际项目路径、API 密钥和输出目录。 'command' 和 'args' 字段定义了客户端启动 MCP 服务器的指令，客户端会根据这些配置在本地启动服务器进程并建立连接。

基本使用方法

启动服务器: 你可以使用以下命令手动启动服务器，进行测试或调试。
```
uv run python app/main.py
```
或者，如果你配置了 Claude Desktop 等 MCP 客户端，客户端会在需要时自动启动服务器。
在 MCP 客户端中使用: 一旦服务器配置完成并启动，你就可以在 MCP 客户端中调用 'get_voices'、'text_to_speech' 和 'play_audio' 等工具，利用 Typecast API 的语音合成能力。具体调用方式请参考 MCP 客户端的文档。

例如，在 Claude Desktop 中，你可以通过自然语言指令或图形界面来调用这些工具，例如：

"列出所有可用的语音" (对应 'get_voices' 工具)
"用 [语音ID] 以 [情感] 朗读 [文本内容]" (对应 'text_to_speech' 工具)
"播放上次生成的音频" (可能在客户端内部调用 'play_audio' 工具)

关键词