Tyrano Studio MCP

🚀 TyranoStudio MCP Server

A comprehensive MCP server that supports project management for TyranoStudio and game development with TyranoScript.

🚀 Quick Start

1. Install Dependencies

pip install mcp

2. Add Configuration to Claude Code

Add the following to ~/.claude/mcp_config.json:

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

3. Confirm Server Startup

python3 /Users/shunsuke/tyrano_studio_mcp_server.py

✨ Features

• 🎮 Project Management - Create, delete, and list project files.
• 📝 Scenario Editing - Read, write, and perform advanced syntax validation.
• 🎨 Resource Management - Add and list image and audio files.
• 🔍 Advanced Validation - Check label existence and resource references.
• 📊 Project Analysis - Provide statistics, estimate playtime, and visualize the flow.
• 🎭 Template Generation - Offer 5 types of scenario templates.
• 🔧 Git Integration - Support version control.
• ⚡ Optimization Tools - Detect unused resources and perform batch operations.

📦 Installation

The installation steps are included in the "Quick Start" section above.

📁 Target Directory Structure

/Users/shunsuke/TyranoStudio_mac_std_v603/
├── myprojects/          # Directory for storing game projects
│   └── [Project Name]/
│       └── data/
│           ├── scenario/    # Scenario files (.ks)
│           ├── fgimage/     # Foreground images (characters, etc.)
│           ├── bgimage/     # Background images
│           ├── bgm/         # BGM
│           ├── sound/       # Sound effects
│           ├── video/       # Videos
│           ├── image/       # Other images
│           ├── system/      # System files (Config.tjs, etc.)
│           └── others/      # Others
├── system_master/       # Templates
│   ├── tyranoscript_ja/ # Japanese templates
│   └── tyranoscript_en/ # English templates
├── export/              # Export destination
└── dlc/                 # Plugins

💻 Usage Examples

Create a New Game Project

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

Create a Simple Scenario

{
  "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]"
  }
}

Add a Character

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

Validate Scenario Syntax

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

📚 Documentation

1. Project Management

list_projects

• Description: Get a list of created projects.
• Parameters: None
• Example:

{}

create_project

• Description: Create a new project.
• Parameters:
  • project_name (required): Project name.
  • template (optional): Template type (tyranoscript_ja or tyranoscript_en).
• Example:

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

delete_project

• Description: Delete a project.
• Parameters:
  • project_name (required): Project name.
• Example:

{
  "project_name": "my_game"
}

list_project_files

• Description: List files and directories in a project.
• Parameters:
  • project_name (required): Project name.
  • path (optional): Relative path (root if omitted).
• Example:

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

2. Scenario File Operations

read_scenario

• Description: Read a scenario file (.ks).
• Parameters:
  • project_name (required): Project name.
  • scenario_file (required): Scenario file name.
• Example:

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

write_scenario

• Description: Write to a scenario file (.ks).
• Parameters:
  • project_name (required): Project name.
  • scenario_file (required): Scenario file name.
  • content (required): Content to write.
• Example:

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

validate_scenario

• Description: Check the syntax of a scenario file.
• Parameters:
  • project_name (required): Project name.
  • scenario_file (required): Scenario file name.
• Example:

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

3. Configuration File Operations

read_config

• Description: Read Config.tjs.
• Parameters:
  • project_name (required): Project name.
• Example:

{
  "project_name": "my_game"
}

write_config

• Description: Write to Config.tjs.
• Parameters:
  • project_name (required): Project name.
  • content (required): Content to write.
• Example:

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

4. Resource Management

add_image

• Description: Add an image to a project.
• Parameters:
  • project_name (required): Project name.
  • source_path (required): Path of the source image to copy.
  • dest_category (required): Destination category (fgimage, bgimage, image, system, etc.).
  • dest_filename (optional): Destination file name.
• Example:

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

5. TyranoScript Reference

get_tyranoscript_reference

• Description: Get the tag reference for TyranoScript.
• Parameters:
  • category (optional): Category (text, character, background, choice, variable, audio, all).
• Example:

{
  "category": "character"
}

TyranoScript Basic Tags

Text and Message Tags

• [l] - Wait for click.
• [p] - Wait for click and turn the page.
• [r] - New line.
• [cm] - Clear the message.

Character Tags

• [chara_new name="Character Name" storage="Image File"] - Define a character.
• [chara_show name="Character Name"] - Show a character.
• [chara_hide name="Character Name"] - Hide a character.
• [chara_mod name="Character Name" storage="Image File"] - Change the expression.

Background and Image Tags

• [bg storage="Image File"] - Change the background.
• [image layer="Layer Number" storage="Image File"] - Show an image.

Choice and Jump Tags

• [link target="Label Name"]Text[endlink] - Choice option.
• [glink target="Label Name" text="Choice Text"] - Graphical choice option.
• [jump target="Label Name"] - Jump.
• [s] - Stop.
• *Label Name - Define a label.

Audio Tags

• [playbgm storage="Music File"] - Play BGM.
• [playse storage="Sound Effect File"] - Play a sound effect.

📖 Reference Links

• TyranoScript Official Website
• Tag Reference
• TyranoBuilder (GUI Development Tool)

🎮 Launch TyranoStudio

open /Users/shunsuke/TyranoStudio_mac_std_v603/TyranoStudio.app

The created projects are saved in the myprojects/ directory and can be directly opened, previewed, and edited in TyranoStudio.

🧪 Testing

Run E2E Tests

python3.11 test_e2e.py

Test Content

• ✅ Project management (create, list, delete).
• ✅ Scenario file operations (read, write, validate).
• ✅ Template generation (5 types).
• ✅ Advanced validation (labels, resources).
• ✅ Audio file management.
• ✅ Resource reference validation.

CI/CD

Automatically run tests with GitHub Actions:

• E2E tests in a macOS environment.
• Automatically run for each push and PR.

🔧 Troubleshooting

Project Not Found

• Check the myprojects/ directory.
• Check for typos in the project name.

Image Not Displayed

• Check if the image file is placed in the appropriate directory.
• Check the case sensitivity of the file name (especially on macOS).

Scenario Syntax Error

• Validate with the validate_scenario tool.
• Check if the start/end tags correspond correctly.

📄 License

This MCP server supports the operation of TyranoStudio and follows the license of the TyranoScript/TyranoStudio itself.