JinDaGe - tyrano-studio-mcp MCP Details

article

README

🚀 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="音效文件"] - 播放音效

参考链接

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