國語押韻工具 (Mandarin Rhyme Tool)

一個強大、可離線使用的國語（普通話）押韻查詢工具，專為創作者、作詞人與饒舌歌手設計。支援 CLI 命令列操作與 MCP (Model Context Protocol) 伺服器模式，可無縫整合至 AI 編輯器（如 Cursor、Trae、Claude Desktop）。

✨ 核心功能

• 全離線運作：內建精簡字典，亦可聯網下載完整字典，無須依賴 API。
• 多模式押韻：
  • 單押/雙押/多押：支援單字查詢，也支援多字詞彙的矩陣式押韻分析（Flow 創作神器）。
  • 嚴格/寬鬆模式：支援標準韻母、包含聲調的嚴格押韻，以及傳統戲曲的「十三轍」寬式押韻。
• 押韻檢測：自動比對兩段文字的押韻狀況，支援從句尾倒序檢查雙押、三押。
• MCP 支援：提供標準 MCP 協定介面，讓 AI 助手能直接調用本工具進行歌詞創作輔助。
• 常用字優化：搜尋結果優先顯示常用字，避免生僻字干擾創作靈感。

🚀 快速開始

環境需求

• Dart SDK (>= 3.10.0)

安裝與初始化

1. Clone 專案：

   git clone https://github.com/your-username/mandarin_rhyme_tool.git
   cd mandarin_rhyme_tool

2. 安裝依賴：

   dart pub get

3. 初始化字典（下載完整拼音資料）：

   dart run bin/mandarin_rhyme_tool.dart dict init

📖 CLI 使用說明

本工具提供多個子命令來滿足不同需求：

1. 查詢押韻 (Rhyme)

找出與輸入文字押韻的候選字。

# 查詢與「天」押韻的字
dart run bin/mandarin_rhyme_tool.dart rhyme --text "天"

# 查詢雙押/多押（輸入多字詞彙，如「火焰」）
# 將回傳每個位置的押韻候選矩陣
dart run bin/mandarin_rhyme_tool.dart rhyme --text "火焰"

參數：

• --tone：包含聲調（更嚴格，如：天(tian1) 只會匹配一聲的字）。
• --broad：寬式押韻（十三轍模式，如：eng/ong 通押）。
• --limit：限制回傳數量（預設 50）。

2. 檢測押韻 (Check)

檢查兩個詞彙是否押韻（支援雙押、多押檢測）。

# 檢查「世界」與「直接」是否押韻
dart run bin/mandarin_rhyme_tool.dart check --a "世界" --b "直接"

3. 查詢韻母 (Key)

查詢文字的韻母鍵值。

dart run bin/mandarin_rhyme_tool.dart key --text "測試"

🤖 MCP Server 整合

本工具實作了 Model Context Protocol (MCP)，可以作為 Server 供 AI 客戶端使用。

設定方式 (以 Trae/Cursor 為例)

在您的 MCP 設定檔（如 claude_desktop_config.json 或 Trae 的 MCP 設定）中加入：

{
  "mcpServers": {
    "mandarin-rhyme": {
      "command": "dart",
      "args": [
        "absolute/path/to/mandarin_rhyme_tool/bin/mandarin_rhyme_tool.dart",
        "mcp"
      ]
    }
  }
}

可用工具 (Tools)

啟用後，AI 助手將獲得以下能力：

• rhyme_key：分析韻母。
• rhyme_candidates：搜尋押韻字。
• rhyme_matrix：多字詞彙押韻矩陣分析（輔助雙押創作）。
• check_rhyme：押韻檢測。

授權

本專案採用 MIT License 授權，詳見 LICENSE 文件。