Tyrano Studio MCP

🚀 TyranoStudio MCP 服務器

TyranoStudio（ティラノスタジオ）是一款用於項目管理和 TyranoScript 遊戲開發的綜合性 MCP 服務器，它能為開發者提供全面且高效的支持，助力遊戲開發工作順利開展。

✨ 主要特性

• 🎮 項目管理：支持項目的創建、刪除操作，還能查看項目文件列表。
• 📝 場景編輯：可對場景文件進行讀寫操作，並具備高級語法驗證功能。
• 🎨 資源管理：能夠添加和查看圖像、音頻等文件資源。
• 🔍 高級驗證：可確認標籤是否存在，檢查資源引用情況。
• 📊 項目分析：提供項目統計信息，估算遊戲播放時間，實現流程可視化。
• 🎭 模板生成：提供 5 種不同的場景模板。
• 🔧 Git 集成：支持版本管理功能。
• ⚡ 優化工具：可檢測未使用的資源，並支持批量操作。

📦 安裝指南

1. 安裝依賴包

pip install mcp

2. 在 Claude Code 中添加配置

在 ~/.claude/mcp_config.json 文件中添加以下內容：

{
  "mcpServers": {
    "tyrano-studio": {
      "command": "python3",
      "args": ["/Users/shunsuke/tyrano_studio_mcp_server.py"],
      "description": "TyranoStudio project management"
    }
  }
}

3. 確認服務器啟動

python3 /Users/shunsuke/tyrano_studio_mcp_server.py

💻 使用示例

基礎用法

創建新的遊戲項目

{
  "tool": "create_project",
  "arguments": {
    "project_name": "my_visual_novel",
    "template": "tyranoscript_ja"
  }
}

創建簡單的場景

{
  "tool": "write_scenario",
  "arguments": {
    "project_name": "my_visual_novel",
    "scenario_file": "scene1.ks",
    "content": "*start\n\n[bg storage=\"room.jpg\"]\n\nこんにちは、世界！[p]\n\nこれはTyranoScriptで作られたゲームです。[p]\n\n[s]"
  }
}

添加角色

{
  "tool": "add_image",
  "arguments": {
    "project_name": "my_visual_novel",
    "source_path": "/path/to/character.png",
    "dest_category": "fgimage"
  }
}

檢查場景語法

{
  "tool": "validate_scenario",
  "arguments": {
    "project_name": "my_visual_novel",
    "scenario_file": "scene1.ks"
  }
}

📚 詳細文檔

目標目錄結構

/Users/shunsuke/TyranoStudio_mac_std_v603/
├── myprojects/          # 遊戲項目存儲目錄
│   └── [項目名稱]/
│       └── data/
│           ├── scenario/    # 場景文件(.ks)
│           ├── fgimage/     # 前景圖像（角色等）
│           ├── bgimage/     # 背景圖像
│           ├── bgm/         # BGM
│           ├── sound/       # 音效
│           ├── video/       # 視頻
│           ├── image/       # 其他圖像
│           ├── system/      # 系統文件(Config.tjs等)
│           └── others/      # 其他
├── system_master/       # 模板
│   ├── tyranoscript_ja/ # 日語模板
│   └── tyranoscript_en/ # 英語模板
├── export/              # 導出目標
└── dlc/                 # 插件

功能（工具列表）

1. 項目管理

list_projects

• 說明：獲取已創建項目的列表。
• 參數：無。
• 示例：

{}

create_project

• 說明：創建新的項目。
• 參數：
  • project_name（必需）：項目名稱。
  • template（可選）：模板類型 (tyranoscript_ja 或 tyranoscript_en)。
• 示例：

{
  "project_name": "my_game",
  "template": "tyranoscript_ja"
}

delete_project

• 說明：刪除項目。
• 參數：
  • project_name（必需）：項目名稱。
• 示例：

{
  "project_name": "my_game"
}

list_project_files

• 說明：列出項目內的文件和目錄。
• 參數：
  • project_name（必需）：項目名稱。
  • path（可選）：相對路徑（省略時為根目錄）。
• 示例：

{
  "project_name": "my_game",
  "path": "data/scenario"
}

2. 場景文件操作

read_scenario

• 說明：讀取場景文件 (.ks)。
• 參數：
  • project_name（必需）：項目名稱。
  • scenario_file（必需）：場景文件名。
• 示例：

{
  "project_name": "my_game",
  "scenario_file": "scene1.ks"
}

write_scenario

• 說明：寫入場景文件 (.ks)。
• 參數：
  • project_name（必需）：項目名稱。
  • scenario_file（必需）：場景文件名。
  • content（必需）：寫入的內容。
• 示例：

{
  "project_name": "my_game",
  "scenario_file": "scene1.ks",
  "content": "[bg storage=\"room.jpg\"]\nこんにちは[p]"
}

validate_scenario

• 說明：檢查場景文件的語法。
• 參數：
  • project_name（必需）：項目名稱。
  • scenario_file（必需）：場景文件名。
• 示例：

{
  "project_name": "my_game",
  "scenario_file": "scene1.ks"
}

3. 配置文件操作

read_config

• 說明：讀取 Config.tjs 文件。
• 參數：
  • project_name（必需）：項目名稱。
• 示例：

{
  "project_name": "my_game"
}

write_config

• 說明：寫入 Config.tjs 文件。
• 參數：
  • project_name（必需）：項目名稱。
  • content（必需）：寫入的內容。
• 示例：

{
  "project_name": "my_game",
  "content": "..."
}

4. 資源管理

add_image

• 說明：向項目中添加圖像。
• 參數：
  • project_name（必需）：項目名稱。
  • source_path（必需）：源圖像路徑。
  • dest_category（必需）：目標類別（fgimage, bgimage, image, system 等）。
  • dest_filename（可選）：目標文件名。
• 示例：

{
  "project_name": "my_game",
  "source_path": "/Users/shunsuke/Downloads/character.png",
  "dest_category": "fgimage",
  "dest_filename": "hero.png"
}

5. TyranoScript 參考

get_tyranoscript_reference

• 說明：獲取 TyranoScript 的標籤參考。
• 參數：
  • category（可選）：類別（text, character, background, choice, variable, audio, all）。
• 示例：

{
  "category": "character"
}

TyranoScript 基本標籤

文本・消息類

• [l] - 等待點擊
• [p] - 等待點擊並翻頁
• [r] - 換行
• [cm] - 清除消息

角色類

• [chara_new name="角色名" storage="圖像文件"] - 定義角色
• [chara_show name="角色名"] - 顯示角色
• [chara_hide name="角色名"] - 隱藏角色
• [chara_mod name="角色名" storage="圖像文件"] - 更改表情

背景・圖像類

• [bg storage="圖像文件"] - 更改背景
• [image layer="圖層編號" storage="圖像文件"] - 顯示圖像

選項・跳轉類

• [link target="標籤名"]文本[endlink] - 選項
• [glink target="標籤名" text="選項文本"] - 圖形化選項
• [jump target="標籤名"] - 跳轉
• [s] - 停止
• *標籤名 - 定義標籤

音頻類

• [playbgm storage="音樂文件"] - 播放 BGM
• [playse storage="音效文件"] - 播放音效

參考鏈接

• TyranoScript 官方網站
• 標籤參考
• TyranoBuilder（GUI 開發工具）

啟動 TyranoStudio

open /Users/shunsuke/TyranoStudio_mac_std_v603/TyranoStudio.app

創建的項目將保存在 myprojects/ 目錄中，可直接在 TyranoStudio 中打開進行預覽和編輯。

測試

執行端到端測試

python3.11 test_e2e.py

測試內容

• ✅ 項目管理（創建、列表、刪除）
• ✅ 場景文件操作（讀寫、驗證）
• ✅ 模板生成（5 種）
• ✅ 高級驗證（標籤、資源）
• ✅ 音頻文件管理
• ✅ 資源引用驗證

CI/CD

通過 GitHub Actions 自動執行測試：

• 在 macOS 環境中進行端到端測試
• 每次推送和 PR 時自動執行

故障排除

項目未找到

• 檢查 myprojects/ 目錄。
• 確認項目名稱是否拼寫錯誤。

圖像未顯示

• 檢查圖像文件是否位於正確的目錄中。
• 確認文件名的大小寫（特別是在 macOS 上）。

場景語法錯誤

• 使用 validate_scenario 工具進行驗證。
• 確認標籤的開始和結束是否正確對應。

📄 許可證

此 MCP 服務器用於支持 TyranoStudio 的操作，遵循 TyranoScript/TyranoStudio 本體的許可證規定。