mcp-roblox-docs

🚀 MCP Roblox 文档

这是一个全面的 MCP（模型上下文协议）服务器，提供完整的 Roblox 生态系统文档。你可以通过 AI 助手查询 API 参考、FastFlags、Open Cloud REST API、Luau 语言文档和 DevForum 等内容。

🚀 快速开始

快速启动（推荐）

使用此 MCP 服务器最简单的方法是通过 uvx：

uvx mcp-roblox-docs

无需安装和设置，直接可用！

从源代码安装

git clone https://github.com/nhattamgithub/mcp-roblox-docs
cd mcp-roblox-docs
uv sync
uv run mcp-roblox-docs

✨ 主要特性

• 始终保持最新：自动从 Roblox 的官方源同步数据。
• 27 种专业工具：全面覆盖 Roblox 生态系统。
• 全文搜索：可搜索 850 多个类、35000 多个成员、14000 多个 FastFlags 和 865 个云 API 端点。
• 数据类型和库：包含 44 种数据类型（如 Vector3、CFrame 等）和 11 个 Luau 标准库。
• 多语言支持：支持包括英语、印尼语、日语、韩语、中文等 15 种语言。
• DevForum 集成：通过智能缓存搜索社区讨论。
• Open Cloud API：提供完整的 REST API 文档，包括认证、参数和响应模式。
• FastFlags 参考：可搜索和探索 14000 多个引擎标志。
• Luau 语言文档：提供完整的语言参考和全局变量。
• 零成本：完全免费，无需 API 密钥。
• 优化设计：采用懒加载、内存缓存和 DevForum 结果缓存。
• 快速同步：并行下载（快 7 - 10 倍）、重试逻辑和 HTTP 压缩。

📦 安装指南

快速启动（推荐）

使用此 MCP 服务器最简单的方法是通过 uvx：

uvx mcp-roblox-docs

无需安装和设置，直接可用！

从源代码安装

git clone https://github.com/nhattamgithub/mcp-roblox-docs
cd mcp-roblox-docs
uv sync
uv run mcp-roblox-docs

💻 使用示例

搜索 API

用户：如何平滑地为物体添加动画效果？
AI：[使用 roblox_search("tween animation")]
→ TweenService、TweenBase、Tween、EasingStyle...

获取类信息

用户：介绍一下 TweenService
AI：[使用 roblox_get_class("TweenService")]
→ 包含 Create()、GetValue()、SmoothDamp() 方法的完整类信息
   类别：动画，首选父级：game

检查弃用情况

用户：BodyPosition 是否已弃用？
AI：[使用 roblox_check_deprecated("BodyPosition")]
→ 是的，已弃用。请使用基于约束的 AlignPosition 代替。

搜索 FastFlags

用户：哪些标志控制物理效果？
AI：[使用 roblox_search_fflags("physics")]
→ FIntPhysicsMaxSteps、DFFlagPhysicsDebug、FFlagPhysicsOptimized...

获取云 API 端点

用户：如何向主题发布消息？
AI：[使用 roblox_search_cloud_api("publish message")]
→ POST /v1/universes/{universeId}/topics/{topic}
   认证：具有 messaging-service:publish 作用域的 API 密钥

获取 Luau 全局变量

用户：Luau 有哪些内置函数？
AI：[使用 roblox_get_luau_globals()]
→ print、warn、error、typeof、select、pairs、ipairs、next...

Luau 语言文档

用户：Luau 中的类型注解如何工作？
AI：[使用 roblox_get_luau_topic("type-annotations")]
→ 关于类型语法、泛型、类型推断的完整指南...

搜索 DevForum

用户：人们如何在 Roblox 中优化内存？
AI：[使用 roblox_search_devforum("memory optimization")]
→ 相关社区讨论的链接（缓存 1 小时）

获取数据类型信息

用户：如何创建一个 Vector3？
AI：[使用 roblox_get_datatype("Vector3")]
→ Vector3.new(x, y, z)、Vector3.one、Vector3.zero
   属性：X、Y、Z、Magnitude、Unit
   方法：Cross、Dot、Lerp、Angle...

获取库函数

用户：math.clamp 如何工作？
AI：[使用 roblox_get_library_function("math", "clamp")]
→ math.clamp(x, min, max): number
   返回 x 限制在 min 和 max 之间的值

📚 详细文档

配置

Claude Desktop

添加到你的 Claude Desktop 配置中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roblox-docs": {
      "command": "uvx",
      "args": ["mcp-roblox-docs"]
    }
  }
}

Cursor / 其他 MCP 客户端

{
  "mcpServers": {
    "roblox-docs": {
      "command": "uvx",
      "args": ["mcp-roblox-docs"]
    }
  }
}

或者如果你从源代码运行：

{
  "command": "uv",
  "args": ["--directory", "/path/to/mcp-roblox-docs", "run", "mcp-roblox-docs"]
}

可用工具（共 27 个）

核心 API 工具

| 工具 | 描述 | |------|-------------| | roblox_search | 对所有 Roblox API 进行全文搜索 | | roblox_get_class | 获取包含成员、元数据和类别的完整类信息 | | roblox_get_member | 获取详细的成员信息（属性/方法/事件） | | roblox_get_enum | 获取包含所有值的枚举 | | roblox_check_deprecated | 检查弃用状态并获取替代方案 | | roblox_list_services | 列出所有 290 多个 Roblox 服务 |

扩展 API 工具

| 工具 | 描述 | |------|-------------| | roblox_get_inheritance | 获取类层次结构和子类 | | roblox_search_devforum | 搜索 DevForum 线程（缓存） | | roblox_recent_changes | 获取 API 版本信息 | | roblox_list_enums | 列出所有 500 多个可用的枚举 | | roblox_sync | 强制同步数据或更改语言 | | roblox_health | 获取服务器状态、统计信息和诊断信息 |

FastFlags 工具

| 工具 | 描述 | |------|-------------| | roblox_search_fflags | 按名称搜索 14000 多个 FastFlags | | roblox_get_fflag | 获取特定 FastFlag 的详细信息和类型 | | roblox_list_fflag_prefixes | 解释 FastFlag 前缀类型（FFlag、FInt、DFFlag 等） |

Luau 全局变量工具

| 工具 | 描述 | |------|-------------| | roblox_get_luau_globals | 列出所有 Luau 全局函数和类型 | | roblox_get_luau_global | 获取特定全局变量的详细信息（如 print、typeof 等） |

Open Cloud API 工具

| 工具 | 描述 | |------|-------------| | roblox_search_cloud_api | 搜索 865 个 REST API 端点 | | roblox_get_cloud_endpoint | 获取端点详细信息（认证、参数、响应） | | roblox_list_cloud_apis | 列出所有 Open Cloud API 类别 |

Luau 语言工具

| 工具 | 描述 | |------|-------------| | roblox_get_luau_topic | 获取 Luau 语言文档 | | roblox_list_luau_topics | 列出可用的 Luau 文档主题 |

数据类型工具

| 工具 | 描述 | |------|-------------| | roblox_get_datatype | 获取数据类型文档（如 Vector3、CFrame、Color3、UDim2 等） | | roblox_list_datatypes | 列出所有 44 个可用的 Roblox 数据类型 |

库工具

| 工具 | 描述 | |------|-------------| | roblox_get_library | 获取 Luau 库文档（如 math、string、table 等） | | roblox_get_library_function | 获取特定函数的详细信息（如 math.clamp、string.split 等） | | roblox_list_libraries | 列出所有 11 个 Luau 标准库 |

MCP 资源（v3.3.0+）

资源提供基于 URI 的直接文档访问： | URI 模式 | 描述 | |-------------|-------------| | roblox://class/{name} | 获取类文档（例如，roblox://class/TweenService） | | roblox://enum/{name} | 获取枚举值（例如，roblox://enum/EasingStyle） | | roblox://datatype/{name} | 获取数据类型文档（例如，roblox://datatype/Vector3） | | roblox://library/{name} | 获取库文档（例如，roblox://library/math） | | roblox://luau/{topic} | 获取 Luau 语言文档（例如，roblox://luau/tables） |

MCP 提示（v3.3.0+）

提示提供可重复使用的工作流模板： | 提示 | 描述 | |--------|-------------| | explain-api | 生成 Roblox API 类的详细解释 | | debug-deprecation | 帮助从弃用的 API 迁移到替代方案 | | code-review | 审查 Roblox Luau 代码以遵循最佳实践 | | learn-service | 通过示例了解 Roblox 服务 |

数据源

所有数据均从免费的公共源获取： | 源 | 内容 | |--------|---------| | Roblox-Client-Tracker | 类、成员、枚举、FastFlags、Luau 类型、元数据 | | Roblox Creator Docs | Open Cloud API、Luau 语言文档 | | DevForum | 社区讨论 |

数据统计

| 数据类型 | 数量 | |-----------|-------| | 类 | 850+ | | 成员 | 35000+ | | 枚举 | 500+ | | FastFlags | 14000+ | | Luau 全局变量 | 87 | | 云端点 | 865 | | Luau 文档主题 | 20 | | 数据类型 | 44 | | 库 | 11 |

支持的语言

使用 roblox_sync(language="id-id") 切换文档语言：

• en-us - 英语（默认）
• id-id - 印尼语
• ja-jp - 日语
• ko-kr - 韩语
• zh-cn - 中文（简体）
• zh-tw - 中文（繁体）
• de-de - 德语
• es-es - 西班牙语
• fr-fr - 法语
• it-it - 意大利语
• pt-br - 葡萄牙语（巴西）
• ru-ru - 俄语
• th-th - 泰语
• tr-tr - 土耳其语
• vi-vn - 越南语

缓存位置

数据缓存在系统的标准缓存目录中：

• Windows：%LOCALAPPDATA%\mcp-roblox-docs\
• macOS：~/Library/Caches/mcp-roblox-docs/
• Linux：~/.cache/mcp-roblox-docs/ 当 Roblox 发布新的 API 版本时，缓存会自动更新。

开发

# 克隆仓库
git clone https://github.com/nhattamgithub/mcp-roblox-docs
cd mcp-roblox-docs

# 安装依赖
uv sync

# 本地运行服务器
uv run mcp-roblox-docs

# 测试工具数量
uv run python -c "from src.server import mcp; print('工具数量:', len(mcp._tool_manager._tools))"

# 构建分发版本
uv build

# 发布到 PyPI
uv publish

变更日志

v3.3.0 (2026-01-25)

完整 MCP 原语实现

• 添加了 MCP 资源（5 个资源模板）：
  • roblox://class/{name} - 直接访问类文档
  • roblox://enum/{name} - 直接访问枚举值
  • roblox://datatype/{name} - 直接访问数据类型文档
  • roblox://library/{name} - 直接访问库文档
  • roblox://luau/{topic} - 直接访问 Luau 语言文档
• 添加了 MCP 提示（4 个工作流模板）：
  • explain-api - 详细解释 Roblox API 类
  • debug-deprecation - 帮助从弃用的 API 迁移
  • code-review - 审查 Roblox Luau 代码
  • learn-service - 了解 Roblox 服务
• 为同步操作添加了 2 分钟超时
• 现在实现了所有 3 个 MCP 原语：工具、资源和提示

v3.2.0 (2026-01-25)

MCP 最佳实践和质量改进

• 添加了 roblox_health 工具，用于获取服务器状态、统计信息和诊断信息
• 在所有 17 个接受用户输入的工具中添加了输入验证
• 通过 MCP_ROBLOX_DOCS_LOG_LEVEL 环境变量添加了可配置的日志记录
• 添加了 py.typed 标记文件以符合 PEP 561
• 改进了 DevForum 磁盘缓存，在保存时清理过期条目
• 修复了加载器中的重复正则表达式模式
• 更新了 USER_AGENT 以匹配当前版本
• 现在共有 27 个工具

v3.1.0 (2026-01-25)

开发者体验和搜索改进

• 支持模糊搜索，容忍拼写错误（例如，“Tweenservce” → “TweenService”）
• 持久化 DevForum 缓存（服务器重启后仍保留）
• 为 roblox_search 工具添加了 fuzzy 参数（默认值：True）
• 修复了格式化器中的 TypedDict 类型提示，以提高类型安全性
• 添加了 pytest 测试套件（56 个测试用于验证、搜索和缓存）
• 添加了开发依赖项：pytest、pytest-asyncio

v3.0.1 (2026-01-25)

• 修复了变更日志中的年份（2025 -> 2026）

v3.0.0 (2026-01-25)

性能和可靠性发布

• 使用信号量进行并行下载（同步速度快 7 - 10 倍）
• 带有指数退避的重试逻辑（3 次尝试）
• 支持 HTTP 压缩（gzip、deflate）
• 预编译正则表达式模式（更快的解析）
• 现在可以通过 roblox_search 搜索数据类型/库
• DevForum 速率限制（防止 429 错误）
• 用于安全的输入验证模块

v2.1.0 (2026-01-25)

• 添加了数据类型文档（44 种类型：Vector3、CFrame、Color3、UDim2、TweenInfo 等）
• 添加了 Luau 库文档（11 个库：math、string、table、task 等）
• 添加了 5 个新工具：roblox_get_datatype、roblox_list_datatypes、roblox_get_library、roblox_get_library_function、roblox_list_libraries
• 工具数量从 21 个扩展到 26 个

v2.0.0 (2026-01-25)

• 添加了 FastFlags 支持（从 FVariables.txt 获取 14000 多个标志）
• 添加了 Luau 全局变量（87 个内置函数/类型）
• 添加了 Open Cloud REST API（从 openapi.json 获取 865 个端点）
• 添加了 Luau 语言文档（20 个主题）
• 添加了类元数据（类别、图标、首选父级）
• 添加了 DevForum 缓存（TTL 为 1 小时）
• 增强了弃用替代方案（40 多个类、30 多个成员映射）
• 工具数量从 11 个扩展到 21 个

v1.0.1

• 初始稳定版本
• 核心 API 文档工具
• DevForum 搜索集成
• 多语言支持

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。

致谢

• Roblox-Client-Tracker 由 MaximumADHD 开发
• Roblox Creator Docs 由 Roblox 开发
• MCP Protocol 由 Anthropic 开发