專案資訊

• 專案名稱：FlowSpeech MCP Server
• 專案簡介：把文字轉語音能力包裝成 Model Context Protocol（MCP）工具，讓支援 MCP 的 AI 用戶端能直接列出音色、產生單人旁白，或輸出雙人對話音訊。
• 目前狀態：v0.1.0，可透過 npm 執行；專案採 MIT License。
• 原始碼：GitHub - mcp-flowspeech-server
• 套件：npm - mcp-flowspeech-server
• 實際操作：AI 文字轉語音

為什麼做這個專案

一般文字轉語音流程常被拆成好幾步：先在網站貼上文案、挑選音色、下載檔案，再把結果搬回剪輯或自動化流程。當 AI 助理已經能整理逐字稿、改寫旁白與產生對話腳本時，最後的語音輸出仍然需要人工切換工具，會中斷工作流。

這個專案的目標不是再做一個網頁播放器，而是把語音生成變成 AI 可以明確呼叫的工具。MCP Server 負責描述參數、驗證輸入、呼叫語音服務，並把 Base64 音訊安全地寫入指定目錄。用戶端只需要理解工具介面，不需要知道後端回應格式。

架構與資料流

MCP Client
   │  tools/list、tools/call
   ▼
FlowSpeech MCP Server（Node.js + TypeScript）
   │  POST /api/ai/text-to-speech
   ▼
TTS Service
   │  mimeType + audioBase64
   ▼
本機音訊檔案（wav / mp3 / ogg / flac）

Server 使用 @modelcontextprotocol/sdk 的 Server 與 StdioServerTransport。這種設計適合桌面 AI 用戶端：程序由用戶端啟動，請求走標準輸入輸出，不需要額外開放本機 HTTP Port。

快速啟動

Node.js 18 以上可直接執行：

npx -y mcp-flowspeech-server

也可以加入支援 MCP 的用戶端設定：

{
  "mcpServers": {
    "flowspeech": {
      "command": "npx",
      "args": ["-y", "mcp-flowspeech-server"],
      "env": {
        "FLOWSPEECH_OUTPUT_DIR": "~/flowspeech-audio"
      }
    }
  }
}

FLOWSPEECH_OUTPUT_DIR 只決定生成檔案的儲存位置。範例沒有放入任何 API Key、Cookie 或 Session Token，公開文件也不應包含真實憑證。

三個 MCP 工具

flowspeech_list_voices

列出目前可用音色，並可用 male、female 或 all 篩選。先讓 AI 查詢音色，再依旁白情境選擇，比把音色名稱硬寫在 Prompt 裡更穩定。

flowspeech_tts

產生單一說話者音訊，必要參數只有 text，預設音色為 Kore。可另外提供 voice 與 output_path。

文字可包含情緒提示：

***(say cheerfully: 歡迎來到今天的節目！)***
接下來會用三分鐘說明這個專案的架構。

flowspeech_tts_multi

處理兩位說話者的對話，文字使用 Speaker1: 與 Speaker2: 前綴，再分別指定 voice_a、voice_b。這適合 Podcast 草稿、角色對話或教學情境模擬。

Speaker1: 今天要測試單人旁白與雙人對話。
Speaker2: 我會負責第二個角色，方便比較音色差異。

實作時遇到的三個問題

回應是 Base64，不是檔案 URL

語音 API 回傳 mimeType 與 audioBase64。MCP 工具不能只把很長的 Base64 字串丟回聊天視窗，否則會浪費 Context，也不方便後續播放。因此 Server 先解碼成 Buffer，再寫入本機檔案，最後只回傳檔案路徑、音色與格式。

副檔名不能固定寫成 wav

後端可能回傳 WAV、MP3、OGG 或 FLAC。實作會根據 mimeType 選擇副檔名，未知格式才退回 WAV。這避免內容格式與檔名不一致，導致播放器判斷錯誤。

輸出路徑需要可控但不能脆弱

使用者可指定 output_path；未指定時，系統使用時間戳記建立檔名，並儲存在 ~/.flowspeech-mcp/audio 或環境變數指定的資料夾。寫檔前會遞迴建立目錄，避免第一次執行就因資料夾不存在而失敗。

最小驗證清單

• tools/list 能看到三個工具與正確的 JSON Schema。
• 空白 text 會被拒絕，不會送出無效請求。
• 單人模式能使用預設音色並建立可播放檔案。
• 雙人模式能把兩個 speaker 對應到不同音色。
• API 錯誤會保留 HTTP 狀態與可讀訊息。
• MIME 類型與輸出副檔名一致。
• README、範例與提交紀錄不含任何真實憑證。

後續方向

接下來可以補強整合測試、串流輸出、更多輸出格式，以及讓用戶端在生成前先預估配額。更重要的是維持工具邊界：MCP Server 專注於可靠地把文字變成音訊，不把腳本改寫、內容審核與檔案發布全部塞進同一個工具。

這次實作最大的收穫是：把 AI 能力接進工作流時，真正重要的不只是模型效果，而是參數契約、錯誤處理、檔案生命週期與憑證邊界。當這些部分清楚，文字轉語音才會從一次性的 Demo 變成可重複使用的工程工具。