MCP 服务器

Roblox Studio MCP 서버

Roblox Studio 的模型上下文协议服务器

dmae97

开发者工具

访问服务器

README

Roblox Studio MCP 服务器

这是一个用于将 Roblox Studio 的数据和功能与外部系统集成的模型上下文协议 (MCP) 服务器。通过此服务器，开发者可以实现 Roblox Studio 与外部工具之间的实时通信和数据同步。

介绍

Roblox Studio MCP 服务器是一个旨在增强 Roblox 游戏开发过程的工具。该服务器实现了外部系统与 Roblox Studio 之间的双向通信，从而可以自动化各种任务，例如脚本生成、UI 元素操作和游戏系统管理。

主要使用场景：

利用 AI 模型进行代码生成和修改
与外部编辑器集成，提供强大的代码编辑体验
实时游戏数据监控和操作
游戏开发工作流程自动化

功能

双向实时通信: Roblox Studio 和实时数据交换
模型管理: 脚本、UI、服务等各种 Roblox 模型管理
事件驱动架构: 通过 SSE (Server-Sent Events) 进行实时事件传递
可扩展的工具系统: 轻松扩展新的工具和功能
安全认证: API 密钥和会话基础认证系统
有效性验证: 模型数据有效性检查，保证数据完整性
详细的日志系统: 用于问题解决和调试的日志记录

开始使用

必备条件

Node.js 16.x 或更高版本
NPM 或 Yarn
Typescript 5.x
Roblox Studio

安装

克隆存储库:

git clone https://github.com/your-username/roblex-studio-mcp-server.git
cd roblex-studio-mcp-server

安装依赖:
```
npm install
```
环境配置:
```
cp .env.example .env
```
编辑 .env 文件，设置需要的环境变量
运行服务器:
```
npm run dev
```
安装 Roblox Studio 插件:
- 将 src/plugins/RobloxStudioPlugin.lua 文件复制到 Roblox Studio 插件文件夹
- 在 Roblox Studio 中激活插件

首次连接

运行 Roblox Studio
打开 MCP 服务器插件
设置服务器 URL (默认值: http://localhost:3000)
点击 '连接' 按钮
成功连接后，控制台会显示连接消息

配置

环境变量

变量名	说明	默认值
`PORT`	服务器端口	`3000`
`LOG_LEVEL`	日志级别 (debug, info, warn, error)	`info`
`API_KEYS`	逗号分隔的 API 密钥列表	-
`JWT_SECRET`	JWT 令牌加密密钥	-
`REQUIRE_AUTH`	是否需要认证 (true/false)	`false`
`SESSION_TIMEOUT`	会话超时时间(秒)	`3600`

配置文件

config/default.json: 默认服务器配置
config/development.json: 开发环境配置 (.env 文件配置优先)
config/production.json: 生产环境配置

API 文档

详细的 API 文档请参考 ROBLOX-STUDIO-API.md 文件。

示例

脚本生成示例

// 连接服务器
const eventSource = new EventSource('http://localhost:3000/sse?studioId=myStudio');
let sessionId = '';

// 连接成功时接收消息端点信息
eventSource.addEventListener('endpoint', (event) => {
  const data = JSON.parse(event.data);
  sessionId = data.sessionId;
  
  // 脚本生成请求
  fetch(`http://localhost:3000/messages?sessionId=${sessionId}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      type: 'createModel',
      modelType: 'script',
      data: {
        name: 'HelloWorld',
        type: 'LocalScript',
        content: 'print("Hello from MCP Server!")',
        parent: 'StarterPlayerScripts'
      }
    })
  });
});

UI 元素生成示例

// UI 元素生成请求
fetch(`http://localhost:3000/messages?sessionId=${sessionId}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'createModel',
    modelType: 'ui',
    data: {
      name: 'MainMenu',
      type: 'Frame',
      size: { width: 400, height: 300 },
      position: { x: 0.5, y: 0.5 },
      properties: {
        AnchorPoint: [0.5, 0.5],
        BackgroundColor3: [0.1, 0.1, 0.1]
      }
    }
  })
});

更多示例请参考 src/examples 目录。

开发

项目结构

roblex-studio-mcp-server/
├── src/
│   ├── index.ts             # 服务器入口点
│   ├── models/              # 模型定义
│   ├── tools/               # MCP 工具
│   ├── utils/               # 实用函数
│   ├── plugins/             # Roblox Studio 插件
│   └── examples/            # 示例代码
├── config/                  # 配置文件
├── logs/                    # 日志文件
├── docs/                    # 文档
└── test/                    # 测试

创建新工具

在 src/tools 目录中创建新文件
定义工具并实现 register 函数
在 src/tools/index.ts 文件中注册工具

示例:

// src/tools/myTool.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { logger } from '../utils/logger.js';

export const myTool = {
  register: (server: McpServer) => {
    server.tool(
      'my-tool-name',
      {
        // 输入模式
        param1: { type: 'string', description: '参数 1' },
        param2: { type: 'number', description: '参数 2' }
      },
      async (params) => {
        logger.info(`Tool executed with params: ${JSON.stringify(params)}`);
        
        // 工具逻辑实现
        
        return {
          content: [
            { type: 'text', text: `结果: ${params.param1}` }
          ]
        };
      }
    );
    
    logger.debug('My tool registered');
  }
};

// 在 src/tools/index.ts 中注册
import { myTool } from './myTool.js';
// ...
myTool.register(server);