VTube Studio MCP 服务器

概述

VTube Studio MCP 服务器是一个旨在将 VTube Studio 与模型上下文协议（MCP）集成的插件。该服务器促进了 VTube Studio 和其他兼容 MCP 应用程序之间的通信，允许从 VTube Studio 直接获取和操作 Live2D 参数。

功能

• WebSocket 连接：建立与 VTube Studio 的 WebSocket 连接以实现实时通信。
• 认证：处理与 VTube Studio 的认证，包括用于安全访问的令牌管理。当 MCP 服务器连接到 VTube Studio 时，它会请求认证。如果没有可用的存储令牌或存储令牌无效，VTube Studio 将生成一个新的令牌。用户必须在 VTube Studio 中批准此认证请求，之后令牌将发送给 MCP 服务器以进行安全通信。根据服务器的配置，此令牌可选择性地存储以供未来会话使用。
• Live2D 参数检索：提供一种工具来从 VTube Studio 获取 Live2D 参数，从而实现动态控制和交互。
• 令牌存储选项：提供了不将认证令牌存储到文件中启动服务器的灵活性，增强了某些使用场景的安全性。

安装

要安装 VTube Studio MCP 服务器，请按照以下步骤操作：

1. 确保您的系统上已安装 Node.js。
2. 克隆此仓库或下载源代码。
3. 导航到项目目录并运行：

   npm install
   

4. 使用以下命令启动服务器：

   npm start
   

使用

启动服务器

要使用默认设置（启用令牌存储）启动服务器：

npm start

要不存储认证令牌启动服务器：

node dist/index.js --no-store-token

配置

服务器可以通过 MCPServerOptions 接口进行配置。关键选项包括：

• name：MCP 服务器的名称。
• description：对服务器用途的简要描述。
• version：服务器的版本。
• storeToken：一个布尔标志，用于启用或禁用令牌存储（默认值为 true）。

工具

• 激活表情：激活当前模型在 VTube Studio 中的特定表情。
• 添加自定义参数：向当前模型添加自定义参数以实现高级控制。
• API 服务器发现：通过 UDP 在本地网络上监听 VTube Studio API 状态广播（目前是 UDP 功能的占位符）。
• 检查是否找到人脸：检查 VTube Studio 的跟踪系统是否检测到人脸。
• 控制表情：控制当前模型的表情状态或强度。
• 控制物品动画：管理场景中物品的动画设置。
• 删除自定义参数：从当前模型中移除自定义参数。
• 获取艺术网格列表：获取当前模型的艺术网格列表，可用于定制。
• 获取可用模型：列出可以加载到 VTube Studio 的所有可用模型。
• 获取当前模型：获取当前加载到 VTube Studio 的模型信息。
• 获取当前模型物理属性：获取当前模型的物理设置。
• 获取表情状态：获取模型的表情当前状态。
• 获取快捷键：列出在 VTube Studio 中配置的可用快捷键。
• 获取物品列表：获取当前场景中的物品列表。
• 获取 Live2D 参数：从 VTube Studio 获取 Live2D 参数以实现动态控制。
• 获取参数值：获取 VTube Studio 中特定参数的当前值。
• 获取后处理效果列表：获取可用的后处理效果列表。
• 获取场景颜色叠加信息：获取有关场景颜色叠加的信息，如照明设置。
• 获取跟踪参数：获取与 VTube Studio 中的人脸或身体跟踪相关的参数。
• 获取 VTS 文件夹：获取 VTube Studio 使用的文件夹路径或配置。
• 获取 VTS 统计数据：从 VTube Studio 获取使用统计或性能数据。
• 注入参数数据：将参数数据注入或更新到 VTube Studio 以实现自定义控制。
• 加载物品到场景：将特定物品加载到 VTube Studio 的当前场景中。
• 加载模型：将指定模型加载到 VTube Studio。
• 调整场景中的物品位置：调整场景中物品的位置或属性。
• 移动模型：更改当前模型在场景中的位置或旋转。
• NDI 配置：管理用于流媒体或输出的 NDI（网络设备接口）配置。
• 将物品固定到模型：将物品固定到模型的特定部分以实现同步运动。
• 从场景中移除物品：从当前场景中移除指定物品。
• 请求 API 权限：请求用户授予特定 API 权限以访问某些功能。
• 选择艺术网格：选择特定的艺术网格进行操作或定制。
• 设置当前模型物理属性：更新或覆盖当前模型的物理设置。
• 设置后处理效果：应用或修改 VTube Studio 中的后处理效果。
• 订阅事件：订阅来自 VTube Studio 的特定事件或更新以实现实时监控。
• 着色艺术网格：对选定的艺术网格应用颜色着色以实现视觉定制。
• 触发快捷键：触发在 VTube Studio 中配置的特定快捷键动作。

项目结构

• src/：包含服务器的源代码。
  • index.ts：应用程序的入口点。
  • mcp-server.ts：核心 MCP 服务器实现。
  • tools/：包含如 getLive2DParameters.ts 等特定功能的工具。
  • utils/：实用函数，包括用于处理认证的 authenticate.ts。
• test/：包含服务器各个组件的单元测试。
• dist/：从 TypeScript 源编译的 JavaScript 输出。

测试

运行单元测试：

npm test

这将使用 Mocha 执行 test/ 目录中的所有测试。

贡献

欢迎贡献！请在项目的 GitHub 页面提交问题或拉取请求，以报告任何错误、功能或改进。

许可证

本项目采用 MIT 许可证 - 详情见 LICENSE 文件。

联系

如有支持需求或疑问，请通过 GitHub 问题联系项目维护者。