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 本体的许可证规定。