Roblox Studio MCP Server

Roblox Studio MCP Server

改进后的 Roblox Studio MCP 服务器更新版本

dmae97

开发者工具
访问服务器

README

Roblox Studio MCP 服务器

为 Roblox Studio 实现的模型上下文协议 (MCP) 服务器，使用 TypeScript 编写。

概述

此 MCP 服务器旨在为 Roblox Studio 开发提供资源、工具和提示。它允许 LLM 应用程序通过标准化接口访问 Roblox Studio 文档、模板、代码生成功能和其他功能。

特点

  • 资源: 访问 Roblox Studio 文档、API 参考和代码模板
  • 工具: Luau 代码生成和验证、资源搜索、游戏组件生成
  • 提示: 用于脚本生成、错误查找和性能优化的特殊提示
  • API 集成: 直接连接到 Roblox API 和 Open Cloud API
  • 交互式系统: 创建对话系统、UI 界面和复杂的游戏机制
  • 增强的性能: 内置缓存和速率限制以获得最佳性能
  • 强大的错误处理: 综合错误管理和优雅的错误恢复
  • 指标和监控: 内置健康检查和性能指标

先决条件

  • Node.js >= 18.x
  • npm 或 yarn
  • Roblox API 密钥（用于 API 集成功能）
  • Roblox Open Cloud API 密钥（用于 Open Cloud 功能）

安装

  1. 克隆存储库
git clone https://github.com/dmae97/roblox-studio-mcp-server.git
cd roblox-studio-mcp-server
  1. 安装依赖项
npm install
  1. 基于 .env.example 创建 .env 文件
cp .env.example .env
  1. 使用 Roblox API 密钥和其他配置更新 .env 文件
ROBLOX_API_KEY=your_api_key_here
ROBLOX_OPEN_CLOUD_API_KEY=your_open_cloud_api_key_here
ROBLOX_OPEN_CLOUD_UNIVERSE_ID=your_universe_id_here
  1. 构建项目
npm run build

运行服务器

在开发模式下启动服务器：

npm run dev

或者启动生产服务器：

npm start

服务器默认在端口 3000 上启动（可在 .env 中配置）。

Docker 运行 (未来支持)

您也可以使用 Docker 运行服务器：

# 构建镜像
docker build -t roblox-studio-mcp-server .

# 运行容器
docker run -p 3000:3000 -v .env:/app/.env roblox-studio-mcp-server

或者使用 docker-compose：

docker-compose up

配置选项

服务器可以使用 .env 文件中的环境变量进行配置：

服务器配置

  • PORT - 服务器运行的端口（默认值：3000）
  • SERVER_NAME - 服务器名称（默认值："Roblox Studio MCP Server"）
  • SERVER_VERSION - 服务器版本（默认值："1.0.0"）
  • NODE_ENV - 环境（development/production）

日志配置

  • DEBUG - 启用调试模式（true/false）
  • LOG_LEVEL - 日志级别（info, warn, error, debug）
  • LOG_TIMESTAMP - 在日志中包含时间戳（true/false）
  • LOG_COLOR - 对日志输出进行着色（true/false）

性能设置

  • ENABLE_RATE_LIMITING - 启用速率限制（true/false）
  • RATE_LIMIT_WINDOW - 速率限制的时间窗口（毫秒）
  • RATE_LIMIT_MAX_REQUESTS - 每个窗口的最大请求数
  • CACHE_TTL - 缓存数据的有效时间（秒）
  • CACHE_CHECK_PERIOD - 检查过期缓存条目的间隔（秒）

安全设置

  • CORS_ORIGINS - 允许的来源的逗号分隔列表，或 * 以允许所有来源
  • JWT_SECRET - 用于 JWT 令牌验证的密钥

API 端点

  • GET /sse - 用于 MCP 通信的 Server-Sent Events 端点
  • POST /messages - 用于 MCP 通信的消息端点
  • GET /health - 健康检查端点
  • GET /metrics - 服务器指标端点

资源

文档

  • docs://api/{section} - 访问 Roblox Studio API 文档
  • docs://api - 列出可用的文档部分
  • docs://luau - Luau 语言文档和最佳实践
  • docs://services/{service} - 特定 Roblox 服务的文档

模板

  • template://roblox/{category}/{name} - 访问代码模板
  • template://roblox - 列出可用的模板
  • template://ui/{component} - 使用 Roblox UI 的 UI 组件模板

工具

代码生成器

generate-roblox-code 工具根据用户规范生成 Roblox Luau 代码。

参数：

  • scriptType: 要生成的脚本类型（ServerScript、LocalScript、ModuleScript）
  • functionality: 脚本应执行的操作的描述
  • includeComments: 是否在代码中包含注释
  • targetRobloxVersion: (可选) 目标 Roblox 版本

资源搜索器

find-roblox-assets 工具根据用户标准搜索 Roblox 资源。

参数：

  • assetType: 要搜索的资源类型（Model、Decal、Mesh、Animation、Sound、Texture）
  • keywords: 搜索关键字或标签
  • maxResults: 要返回的最大结果数
  • includeDetails: 是否包含详细的资源信息

脚本验证器

validate-roblox-script 工具验证 Luau 脚本是否存在语法错误和最佳实践。

参数：

  • scriptContent: 要验证的 Luau 脚本内容
  • scriptType: 脚本类型（ServerScript、LocalScript、ModuleScript）
  • checkBestPractices: 是否检查最佳实践
  • checkPerformance: 是否检查性能问题

新工具

数据存储管理器

create-datastore-system 工具生成用于持久数据管理的完整 DataStore 代码。

参数：

  • datastoreName: DataStore 名称
  • dataStructure: 要存储的数据的结构
  • sessionCaching: 是否包含会话缓存逻辑
  • backupStrategy: 数据备份策略
  • playerData: 是否为玩家数据

物理系统生成器

create-physics-system 工具为 Roblox 生成基于物理的系统。

参数：

  • objectName: 物理对象的名称
  • objectType: 物理对象类型
  • size: 大小尺寸
  • material: 材料类型
  • physicsProperties: 密度、摩擦等
  • constraints: 可选的物理约束

UI 构建器

create-ui-system 工具生成 Roblox UI 代码。

参数：

  • uiType: UI 类型（Menu、HUD、Dialog、Inventory）
  • elements: 要包含的 UI 元素
  • responsive: UI 是否应该具有响应性
  • stylePreset: 要使用的视觉样式预设

Roblox API 连接器

用于直接连接到 Roblox API 的工具：

资源搜索 API

roblox-search-assets 工具使用官方 Roblox API 搜索资源。

Open Cloud 集成

roblox-open-cloud 工具提供对 Roblox Open Cloud API 功能的访问。

参数：

  • feature: 要使用的 Open Cloud 功能
  • universeId: 要操作的 Universe ID
  • actionType: 要执行的操作类型
  • data: 操作的数据

提示

脚本生成器

generate-script 提示有助于通过 AI 辅助生成 Roblox 脚本。

参数：

  • scriptType: 要生成的脚本类型
  • functionality: 脚本应执行的操作的描述
  • includeComments: 是否在代码中包含注释
  • complexity: 复杂程度（Beginner、Intermediate、Advanced）
  • targetAudience: 目标受众（Child、Teen、Adult）

错误查找器

find-bugs 提示分析错误并提出改进建议。

参数：

  • scriptContent: 要分析的 Luau 脚本内容
  • scriptType: 脚本类型
  • checkPerformance: 是否检查性能问题
  • checkSecurity: 是否检查安全问题
  • suggestImprovements: 是否提出改进建议

性能优化器

optimize-performance 提示分析和优化 Roblox 脚本以获得更好的性能。

参数：

  • scriptContent: 要优化的脚本
  • targetFPS: 目标每秒帧数
  • optimizationLevel: 要应用的优化级别
  • preserveReadability: 是否优先考虑可读性

开发

项目结构

  • src/index.ts - 主服务器文件
  • src/utils/ - 实用程序函数
  • src/middleware/ - 用于错误处理、速率限制等的 Express 中间件
  • src/tools/ - MCP 工具实现
  • src/resources/ - MCP 资源实现
  • src/prompts/ - MCP 提示实现
  • src/api/ - Roblox API 客户端实现
  • src/tools/interactive/ - 交互式系统和 UI 工具
  • src/tools/physics/ - 物理系统工具
  • src/tools/datastore/ - DataStore 管理工具
  • src/tools/opencloud/ - Open Cloud API 集成

测试 (未来支持)

运行单元测试：

npm test

运行集成测试：

npm run test:integration

生成完整的测试覆盖率报告：

npm run test:coverage

MCP 集成示例

如何在各种 LLM 应用程序中使用此 MCP 服务器的示例：

示例 1：使用 Claude 和 API

// 使用 Claude 从 Web 应用程序调用 MCP 服务器的示例代码
async function callRobloxMcp() {
  const response = await fetch('https://your-claude-api-endpoint/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-claude-api-key'
    },
    body: JSON.stringify({
      model: "claude-3.7-sonnet-20250219",
      messages: [
        {
          role: "user",
          content: "Roblox Studio에서 플랫포머 게임을 만드는 데 도움을 주시겠어요?"
        }
      ],
      tool_choice: "auto",
      tools: [
        {
          function: {
            name: "mcp",
            description: "Roblox Studio MCP 服务器调用",
            parameters: {
              type: "object",
              properties: {
                server_url: {
                  type: "string",
                  description: "MCP 服务器的 URL"
                },
                tool_name: {
                  type: "string",
                  description: "要调用的 MCP 工具的名称"
                },
                tool_parameters: {
                  type: "object",
                  description: "MCP 工具的参数"
                }
              },
              required: ["server_url", "tool_name"]
            }
          }
        }
      ]
    })
  });
  
  return await response.json();
}

示例 2：使用 CLI 工具的 MCP 服务器

您还可以通过命令行使用 MCP 服务器：

# 安装 MCP 客户端 CLI
npm install -g @modelcontextprotocol/cli

# 连接到 MCP 服务器
mcp connect http://localhost:3000

# 使用 MCP 工具
mcp tool generate-roblox-code --scriptType=ServerScript --functionality="플레이어 이동 처리" --includeComments=true

# 访问模板
mcp resource template://roblox/game/platformer

示例 3：与 Anthropic 的 Claude 连接

import anthropic
from anthropic.tool_use import MCP

# 初始化 Claude 客户端
client = anthropic.Client(api_key="your-anthropic-api-key")

# 创建 MCP 连接
mcp = MCP(server_url="http://localhost:3000")

# 向具有 MCP 功能的 Claude 发送消息
response = client.messages.create(
    model="claude-3.7-sonnet-20250219",
    max_tokens=1000,
    system="您是一个可以访问 Roblox Studio MCP 服务器的有用 AI 助手。",
    messages=[
        {
            "role": "user",
            "content": "Roblox Studio에서 멀티플레이어 게임을 만들고 싶어요. 어떤 도구를 사용해야 할까요?"
        }
    ],
    tools=[mcp.to_tool()]
)

print(response.content)

脚本

  • npm run build - 构建项目
  • npm run dev - 在具有热重载的开发模式下运行
  • npm start - 运行生产服务器
  • npm run lint - 运行 linting
  • npm test - 运行测试

故障排除

常见问题

  1. 连接错误: 确保 Roblox API 密钥已正确配置。
  2. 内存使用量高: 调整缓存 TTL 设置以管理内存使用量。
  3. 速率限制错误: 根据您的环境调整 RATE_LIMIT_* 设置。

日志

要调试问题，请将 LOG_LEVEL=debug 设置为启用详细日志记录。

最近更新

  • 使用自定义中间件改进错误处理
  • 通过可配置的级别和格式改进日志系统
  • 实现缓存系统以提高性能
  • 添加速率限制以防止滥用
  • 扩展指标端点以进行更好的监控
  • 添加优雅的关闭处理
  • 更新到最新的 Roblox API 端点
  • 修复名称不一致 (Roblex → Roblox)

未来计划的功能

  • JWT 身份验证: 为了增强安全性
  • API 文档: OpenAPI/Swagger 集成
  • Docker 支持: 用于轻松部署的容器化
  • 测试套件: 完整的单元和集成测试
  • CI/CD 管道: 自动化测试和部署

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript