MCP IMRS Game Manager

一個用於生成 IMRS 對話遊戲的 MCP (Model Context Protocol) 工具，支援 SSE 串流回傳即時進度。

功能特色

• 🎮 對話遊戲生成：透過 AI 快速生成互動式對話遊戲
• 📡 SSE 串流：即時回傳生成進度，避免 timeout 問題
• 🎨 多種題型：支援單選、多選、劇情選擇、問答、文本閱讀等題型
• 🖼️ 圖片生成：可選擇性生成題目配圖
• 🔧 彈性配置：透過環境變數輕鬆配置 API

安裝方式

從 PyPI 安裝

pip install mcp-imrs-game-manager

從原始碼安裝

git clone https://github.com/yourusername/MCPTools.git
cd MCPTools/mcp-imrs-game-manager
pip install -e .

配置方式

1. 準備配置檔案

建立或編輯你的 MCP 配置檔案（例如：~/.config/claude/claude_desktop_config.json 或自訂位置）：

{
  "mcpServers": {
    "imrs-game-manager": {
      "command": "mcp-imrs-game-manager",
      "env": {
        "IMRS_API_BASE_URL": "https://your-api-domain.com/api/botrun",
        "IMRS_API_KEY": "your-api-key-here",
        "IMRS_AVATAR_ID": "avatar_1764303977799_60ff"
      }
    }
  }
}

2. 環境變數說明

• IMRS_API_BASE_URL（必填）：IMRS API 的基礎網址
• IMRS_API_KEY（必填）：API 金鑰
• IMRS_AVATAR_ID（選填）：預設頭像 ID，若不設定將使用預設值

3. 配置檔案範例

專案中提供了 mcp.json.example 範例檔案，你可以參考此檔案進行配置：

cp mcp.json.example mcp.json
# 編輯 mcp.json，填入你的 API 資訊

使用方式

在 MCP 客戶端中使用

安裝並配置完成後，在支援 MCP 的客戶端（如 Claude Desktop）中即可使用 generate_dialogue_game 工具。

基本範例

# 在 MCP 客戶端中呼叫
generate_dialogue_game(
    question_types='["單選", "劇情選擇"]',
    count=3,
    content="長髮公主的故事"
)

進階範例（包含圖片生成）

generate_dialogue_game(
    question_types='["單選", "多選", "文本閱讀"]',
    count=5,
    content="太陽系行星探索",
    generate_question_images=True,
    question_image_ratio=0.7,
    avatar_id="custom_avatar_id"
)

支援的題型

題型 ID	表情符號	說明	選項限制
單選	📋	基礎知識測驗	最多 3 個選項
多選	☑️	進階理解測驗	不超過 6 個選項
劇情選擇	🎭	劇情發展選擇	必須 2 個選項
問答	💬	開放式問答	AI 評分
文本閱讀	📄	文本展示或閱讀理解	-

建議題型組合

• 入門學習：["文本閱讀", "單選", "劇情選擇"]
• 知識測驗：["單選", "多選"]
• 故事互動：["劇情選擇", "文本閱讀"]
• 混合型（推薦）：["劇情選擇", "單選", "文本閱讀"]

API 參數說明

generate_dialogue_game

參數	類型	必填	預設值	說明
question_types	str	✅	-	題型列表（JSON 字串格式）
count	int	✅	-	題目數量
content	str	✅	-	遊戲內容描述
generate_question_images	bool	❌	False	是否生成題目圖片
question_image_ratio	float	❌	0.5	圖片比例 (0.0-1.0)
avatar_id	str	❌	None	頭像 ID（不指定則使用環境變數）

開發指南

本地開發

# 複製專案
git clone https://github.com/yourusername/MCPTools.git
cd MCPTools/mcp-imrs-game-manager

# 安裝開發依賴
pip install -e ".[dev]"

# 執行測試（如果有）
pytest

建立發布套件

# 安裝建構工具
pip install build twine

# 建構套件
python -m build

# 檢查套件
twine check dist/*

# 上傳到 TestPyPI（測試）
twine upload --repository testpypi dist/*

# 上傳到 PyPI（正式發布）
twine upload dist/*

專案架構

mcp-imrs-game-manager/
├── src/
│   └── mcp_imrs_game_manager/
│       ├── __init__.py          # 套件初始化
│       ├── __main__.py          # 執行進入點
│       ├── server.py            # MCP 伺服器主程式
│       ├── utils.py             # 工具函數
│       └── sse_handler.py       # SSE 串流處理
├── pyproject.toml               # 專案配置
├── README.md                    # 說明文件
├── LICENSE                      # 授權條款
├── mcp.json.example             # 配置範例
└── CONFIG.md                    # 詳細配置說明

授權條款

MIT License - 詳見 LICENSE 檔案

問題回報

如有任何問題或建議，請至 GitHub Issues 回報。

更新紀錄

v0.1.0 (2026-01-14)

• 初始版本發布
• 支援基本對話遊戲生成
• SSE 串流即時進度回報
• 支援 5 種題型
• 可選擇性圖片生成