Metadata-Version: 2.4
Name: mcp-imrs-game-manager
Version: 0.1.0
Summary: MCP tool for generating IMRS dialogue games via SSE stream
Author-email: Your Name <your.email@example.com>
License: MIT License
        
        Copyright (c) 2026 MCP IMRS Game Manager Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/yourusername/MCPTools
Project-URL: Repository, https://github.com/yourusername/MCPTools
Project-URL: Issues, https://github.com/yourusername/MCPTools/issues
Keywords: mcp,imrs,game,dialogue,ai,education
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.25.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# MCP IMRS Game Manager

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

## 功能特色

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

## 安裝方式

### 從 PyPI 安裝

```bash
pip install mcp-imrs-game-manager
```

### 從原始碼安裝

```bash
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` 或自訂位置）：

```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` 範例檔案，你可以參考此檔案進行配置：

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

## 使用方式

### 在 MCP 客戶端中使用

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

### 基本範例

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

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

```python
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（不指定則使用環境變數） |

## 開發指南

### 本地開發

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

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

# 執行測試（如果有）
pytest
```

### 建立發布套件

```bash
# 安裝建構工具
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](LICENSE) 檔案

## 問題回報

如有任何問題或建議，請至 [GitHub Issues](https://github.com/yourusername/MCPTools/issues) 回報。

## 更新紀錄

### v0.1.0 (2026-01-14)

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