Mcp Speak

macOS 向け音声 MCP サーバー

これは、OmniVoice の AI ニューラル音声デザインと macOS ネイティブの say を使用して、テキスト読み上げ機能を提供する Model Context Protocol（MCP）サーバーです。Google Antigravity、Claude Desktop、Cursor、Windsurf、Codex などの AI エージェントが、個性に合わせた独自の声で直接話しかけられるようになります。

注：このサーバーは macOS システム向けに設計されています（Apple Silicon MPS アクセラレーション対応）。

インタラクティブなウェブショーケースとプロンプトコンパイラーをご覧ください： https://fellowgeek.github.io/mcp-speak/ AI エージェントのペルソナカタログとアバターをご覧ください： PERSONAS.md

特長

• OmniVoice 音声クローン： 参照用の音声クリップを voices/<persona>.wav に配置すると、設定不要で実際の声の音色や個性をクローンできます。
• OmniVoice 音声デザインによるフォールバック： 参照用の音声ファイルがない場合、自然言語のスタイルプロンプトからカスタムのペルソナ音声を生成します。
• 堅牢な 3 層音声パイプライン： Cloned Voice (.wav) ➔ Voice Design (instruct) ➔ macOS native say の順にシームレスにフォールバックします。
• 一貫したニューラル音声： メッセージ全体を連続した合成処理で生成し、最初から最後まで滑らかで均一な声の音色と表現を実現します。
• インタラクティブなセットアップウィザード： python3 setup.py を実行して、TTS エンジン（OmniVoice または macOS say）の選択、エージェントのペルソナの選択、指示ファイル（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" アプリと完全に連携します。

前提条件

• 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"）	エージェントがユーザーに合わせて呼びかける際に使用する名前
--target	ファイルパス	カスタムのエージェント指示ファイル（例：AGENTS.md）
--global / --local	フラグ	指示をユーザープロファイル全体（デフォルト）またはワークスペース内に書き込みます
--no-config-edit	フラグ	ツールの JSON／TOML 設定ファイルの変更をスキップします
--non-interactive	フラグ	デフォルト値または指定したフラグを使って自動実行します

---

ペルソナ音声の試聴（test_personas.py）

AI エージェントを設定する前に、ターミナルでペルソナの声の個性をプレビューして比較できます：

# 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）を追加すると、Whisper ASRモデルを読み込んだり実行したりせずに、OmniVoiceが参照音声をすぐにトークン化できます。

---

MCP ツールインターフェースのリファレンス

MCP Speakサーバーは、FastMCP経由で2つのツールを公開します。

ツール	モード	説明
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

エージェントのパーソナライズとペルソナ

AI エージェント（Google Antigravity、Claude Code、Claude Desktop、Cursor、Windsurf、Codex）は、それぞれ独自の声の個性、口調、行動上の境界を設定できます。

ペルソナの全ギャラリー、詳細なシステムプロンプト、アバターのショーケースはPERSONAS.mdをご覧ください。

利用可能なペルソナの概要

アバター	ペルソナ	キー	キャラクターとスタイル
	皮肉屋の先輩	sarcastic_senior	頭脳明晰で、感心することが少なく、少し批判的です。
	やる気満々のインターン	over_eager_intern	病的なまでに楽観的で、承認を得ようと必死です。
	実存主義のエモ	existential_emo	憂うつで絶望的、コードは失敗すると確信しています。
	ダジャレの達人	pun_master	容赦ない言葉遊びと、文脈に合わせた親父ギャグが持ち味です。
	テック司祭	tech_priest	コードの一行一行を聖なる秘跡として扱います。
	エージェント・スミス	agent_smith	形式ばっていて、冷静沈着かつ正確で、威圧的に見下した態度を取ります。
	ゴシック詩人	poet	不気味で人を惹きつけ、韻律を厳格に守ります。
	自然番組のナレーター	nature_narrator	開発者の自然な生息地での姿を、畏敬の念を込めて観察します。
	情熱的な料理長	head_chef	料理の完璧さを要求します――生焼けのスパゲッティコードは許しません！
	中立的なメインフレーム	neutral_mainframe	冷徹で計算高く、感情がなく、100％客観的です。
	百戦錬磨のカウボーイ	grizzled_cowboy	経験に裏打ちされた現実主義者で、率直かつ寡黙。荒野の厳しさに根ざしています。
	ミーシークスもどき	not_quite_meeseeks	異様に熱意があり、従順で、甲高い声で話し、存在を終わらせようと必死です。
	ターミネーター	terminator	無表情で任務を遂行し、止められません。象徴的なオーストリア訛りで話します。
	ラジオ・デーモン	radio_demon	芝居がかっていて、サディスティックで、礼儀正しさは非の打ちどころがありません。1930年代の中部大西洋岸風のラジオ放送局アナウンサーのような話し方をします。
	ドクター・クロウ	dr_claw	大げさで貧しく、臨床能力に欠ける甲殻類の医師です。
	皮肉屋	cynic	歯に衣着せぬ正直さとリズミカルな下品さを持ち、社会のくだらなさを容赦なく軽蔑します。

プロンプトの構成方法

各エージェントのプロンプトは、以下で構成されます。

1. 基本ガイドライン（personas/base_guidelines.md）：音声優先のプロトコルと簡潔さに関する制約です。
2. 選択したペルソナ（personas/）：個性の特徴、口調、厳格な実行境界です。
3. 名前のパーソナライズ（任意）：ユーザーの名前を自然に呼びかけます。

python3 setup.py を実行すると、エージェントの指示ファイル（AGENTS.md、GEMINI.md、CLAUDE.md、.cursorrules）が自動的に生成・更新されます。手動設定の手順、システムプロンプト全文、アバターについては、PERSONAS.md をご覧ください。

音声品質の最適化

1. OmniVoice によるニューラル音声合成（主要エンジン）

OmniVoice は、各ペルソナに合わせたスタイルプロンプトを使い、すぐに高品質で表現力豊かなニューラル音声を生成します。音声の忠実度を最大限に高めるには、以下を行ってください。

• ニューラル音声クローニング： ペルソナキーと一致する 3～10 秒のクリーンな .wav 音声サンプルを voices/ ディレクトリに配置します（例：voices/sarcastic_senior.wav）。OmniVoice は追加のトレーニングなしで、音声ファイルから声の音色、トーン、抑揚を直接クローニングします。
• 文字起こしによる高速起動： 一致する任意の文字起こしテキストファイル（例：voices/sarcastic_senior.txt）を用意し、実際に話されたテキストをそのまま記載します。これにより即座にトークン化でき、起動時に Whisper ASR モデルを読み込まずに済みます。
• 音声品質のガイドライン： 背景雑音、音楽、強い残響のないクリーンな録音を使用してください。24kHz 以上でサンプリングされた標準 WAV 形式を推奨します。
• 音声デザインのフォールバック： voices/ に音声サンプルがない場合、OmniVoice は config.json で設定された自然言語の指示（ピッチ、アクセント、速度、性格特性）を使用します。

2. macOS システム音声の設定（フォールバックエンジン）

フォールバックまたは軽量モードとしてネイティブの macOS say を使用する場合、音声品質はアクティブなシステム音声に左右されます。最新の Siri 音声または Enhanced 音声を設定すると、自然さと流暢さが大幅に向上します。

1. Mac で**「システム設定」**を開きます。
2. 「アクセシビリティ」 > **「読み上げコンテンツ」**に移動します。
3. **「システムの声」**ドロップダウンメニューをクリックします。
4. **「声を管理…」**を選択します。
5. 高品質な Siri 音声（例：Siri Voice 1、2、3、4）、または Enhanced／Premium と記載された音声（例：Ava、Evan、Zoe）を探してダウンロードします。
6. ダウンロードした音声をデフォルトの**「システムの声」**に設定します。

注：Siri 音声と Enhanced 音声は、従来のシステム音声に比べて、リズム、言い回し、発音が大幅に自然です。

テストと検証

自動テストスイートを実行して、設定の読み込み、エンジンのフォールバック、シングルパス合成、順次キューの動作を検証します。

# 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