openwebgal-mcp-server

floatDreamWithSong/openwebgal-mcp-server

3.2

If you are the rightful owner of openwebgal-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

OpenWebGAL Assistant is a Model Context Protocol (MCP) Server designed to assist developers in creating games using the OpenWebGAL framework.

Tools

  1. WebGAL Encyclopedia

    Provides quick answers to WebGAL-related questions by referencing official documentation.

  2. Game Asset Manager

    Helps in organizing and listing game assets like Live2D models and background images.

  3. Script Assistant

    Assists in listing, creating, and modifying game script files.

  4. Script Conversion

    Converts narrative text into WebGAL game scripts, integrating assets and dialogues.

OpenWebGAL Assistant

这是一个为 OpenWebGAL 游戏开发者设计的 Assistant（MCP Server）。它的核心目标是利用大型语言模型（LLM）的能力，将您从繁琐、重复的游戏开发工作中解放出来，让您可以更专注于核心的故事与创意。

您可以把这个项目理解为一个赋予了 AI "超能力"的、专门研究 WebGAL 的开发助理，让 AI 帮您完成许多工作，例如：

  • "帮我查一下 WebGAL 的动画指令怎么写？"
  • "我的游戏里有哪些背景图片？"
  • "帮我把第一章的剧本最后加一段祥子的独白。"
  • "帮我把剧本/小说.txt直接转化为Webgal游戏脚本吧！资产我都准备好了您自己看嘞"

无论您是经验丰富的开发者，还是刚刚接触 WebGAL 的新手，AI 助手都能为您提供帮助，成为您游戏开发中最得力的伙伴。

1. 这是为了解决什么问题？

在传统的游戏开发流程中，创作者常常需要处理大量非创造性的工作，例如：

  • 查阅文档：忘记某个指令或功能时，需要在冗长的文档中反复查找。
  • 管理资源：手动整理、核对成百上千的图片、音乐、语音等素材文件。
  • 编写脚本：在剧本文件中反复修改、增删、调整对话和情节。
  • 制作配音：为每一句对话手动录制、剪辑、并整合到游戏中，如果涉及多语言则工作量翻倍。

本项目旨在解决以上痛点，将这些任务交给 AI 自动处理，其核心优势在于：

  • 自动化：自动扫描和管理游戏资源、自动为对话生成语音。
  • 智能化：能理解您的意图，直接修改游戏代码、提供文档查询。
  • 高效率：利用并行处理等技术，大幅缩短翻译和语音合成等耗时任务的时间。

最终，让您回归创作本身。

2. 如何开始：初始化与配置

开始使用前，您需要进行简单的初始化和配置。

首次初始化

首先，请打开一个终端或命令行工具（如 PowerShell 或 Cmd），然后执行以下命令：

npx openwebgal-mcp-server init -webgal <你的游戏目录>

命令解释：

  • npx：一个方便的工具，可以临时下载并运行这个 AI 助手程序，无需在您的电脑上永久安装。
  • init: 表示要执行"初始化"操作。
  • -webgal <你的游戏目录>: 这是最重要的参数，您需要将 <你的游戏目录> 替换成您本地 WebGAL 游戏的根目录路径。例如：D:/Webgal_Terre/public/games/新的游戏/game。

执行该命令后，程序会在您 当前所在的目录 下创建两个核心配置文件：

  1. .env: 用于配置基础环境，主要是游戏资源目录。
  2. voice.config.json: 用于配置所有与 翻译 和 语音合成 相关的功能。

配置项详解

基础配置 (.env 文件)

这个文件告诉 AI 助手去哪里寻找您的游戏资源。通常您不需要修改它，使用默认配置即可。

# 资源扫描的目录（相对于您的游戏目录）
WEBGAL_BACKGROUND_DIR=background
WEBGAL_VOCAL_DIR=vocal
WEBGAL_BGM_DIR=bgm
WEBGAL_ANIMATION_DIR=animation
WEBGAL_VIDEO_DIR=video
WEBGAL_FIGURE_DIR=figure

# 最大翻译任务并发数
MAX_TRANSLATOR=3
  • WEBGAL_..._DIR: 指定了不同类型资源（背景、语音、音乐等）所在的文件夹名称。
  • MAX_TRANSLATOR: 在执行翻译和语音合成时，可以同时进行多少个翻译任务。提高此数值可以加快多角色、多语言翻译的速度，但也会增加电脑性能消耗。对于大型语言模型API服务（如OpenAI、Anthropic等），较高的并发数可以显著提升效率；但如果使用的是本地部署的Ollama服务，过高的并发可能会导致性能下降，因为本地模型的推理能力有限，建议根据您的硬件配置调整此值。
语音与翻译配置 (voice.config.json 文件)

这是最核心的配置文件，控制着所有AI翻译和语音功能。下面是两个个完整的配置示例和参数说明。

示例1：本地ollama服务 voice.config.json:

{
  "volume": 30,
  "gpt_sovits_url": "http://localhost:9872",
  "gpt_sovits_path": "D:\\AIVoice\\GPT-SoVITS-v2pro-20250604",
  "model_version": "v2",
  "translate": {
    "model_type": "ollama",
    "base_url": "http://localhost:11434/api",
    "model_name": "glm4:9b",
    "enabled": true,
    "context_size": 2,
    "additional_prompt":"人名信息：睦，全名若叶（わかば）睦（むつみ）。学生"
  },
  "characters": [
    {
      "character_name": "Sakiko",
      "gpt": "GPT_weights_v2ProPlus\\Mujica_豊川祥子_白_v2pp.ckpt",
      "sovits": "SoVITS_weights_v2ProPlus\\Mujica_豊川祥子_白_v2pp.pth",
      "ref_audio": "D:\\AIVoice\\语音模型\\GPT-SoVITS v2 pro plus\\Mujica\\丰川祥子（白祥）\\(A)あなたと空を見上げるのは、いつも夏でしたわね.wav",
      "ref_text": "あなたと空を見上げるのは、いつも夏でしたわね",
      "prompt": "说日语喜欢说类似'德斯哇'的大小姐语气，喜欢亲切地叫若叶睦为睦。",
      "translate_to": "日文",
      "inferrence_config": {
        "prompt_language": "日文",
        "text_language": "日文",
        "how_to_cut": "凑四句一切",
        "top_k": 15,
        "top_p": 1.0,
        "temperature": 1.0,
        "speed": 1.0,
        "sample_steps": 8,
        "if_sr": false,
        "pause_second": 0.3
      }
    },{
      "character_name": "Uika",
      "gpt": "GPT_weights_v2ProPlus\\Mujica_三角初華_v2pp.ckpt",
      "sovits": "SoVITS_weights_v2ProPlus\\Mujica_三角初華_v2pp.pth",
      "ref_audio": "D:\\AIVoice\\语音模型\\GPT-SoVITS v2 pro plus\\Mujica\\三角初华\\(A)まなちゃんソロの仕事も始まって、大変なときなのに.wav",
      "ref_text": "まなちゃんソロの仕事も始まって、大変なときなのに",
      "translate_to": "日文",
      "inferrence_config": {
        "prompt_language": "日文",
        "text_language": "日文",
        "how_to_cut": "凑四句一切",
        "top_k": 15,
        "top_p": 1.0,
        "temperature": 1.0,
        "speed": 0.9,
        "sample_steps": 8,
        "if_sr": false,
        "pause_second": 0.3
      }
    }
  ]
}

示例2：外部API服务（这里是阿里云百炼平台的qwen测试） voice.config.json:

{
  "volume": 30,
  "gpt_sovits_url": "http://localhost:9872",
  "gpt_sovits_path": "D:\\AIVoice\\GPT-SoVITS-v2pro-20250604",
  "model_version": "v2",
  "translate": {
    "model_type": "openai",
    "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "model_name": "qwen-turbo-latest",
    "api_key": "sk-xxxxxxxxxxxxxxxxxx",
    "enabled": true,
    "context_size": 2,
    "additional_prompt":"人名信息：睦，即：むつみ。"
  },
  "characters": [
    {
      "character_name": "Sakiko",
      "gpt": "GPT_weights_v2ProPlus\\Mujica_豊川祥子_白_v2pp.ckpt",
      "sovits": "SoVITS_weights_v2ProPlus\\Mujica_豊川祥子_白_v2pp.pth",
      "ref_audio": "D:\\AIVoice\\语音模型\\GPT-SoVITS v2 pro plus\\Mujica\\丰川祥子（白祥）\\(A)あなたと空を見上げるのは、いつも夏でしたわね.wav",
      "ref_text": "あなたと空を見上げるのは、いつも夏でしたわね",
      "prompt": "说日语喜欢说类似'德斯哇'的大小姐语气",
      "translate_to": "日文",
      "inferrence_config": {
        "prompt_language": "日文",
        "text_language": "日文",
        "how_to_cut": "凑四句一切",
        "top_k": 15,
        "top_p": 1.0,
        "temperature": 1.0,
        "speed": 1.0,
        "sample_steps": 8,
        "if_sr": false,
        "pause_second": 0.3
      }
    },{
      "character_name": "Uika",
      "gpt": "GPT_weights_v2ProPlus\\Mujica_三角初華_v2pp.ckpt",
      "sovits": "SoVITS_weights_v2ProPlus\\Mujica_三角初華_v2pp.pth",
      "ref_audio": "D:\\AIVoice\\语音模型\\GPT-SoVITS v2 pro plus\\Mujica\\三角初华\\(A)まなちゃんソロの仕事も始まって、大変なときなのに.wav",
      "ref_text": "まなちゃんソロの仕事も始まって、大変なときなのに",
      "translate_to": "日文",
      "inferrence_config": {
        "prompt_language": "日文",
        "text_language": "日文",
        "how_to_cut": "凑四句一切",
        "top_k": 15,
        "top_p": 1.0,
        "temperature": 1.0,
        "speed": 0.9,
        "sample_steps": 8,
        "if_sr": false,
        "pause_second": 0.3
      }
    }
  ]
}

参数说明:

详细配置和意义请自行查看GPT-SOVITS项目的tts服务介绍

  • 全局配置:

    • gpt_sovits_url: 您的 GPT-SoVITS 服务运行的地址。
    • gpt_sovits_path: 您本地 GPT-SoVITS 项目的完整路径。模型文件路径将基于此路径计算。
    • volume: 生成语音的默认音量。
    • model_version: GPT-SoVITS 使用的模型版本，一般就 (v2)。

  • 翻译配置 (translate 部分):

    • enabled: 是否启用翻译功能。如果为 true，则会在语音合成前先进行翻译。
    • model_type: 您使用的翻译模型服务商。支持 ollama, openai, anthropic, google, mistral, cohere, custom (用于其他兼容OpenAI API的服务)。
    • base_url: 翻译服务的 API 地址。
    • api_key: (可选) 访问翻译服务所需的 API 密钥。对于本地 ollama 服务则无需填写。
    • model_name: 您要使用的具体模型名称，例如 gpt-4o-mini 或 gemma:2b。
    • context_size: 为了让翻译更准确，AI 会自动读取前后文。此参数定义读取几句对话作为上下文，推荐 1-4。
    • additional_prompt: 全局的翻译提示信息。您可以在这里提供人名、地名对照表等，以提高翻译准确性。

  • 角色配置 (characters 数组):

    • 您可以为游戏里的每个角色（或每个需要不同语音/语言的角色）添加一个配置对象。
    • character_name: 角色名，必须与游戏脚本中的角色名(角色名: 对话内容 ...)完全一致。
    • gpt / sovits: 角色使用的 GPT 和 SoVITS 模型文件路径（模型权重）。这是相对于 gpt_sovits_path 的相对路径。
    • ref_audio / ref_text: 参考音频的路径和文本。
    • prompt: 对这个角色说话风格、语气的描述，引导 AI 合成出更具个性的语音。
    • translate_to: 指定这个角色的对话需要被翻译成哪种语言。
    • inferrence_config: (可选) 更详细的 GPT-SoVITS 推理参数。

3. AI 助手的核心能力 (MCP)

配置完成后，AI 助手就具备了多种能力。您可以通过兼容 MCP 协议的客户端（如配置好的聊天机器人）来使用这些能力。

📚 能力一：WebGAL 万事通

遇到 WebGAL 的问题却不想翻阅长篇的文档？直接问 AI 吧！AI 熟读了所有 WebGAL 的官方文档，能为您快速、准确地解答问题。

  • 您可以问："WebGAL 如何显示一张背景图？"
  • AI 会：找到并展示 bg-and-figure.md 文档中关于背景图指令的内容。

🎨 能力二：游戏资源管家

管理成百上千的游戏素材是一件麻烦事。现在，您可以让 AI 来帮您清点和管理。

  • 您可以说："帮我看看游戏里都有哪些角色的 Live2D 模型。"
  • AI 会：扫描您在 .env 中配置的 figure 目录，并列出所有找到的浅层的 Live2D 模型文件（.json）和普通角色图片目录。
  • 您还可以问："祥子这个模型有哪些表情和动作？"
  • AI 会：列出该 Live2D 模型包含的所有表情（.exp.json 文件）和动作（.mtn 文件），方便您在剧情中精确调用。

✍️ 能力三：剧本助理

写游戏剧本不只是打字，更需要不断地修改和调整。AI 不仅能陪您讨论剧情，还能直接上手帮您修改剧本文件。

  • 您可以说："帮我列出所有的剧本文件。"
  • AI 会：扫描 scene 目录并展示所有 .txt 剧本文件。
  • 您可以说："帮我创建一个新剧本 scene2.txt，内容是'祥子离开了房间'。"
  • AI 会：在 scene 目录下新建一个 scene2.txt 文件并写入您指定的内容。
  • 您还可以说："在 scene1.txt 的末尾追加一行对话。"
  • AI 会：读取 scene1.txt 并在文件末尾添加新的内容。

💪 终极能力：剧本转化

哎呀，剧情写好了，直接把把剧情文件给AI，让他自行调用MCP，帮你转化为Webgal游戏脚本， 它也能够满足绝大部分的人物对话分割，旁白安排。 角色立绘、动作、表情设置、背景图片、音效等设置，只要你的文件名和文件夹足够语义化，AI也能合理的 推断使用需求。

稍微比较难的是角色位置，因为Webgal的位置安排依靠游戏的屏幕大小。目前还没考虑这方面的解决方案。 如果你有对应的高级动画、角色位置摆放的需求，请在生成后自行微调

4. 语音合成 (GPT-SoVITS 集成)

这是本项目的核心功能之一：全自动为游戏对话生成高质量的配音。

工作原理

当您执行语音生成命令后，程序会：

  1. 读取剧本：我们的内置编译器会解析您指定的剧本文件（如 scene1.txt）。
  2. 识别对话：找出所有需要配音的对话行。
  3. 智能检测：通过检查 vocal 目录下的音频文件，自动跳过已经生成过语音的对话。音频文件使用角色名和对话内容的哈希值命名，确保相同内容的对话能够复用音频文件。（修改配置是不会重置缓存的，如果需要，请添加-force为该文件重新生成配音）
  4. 音频复用：对于同一个角色说的同一句话，会自动复用已经生成好的音频文件，即使在不同的剧情脚本中也能生效，从而大大减少翻译和语音合成的开销。

音频缓存策略：

  • 音频文件使用 {角色名}_{内容哈希}.wav 格式命名，例如：Alice_a1b2c3d4e5f6.wav
  • 内容哈希基于"角色名:对话内容"计算，确保相同角色的相同对话总是使用同一个音频文件
  • 在执行语音生成前，会自动检查 vocal 目录下是否已存在对应的音频文件
  • 如果文件已存在，直接跳过生成任务并在脚本中引用现有音频
  • 这种设计实现了跨文件的音频复用，大大提升了生成效率
  1. 翻译 (如果启用)：将新的或修改过的对话，根据 voice.config.json 中的配置，发送给翻译模型进行翻译。为了保证质量，翻译时会自动附带上下文。系统使用基于Promise的并发控制，可同时处理多个翻译任务，显著提升效率。
  2. 语音合成：将原文或翻译后的文本，连同对应的角色模型配置，发送给 GPT-SoVITS 服务进行语音合成。语音合成过程保持单线程执行，以避免模型切换冲突。
  3. 更新脚本：将生成好的语音文件（.wav）引用自动插入到剧本文件中。
  4. 备份：在修改脚本前，会自动在 .voice-backups 目录下创建备份，防止意外。

整个过程采用基于Promise的并发控制和智能队列任务排序，翻译阶段可并行执行多个任务，语音合成阶段优先处理同一角色的任务以减少模型切换开销，大幅提升效率。系统还提供详细的进度回调，让您实时了解处理状态。

使用方式

在配置好 voice.config.json 后，打开终端，执行以下命令即可开始为指定剧本生成语音：

# 为 scene1.txt 生成语音
npx openwebgal-mcp-server -voice scene1.txt -webgal <你的游戏目录>

# 强制模式：忽略缓存，为所有对话重新生成语音
npx openwebgal-mcp-server -voice scene1.txt -force -webgal <你的游戏目录>

5. 翻译模型接入

为了实现高质量的"外语配音"，本项目集成了强大的翻译功能。

配置特点

  • 多服务商支持：您可以灵活选择最适合您的翻译服务，无论是免费的本地模型（通过 Ollama），还是强大的商业模型（如 OpenAI, Google Gemini 等）。

  • 上下文感知：自动分析这句对话是否包含"它"、"那个"、"刚才"等需要依赖上下文才能准确理解的词语。如果包含，AI 会自动将前后几句对话一起发给翻译模型，极大地提升了翻译的准确性和自然度。

  • 高度自定义的 Prompt：

    • 全局提示 (additional_prompt): 您可以在 voice.config.json 中设置一个全局的提示，例如提供一份"角色中文名-外文名对照表"，或者解释游戏中的特殊术语。这个信息会提供给每一次翻译请求，确保译名统一、术语准确。
    • 角色提示 (prompt): 您可以为每个角色单独设置 Prompt，用以描述这个角色的说话风格，例如"一个喜欢用大小姐语气的角色"或"说话简洁、冷淡"，让翻译结果和后续的语音合成更贴合人物性格。

  • 关于Ollama服务的小模型选择

    • 模型在初次加载的时候都比较慢，请耐心等待，我们有设置30s的超时警告和3次重试机制
    • 尽量不要选择太小的模型，例如1.5b, 3b。除非你还对它们进行了翻译微调，否则不能很好的结合语境进行翻译
    • 不要选择思考模型，思考模型输出的效率极低。
    • 目前作者的体验是，gemma3:4b能较好的完成翻译流畅性，glm4:9b能较好的贴切语境和人物语言特色翻译

6. 并行处理系统

本项目采用了高效的并行处理系统，特别是在翻译和语音合成方面：

并发控制架构

  • 基于Promise的并发控制：使用现代JavaScript的Promise机制实现高效的并发任务处理，相比传统的多进程架构，更加轻量和灵活。
  • 智能队列管理：翻译任务采用并行处理，而语音合成任务则使用智能排序的单线程队列，确保同一角色的任务连续处理，减少模型切换开销。
  • 自适应并发限制：通过环境变量MAX_TRANSLATOR控制最大并发数，系统会自动管理并发任务数量，避免资源竞争。

性能优化

  • 翻译阶段：多任务并发执行，充分利用API服务的并发能力。
  • 语音合成阶段：优先处理同一角色的任务，减少模型切换次数，显著提升效率。
  • 资源管理：自动清理模型缓存，及时释放内存资源。

进度监控

系统提供完善的进度回调机制，让您可以实时了解：

  • 翻译进度：已完成/总任务数，当前处理的角色和文本
  • 语音合成进度：已完成/总任务数，当前处理的角色和文件
  • 错误处理：详细的错误信息和相关任务内容

这一设计使得整个翻译和语音合成过程更加高效、透明，同时保持了稳定性和可靠性。

迁移指南

如果您正在从旧版本升级，请注意以下变化：

  1. 环境变量 MAX_TRANSLATOR 现在用于控制Promise并发数量
  2. 移除了多进程架构，改用基于Promise的并发控制
  3. 新增了进度回调函数API，可通过 setCallbacks() 方法设置
  4. 所有翻译服务统一通过 TranslateService 类处理，支持更多模型供应商

7. 二次定制开发简略指南

如果您具备一定的编程基础（了解 TypeScript/JavaScript），您可以对本项目进行更深度的定制。

项目结构概览

  • src/：所有核心代码存放的目录。
    • server/tools/：AI 助手的"工具箱"。每个文件定义了一类能力（如 assets.ts 定义了资源管理能力）。
    • voice/：语音合成相关的所有逻辑。
    • translate/：翻译服务相关的逻辑。
  • prompts/：存放了 AI 助手的核心 Prompt (系统提示词)，定义了它的基本角色和行为准则。
  • package.json：项目定义与依赖管理文件。

开发流程

  1. 克隆项目：将本项目代码克隆到您的本地。
  2. 安装依赖：在项目根目录下执行 pnpm install。
  3. 开始开发：执行 pnpm run dev，这将启动 TypeScript 的实时编译，您所做的任何代码修改都会被自动编译。
  4. 运行测试：您可以修改 package.json 中 `