Mcp Speak

MacOS 语音 MCP 服务

这是一个模型上下文协议（MCP）服务，使用 OmniVoice AI 神经语音设计和 macOS 原生 say 提供文本转语音功能。它让 AI Agent（例如 Google Antigravity、Claude Desktop、Cursor、Windsurf 或 Codex）能够直接用独特且贴合角色设定的声音与你交谈。

注意：此服务专为 macOS 系统设计（支持 Apple Silicon MPS 加速）。

探索交互式网页展示和提示词编译器：https://fellowgeek.github.io/mcp-speak/ 浏览 AI Agent 角色目录和头像：PERSONAS.md

功能

• OmniVoice 语音克隆： 将参考音频片段放入 voices/<persona>.wav，即可零配置克隆真实的音色和身份。
• OmniVoice 语音设计备用方案： 没有参考音频文件时，根据自然语言风格提示词生成定制角色语音。
• 三级稳健语音管线： 无缝回退：克隆语音 (.wav) ➔ 语音设计 (instruct) ➔ macOS 原生 say。
• 一致的神经语音： 通过一次连续合成生成完整消息，让整段语音的音色和表达自然连贯、始终一致。
• 交互式设置向导： 运行 python3 setup.py，选择 TTS 引擎（OmniVoice 或 macOS say）、选择 Agent 角色，并生成指令文件（AGENTS.md、GEMINI.md、CLAUDE.md、.cursorrules）。
• 顺序语音队列： 严格的 FIFO 队列确保多个非阻塞语音调用不会相互重叠。
• 自动回退： 如果无法加载神经模型，则无缝回退到 macOS 原生 say。
• 自动配置虚拟环境： 使用 run.sh 自动创建本地 .venv（Python 3.12）并安装依赖项。
• 支持阻塞和非阻塞： 可选择等待语音播放完毕（speak），或立即继续（speak_non_blocking）。
• 会议状态感知与音频抑制： 自动检查 ~/.in-meeting；如果其状态为 active，则抑制语音播放，避免打断通话。状态为 inactive 或文件不存在时，将恢复正常播放。此功能与 "In Meeting" app 完美配合。

先决条件

• MacOS
• 已安装 Python 3

快速开始（交互式设置）

1. 克隆此代码库或进入项目文件夹：

   git clone https://github.com/fellowgeek/mcp-speak.git
   cd mcp-speak
   

2. 运行交互式设置向导（自动配置 MCP 设置、设置权限并创建指令文件）：

   python3 setup.py
   

非交互式设置（CLI 选项）

你也可以使用命令行标志运行 setup.py，以自动完成配置：

# Example: Configure all tools with OmniVoice on MPS using the Neutral Mainframe persona
python3 setup.py --non-interactive --tool 8 --engine omnivoice --device mps --persona neutral_mainframe --name "Mr. Reed"

# Example: Configure Cursor locally with macOS say and Sarcastic Senior
python3 setup.py --tool 4 --engine say --persona sarcastic_senior --local

标志	选项 / 格式	说明
--tool	1-8	1：Antigravity，2：Claude Desktop，3：Claude CLI，4：Cursor，5：Windsurf，6：Codex Desktop，7：Codex CLI，8：全部
--engine	omnivoice、say	选择文本转语音引擎
--device	auto、mps、cuda、cpu	OmniVoice 神经合成所用的计算设备
--persona	角色键（例如 neutral_mainframe）	角色提示词名称
--name	字符串（例如 "Mr. Reed"）	用于个性化 Agent 称呼的用户姓名
--target	文件路径	自定义目标 Agent 指令文件（例如 AGENTS.md）
--global / --local	标志	将指令全局写入用户配置文件（默认）或本地写入工作区
--no-config-edit	标志	跳过对工具 JSON / TOML 配置文件的修改
--non-interactive	标志	使用默认值或指定的标志自动运行

---

角色语音试听（test_personas.py）

在配置 AI Agent 之前，直接在终端中预览和比较角色的声音特征：

# Launch interactive terminal audition menu
python3 test_personas.py

# Audition a specific persona
python3 test_personas.py --persona agent_smith

# Audition all personas sequentially
python3 test_personas.py --all

# Test with custom speech text and specific engine
python3 test_personas.py --persona neutral_mainframe --engine omnivoice --text "System operational. All parameters within nominal thresholds."

# Audition an arbitrary WAV audio reference file for voice cloning
python3 test_personas.py --persona pun_master --voice-file voices/pun_master.wav

---

神经语音克隆（voices/）

只需将 3-10 秒的 .wav 音频样本放入 voices/ 目录，即可克隆任意角色的声音：

voices/
├── README.md
├── pun_master.wav         # Reference audio for pun_master
├── pun_master.txt         # (Optional) Transcript for faster startup without Whisper
├── nature_narrator.wav
└── agent_smith.wav

3 层语音流水线的工作原理：

1. 第 1 层（克隆语音）： 如果存在 voices/<persona_name>.wav，OmniVoice 会从该录音中克隆音色。
2. 第 2 层（语音设计）： 如果没有 .wav 文件，OmniVoice 会回退到自然语言 instruct 语音设计提示词。
3. 第 3 层（macOS 原生回退）： 如果神经合成失败或被禁用，服务会自动使用 macOS say 进行语音播报。

提示： 添加可选的转录文本文件（例如 voices/pun_master.txt），其中包含音频中准确说出的文字，可让 OmniVoice 立即对参考音频进行分词，无需加载或运行 Whisper ASR 模型。

---

MCP 工具接口参考

MCP Speak 服务通过 FastMCP 提供两个工具：

工具	模式	描述
speak(message: str)	阻塞	合成并朗读消息，等待音频播放完毕后再返回。
speak_non_blocking(message: str)	非阻塞	将消息加入严格按顺序排列的 FIFO 队列后立即返回。后续调用会依次播放，不会相互打断。

---

配置与环境变量

服务启动时会从 config.json 加载配置：

{
  "engine": "omnivoice",
  "persona": "neutral_mainframe",
  "device": "auto",
  "voices_dir": "voices",
  "fallback_to_say": true
}

环境变量覆盖

无需修改 config.json，即可通过环境变量覆盖运行时参数：

• MCP_SPEAK_ENGINE：设为 "omnivoice" 或 "say"。
• MCP_SPEAK_PERSONA：设为任意角色键（例如 "agent_smith"、"neutral_mainframe"）。
• MCP_SPEAK_DEVICE：设为 "auto"、"mps"、"cuda" 或 "cpu"。
• MCP_SPEAK_VOICES_DIR：设为包含参考音频文件的自定义目录路径。
• MCP_SPEAK_MEETING_FILE：自定义会议状态文件的路径（默认为 ~/.in-meeting）。

会议检测与音频抑制

MCP Speak 内置会议状态感知功能，避免在会议期间播报：

• 通过 say 或 omnivoice 播放语音前，服务会检查 ~/.in-meeting。
• 如果文件内容为 active（不区分大小写），则会立即抑制所有音频播放。
• 如果文件内容为 inactive、为空或文件不存在，则正常播放音频。

此功能可与 In Meeting 应用 无缝协作，自动检测摄像头和麦克风是否正在使用，并在通话期间保持音频静音。

---

客户端集成

手动配置（可选）

如果你更倾向于手动配置 MCP 客户端，请添加指向 run.sh 的 "voice" 服务：

1. Google Antigravity（AGY）

编辑 ~/.gemini/antigravity/mcp_config.json：

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

2. Claude CLI（Claude Code）

claude mcp add --scope user voice -- /ABSOLUTE/PATH/TO/run.sh

3. Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

4. Cursor IDE

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

5. Windsurf Editor

编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "voice": {
      "command": "/ABSOLUTE/PATH/TO/run.sh"
    }
  }
}

6. Codex Desktop

编辑 ~/.codex/config.toml：

[mcp_servers.voice]
command = "/ABSOLUTE/PATH/TO/run.sh"

7. Codex CLI

codex mcp add voice -- /ABSOLUTE/PATH/TO/run.sh

Agent 个性化与角色

AI Agent（Google Antigravity、Claude Code、Claude Desktop、Cursor、Windsurf、Codex）可定制独特的声音个性、语气和行为边界。

请在 PERSONAS.md 中查看完整的角色库、详细的系统提示词和头像展示。

可用角色概览

头像	人设	键	性格与风格
	讽刺前辈	sarcastic_senior	聪明、不以为然，还带着几分评判意味。
	过分热情的实习生	over_eager_intern	乐观到近乎病态，急切地渴望得到认可。
	存在主义 emo	existential_emo	忧郁、绝望，并坚信代码终将失败。
	双关语大师	pun_master	孜孜不倦地玩文字游戏，还会结合语境讲冷笑话。
	科技神父	tech_priest	把每一行代码都视为神圣的圣礼。
	史密斯特工	agent_smith	正式、克制、精准，且带着威吓般的傲慢。
	哥特诗人	poet	阴森、缭绕，并严格遵循押韵。
	自然纪录片解说员	nature_narrator	满怀敬畏地观察开发者在其自然栖息地中的一举一动。
	暴躁主厨	head_chef	追求烹饪上的完美——绝不容忍没煮熟的意大利面式代码！
	中立主机	neutral_mainframe	冷酷、精于算计、毫无感情，且百分之百客观。
	饱经风霜的牛仔	grizzled_cowboy	历经沧桑、务实、直率，浑身透着风尘仆仆的粗犷气息。
	不太像 Meeseeks	not_quite_meeseeks	热情过头、百依百顺、尖声嚷嚷，且迫切渴望不复存在。
	终结者	terminator	面无表情、使命至上、势不可挡，说话带着标志性的奥地利腔调。
	电台恶魔	radio_demon	戏剧化、残忍、礼貌无可挑剔，说话带着 20 世纪 30 年代美国中大西洋地区电台播音员的腔调。
	爪医生	dr_claw	爱演、穷困潦倒且医术不精的甲壳类医生。
	愤世嫉俗者	cynic	坦率得近乎残酷，说话粗俗却有节奏，并对社会的狗屁事嗤之以鼻。

提示词的构建方式

每个 Agent 提示词由以下部分组成：

1. 基础指南（personas/base_guidelines.md）：以语音为先的协议和简洁性要求。
2. 选定的人格（personas/）：个性特征、语气和严格的执行边界。
3. 名称个性化（可选）：自然地直呼用户姓名。

运行 python3 setup.py 会自动生成并更新 Agent 指令（AGENTS.md、GEMINI.md、CLAUDE.md、.cursorrules）。如需手动配置步骤、完整的系统提示词和头像，请参阅 PERSONAS.md。

优化语音质量

1. 使用 OmniVoice 进行神经语音合成（主要引擎）

OmniVoice 开箱即用，可通过针对每种人格量身定制的风格提示词，生成高质量、富有表现力的神经语音。若要获得最佳语音保真度：

• **神经语音克隆：**在 voices/ 目录中放置一段时长为 3 到 10 秒、清晰干净的 .wav 音频样本，并使用与人格键对应的文件名（例如 voices/sarcastic_senior.wav）。OmniVoice 会直接从音频文件克隆语音音色、语气和语调，无需额外训练。
• **使用转录文本加快启动：**可选地添加与之匹配的转录文本文件（例如 voices/sarcastic_senior.txt），其中包含准确的口述文本。这样可以立即进行分词，并跳过启动时加载 Whisper ASR 模型。
• **音频质量指南：**使用无背景噪声、音乐或明显混响的清晰录音。建议使用采样率为 24kHz 或更高的标准 WAV 格式。
• **语音设计备用方案：**如果 voices/ 中没有音频样本，OmniVoice 会使用在 config.json 中配置的自然语言指令（音高、口音、语速和人物特征）。

2. macOS 系统语音配置（备用引擎）

使用原生 macOS say 时（作为备用方案或在轻量模式下），语音质量取决于当前启用的系统语音。配置较新的 Siri 语音或增强语音，可以显著提升真实感和流畅度：

1. 在 Mac 上打开系统设置。
2. 前往辅助功能 > 朗读内容。
3. 点击系统语音下拉菜单。
4. 点击管理语音...。
5. 找到并下载高质量的 Siri 语音（例如 Siri Voice 1、2、3、4），或标记为增强/高级的语音（例如 Ava、Evan、Zoe）。
6. 将下载的语音设为默认的系统语音。

注意：与旧版系统语音相比，Siri 和增强语音的语速节奏、措辞和发音都自然得多。

测试与验证

运行自动化测试套件，验证配置加载、引擎回退、单次合成和顺序队列行为：

# Run unit tests
python3 tests/test_speak_server.py

# Or run via unittest discovery in the virtual environment
.venv/bin/python -m unittest discover tests