shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

tyrano-studio-mcp

TyranoStudio MCP服务器提供全面的TyranoScript游戏开发支持，包括项目管理、场景编辑、资源管理和高级验证等功能。

article

README

🚀 TyranoStudio MCP 服务器

TyranoStudio（ティラノスタジオ）是一款用于项目管理和 TyranoScript 游戏开发的综合性 MCP 服务器，它能为开发者提供全面且高效的支持，助力游戏开发工作顺利开展。

Test Status Python License

✨ 主要特性

  • 🎮 项目管理：支持项目的创建、删除操作，还能查看项目文件列表。
  • 📝 场景编辑：可对场景文件进行读写操作，并具备高级语法验证功能。
  • 🎨 资源管理：能够添加和查看图像、音频等文件资源。
  • 🔍 高级验证：可确认标签是否存在，检查资源引用情况。
  • 📊 项目分析：提供项目统计信息，估算游戏播放时间，实现流程可视化。
  • 🎭 模板生成：提供 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 本体的许可证规定。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端