roblox-studio-physical-operation-mcp 0.1.0__tar.gz

roblox_studio_physical_operation_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:  # 允许手动触发
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    
+    permissions:
+      id-token: write  # 用于 Trusted Publisher
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

roblox_studio_physical_operation_mcp-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+
+*.rbxl.lock
+*.png
+dist/
+# Test outputs
+tests/capture_test_output/
+tests/screenshots/
+screenshots/
+
+# Lock files
+*.lock
+
+# Reference images (not needed in repo)
+roblox_studio_physical_operation_mcp/buttons*.jpg

roblox_studio_physical_operation_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 White Dragon Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roblox_studio_physical_operation_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: roblox-studio-physical-operation-mcp
+Version: 0.1.0
+Summary: MCP server for controlling Roblox Studio - toolbar detection, game control, log analysis
+Project-URL: Homepage, https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp
+Project-URL: Repository, https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp
+Project-URL: Issues, https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp/issues
+Author: White Dragon Tools
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,mcp,model-context-protocol,roblox,roblox-studio
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: opencv-python
+Requires-Dist: pillow
+Requires-Dist: pywin32
+Description-Content-Type: text/markdown
+
+# Roblox Studio MCP
+
+一个用于控制 Roblox Studio 的 MCP (Model Context Protocol) 服务。
+
+## 安装
+
+```bash
+pip install roblox-studio-physical-operation-mcp
+```
+
+## 配置 MCP
+
+### Claude Desktop
+
+编辑 `%APPDATA%\Claude\claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "roblox-studio": {
+      "command": "python",
+      "args": ["-m", "roblox_studio_physical_operation_mcp"]
+    }
+  }
+}
+```
+
+### Droid
+
+编辑 `~/.factory/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "roblox-studio": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "roblox_studio_physical_operation_mcp"]
+    }
+  }
+}
+```
+
+> **注意**：Windows Store 版 Python 可能需要使用完整路径：
+> ```json
+> "command": "C:\\Users\\<用户名>\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\\python.exe"
+> ```
+
+## 从源码安装
+
+```bash
+git clone https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp.git
+cd roblox-studio-physical-operation-mcp
+pip install -r requirements.txt
+python -m roblox_studio_physical_operation_mcp
+```
+
+---
+
+## AI 使用指南
+
+### ⚠️ 重要：获取 place_path 或 place_id
+
+**不知道 place_path 或 place_id 时，必须先调用 `studio_list()` 获取！**
+
+```python
+# 先获取当前运行的 Studio 实例
+instances = studio_list()
+# 返回示例:
+# [{"pid": 12345, "type": "local", "place_path": "D:/game.rbxl"},
+#  {"pid": 67890, "type": "cloud", "place_id": 110155533210141}]
+
+# 然后用返回的 place_path 或 place_id 操作
+logs_get(place_path=instances[0]["place_path"])
+```
+
+### 推荐工作流程
+
+**调试已打开的 Studio**
+```
+1. studio_list()               # 获取运行中的 Studio 实例
+2. studio_query(place_path)    # 查询状态
+3. modal_close(place_path)     # 如果有模态弹窗，关闭它们
+4. game_start(place_path)      # 开始游戏
+5. logs_get(place_path)        # 获取日志
+6. game_stop(place_path)       # 停止游戏
+```
+
+**打开新的 Studio**
+```
+1. studio_open(place_path)     # 打开 Studio（本地文件）
+2. studio_query(place_path)    # 查询状态
+3. modal_close(place_path)     # 如果有模态弹窗，关闭它们
+4. studio_query(place_path)    # 确认 ready=true
+5. game_start(place_path)      # 开始游戏
+6. logs_get(place_path)        # 获取日志
+7. game_stop(place_path)       # 停止游戏
+8. studio_close(place_path)    # 关闭 Studio
+```
+
+### 支持两种 Place 类型
+
+所有工具都支持两种参数（二选一）：
+- `place_path` - 本地 .rbxl 文件路径
+- `place_id` - 云端 Roblox Place ID
+
+```python
+# 本地文件
+logs_get(place_path="D:/game.rbxl")
+
+# 云端 Place（从网页打开的）
+logs_get(place_id=110155533210141)
+```
+
+### studio_query 返回值说明
+
+```json
+{
+  "active": true,       // Studio 是否运行中
+  "ready": true,        // 是否就绪（无模态弹窗）
+  "pid": 12345,         // 进程 ID
+  "hwnd": 67890,        // 主窗口句柄
+  "has_modal": false,   // 是否有模态弹窗
+  "modal_count": 0,     // 模态弹窗数量
+  "modals": []          // 模态弹窗详情
+}
+```
+
+**重要**: `ready=true` 时才能正常操作 Studio。
+
+---
+
+## 工具列表
+
+### 系统工具
+
+| 工具 | 说明 |
+|------|------|
+| `studio_help()` | 获取使用指南 |
+| `studio_list()` | **列出所有运行中的 Studio 实例** |
+| `studio_open(place_path)` | 打开 Studio 并加载 .rbxl 文件 |
+| `studio_close(place_path/place_id)` | 关闭 Studio |
+| `studio_status(place_path/place_id)` | 获取基本状态 |
+| `studio_query(place_path/place_id)` | **综合查询状态（推荐）** |
+
+### 模态弹窗
+
+| 工具 | 说明 |
+|------|------|
+| `modal_detect(place_path/place_id)` | 检测模态弹窗 |
+| `modal_close(place_path/place_id)` | 关闭所有模态弹窗 |
+
+### 游戏控制
+
+| 工具 | 说明 |
+|------|------|
+| `game_start(place_path/place_id)` | 开始游戏 (F5) |
+| `game_stop(place_path/place_id)` | 停止游戏 (Shift+F5) |
+| `game_pause(place_path/place_id)` | 暂停/恢复游戏 (F12) |
+
+### 工具栏状态检测
+
+| 工具 | 说明 |
+|------|------|
+| `toolbar_state(place_path/place_id)` | 检测工具栏按钮状态和游戏状态 |
+| `toolbar_state_debug(place_path/place_id)` | 带调试信息的检测 |
+
+返回示例：
+```json
+{
+  "play": "enabled",
+  "pause": "disabled", 
+  "stop": "disabled",
+  "game_state": "stopped"
+}
+```
+
+`game_state` 可能的值：`stopped`, `running`, `paused`
+
+### 日志
+
+| 工具 | 说明 |
+|------|------|
+| `logs_get(place_path/place_id, after_line, before_line, timestamps)` | 获取日志 |
+| `logs_search(place_path/place_id, pattern, after_line, before_line, timestamps)` | 搜索日志（正则） |
+| `logs_clean(days)` | 清理旧日志 |
+
+**logs_get 参数：**
+```python
+logs_get(
+    place_path: str = None,      # 本地文件路径
+    place_id: int = None,        # 云端 Place ID（二选一）
+    after_line: int = None,      # 从哪一行之后开始读取
+    before_line: int = None,     # 到哪一行之前结束
+    timestamps: bool = False     # 是否附加时间戳 [HH:MM:SS]
+)
+```
+
+**logs_get 返回：**
+```json
+{
+  "logs": "[15:22:01] Hello world!\nThe MCP plugin is ready.",
+  "start_line": 100,
+  "last_line": 2330,
+  "remaining": 0,
+  "has_more": false
+}
+```
+
+**续读日志：**
+```python
+# 首次获取
+result = logs_get(place_path="D:/game.rbxl")
+# 续读新日志
+result = logs_get(place_path="D:/game.rbxl", after_line=result["last_line"])
+```
+
+### 截图
+
+| 工具 | 说明 |
+|------|------|
+| `screenshot(place_path/place_id)` | 截取主窗口 |
+| `screenshot_full(place_path/place_id)` | 截取窗口（包含模态弹窗） |
+
+---
+
+## 注意事项
+
+1. **支持本地和云端 Place** - 使用 `place_path` 或 `place_id` 参数
+2. **启动后务必查询状态** - 调用 `studio_query` 检查是否有模态弹窗
+3. **处理模态弹窗** - `ready=false` 时调用 `modal_close` 关闭弹窗
+4. **最小化窗口自动恢复** - 检测工具栏状态时会自动恢复最小化的窗口
+5. **自动清理** - 关闭本地文件的 Studio 后会自动清理 .lock 文件
+6. **日志过滤** - `logs_get` 自动过滤 Studio 内部日志，只返回用户脚本输出
+
+---
+
+## 技术说明
+
+- 会话管理通过扫描进程命令行 + 日志文件自动匹配
+- 日志索引缓存减少 IO 操作
+- 游戏控制使用 SendInput API（需短暂切换窗口焦点）
+- 截图使用 PrintWindow API（可捕获被遮挡窗口）
+- 模态弹窗检测通过枚举同进程窗口实现
+- 工具栏状态通过 OpenCV 模板匹配检测
+- 支持多显示器环境

roblox_studio_physical_operation_mcp-0.1.0/README.md

@@ -0,0 +1,246 @@
+# Roblox Studio MCP
+
+一个用于控制 Roblox Studio 的 MCP (Model Context Protocol) 服务。
+
+## 安装
+
+```bash
+pip install roblox-studio-physical-operation-mcp
+```
+
+## 配置 MCP
+
+### Claude Desktop
+
+编辑 `%APPDATA%\Claude\claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "roblox-studio": {
+      "command": "python",
+      "args": ["-m", "roblox_studio_physical_operation_mcp"]
+    }
+  }
+}
+```
+
+### Droid
+
+编辑 `~/.factory/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "roblox-studio": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "roblox_studio_physical_operation_mcp"]
+    }
+  }
+}
+```
+
+> **注意**：Windows Store 版 Python 可能需要使用完整路径：
+> ```json
+> "command": "C:\\Users\\<用户名>\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\\python.exe"
+> ```
+
+## 从源码安装
+
+```bash
+git clone https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp.git
+cd roblox-studio-physical-operation-mcp
+pip install -r requirements.txt
+python -m roblox_studio_physical_operation_mcp
+```
+
+---
+
+## AI 使用指南
+
+### ⚠️ 重要：获取 place_path 或 place_id
+
+**不知道 place_path 或 place_id 时，必须先调用 `studio_list()` 获取！**
+
+```python
+# 先获取当前运行的 Studio 实例
+instances = studio_list()
+# 返回示例:
+# [{"pid": 12345, "type": "local", "place_path": "D:/game.rbxl"},
+#  {"pid": 67890, "type": "cloud", "place_id": 110155533210141}]
+
+# 然后用返回的 place_path 或 place_id 操作
+logs_get(place_path=instances[0]["place_path"])
+```
+
+### 推荐工作流程
+
+**调试已打开的 Studio**
+```
+1. studio_list()               # 获取运行中的 Studio 实例
+2. studio_query(place_path)    # 查询状态
+3. modal_close(place_path)     # 如果有模态弹窗，关闭它们
+4. game_start(place_path)      # 开始游戏
+5. logs_get(place_path)        # 获取日志
+6. game_stop(place_path)       # 停止游戏
+```
+
+**打开新的 Studio**
+```
+1. studio_open(place_path)     # 打开 Studio（本地文件）
+2. studio_query(place_path)    # 查询状态
+3. modal_close(place_path)     # 如果有模态弹窗，关闭它们
+4. studio_query(place_path)    # 确认 ready=true
+5. game_start(place_path)      # 开始游戏
+6. logs_get(place_path)        # 获取日志
+7. game_stop(place_path)       # 停止游戏
+8. studio_close(place_path)    # 关闭 Studio
+```
+
+### 支持两种 Place 类型
+
+所有工具都支持两种参数（二选一）：
+- `place_path` - 本地 .rbxl 文件路径
+- `place_id` - 云端 Roblox Place ID
+
+```python
+# 本地文件
+logs_get(place_path="D:/game.rbxl")
+
+# 云端 Place（从网页打开的）
+logs_get(place_id=110155533210141)
+```
+
+### studio_query 返回值说明
+
+```json
+{
+  "active": true,       // Studio 是否运行中
+  "ready": true,        // 是否就绪（无模态弹窗）
+  "pid": 12345,         // 进程 ID
+  "hwnd": 67890,        // 主窗口句柄
+  "has_modal": false,   // 是否有模态弹窗
+  "modal_count": 0,     // 模态弹窗数量
+  "modals": []          // 模态弹窗详情
+}
+```
+
+**重要**: `ready=true` 时才能正常操作 Studio。
+
+---
+
+## 工具列表
+
+### 系统工具
+
+| 工具 | 说明 |
+|------|------|
+| `studio_help()` | 获取使用指南 |
+| `studio_list()` | **列出所有运行中的 Studio 实例** |
+| `studio_open(place_path)` | 打开 Studio 并加载 .rbxl 文件 |
+| `studio_close(place_path/place_id)` | 关闭 Studio |
+| `studio_status(place_path/place_id)` | 获取基本状态 |
+| `studio_query(place_path/place_id)` | **综合查询状态（推荐）** |
+
+### 模态弹窗
+
+| 工具 | 说明 |
+|------|------|
+| `modal_detect(place_path/place_id)` | 检测模态弹窗 |
+| `modal_close(place_path/place_id)` | 关闭所有模态弹窗 |
+
+### 游戏控制
+
+| 工具 | 说明 |
+|------|------|
+| `game_start(place_path/place_id)` | 开始游戏 (F5) |
+| `game_stop(place_path/place_id)` | 停止游戏 (Shift+F5) |
+| `game_pause(place_path/place_id)` | 暂停/恢复游戏 (F12) |
+
+### 工具栏状态检测
+
+| 工具 | 说明 |
+|------|------|
+| `toolbar_state(place_path/place_id)` | 检测工具栏按钮状态和游戏状态 |
+| `toolbar_state_debug(place_path/place_id)` | 带调试信息的检测 |
+
+返回示例：
+```json
+{
+  "play": "enabled",
+  "pause": "disabled", 
+  "stop": "disabled",
+  "game_state": "stopped"
+}
+```
+
+`game_state` 可能的值：`stopped`, `running`, `paused`
+
+### 日志
+
+| 工具 | 说明 |
+|------|------|
+| `logs_get(place_path/place_id, after_line, before_line, timestamps)` | 获取日志 |
+| `logs_search(place_path/place_id, pattern, after_line, before_line, timestamps)` | 搜索日志（正则） |
+| `logs_clean(days)` | 清理旧日志 |
+
+**logs_get 参数：**
+```python
+logs_get(
+    place_path: str = None,      # 本地文件路径
+    place_id: int = None,        # 云端 Place ID（二选一）
+    after_line: int = None,      # 从哪一行之后开始读取
+    before_line: int = None,     # 到哪一行之前结束
+    timestamps: bool = False     # 是否附加时间戳 [HH:MM:SS]
+)
+```
+
+**logs_get 返回：**
+```json
+{
+  "logs": "[15:22:01] Hello world!\nThe MCP plugin is ready.",
+  "start_line": 100,
+  "last_line": 2330,
+  "remaining": 0,
+  "has_more": false
+}
+```
+
+**续读日志：**
+```python
+# 首次获取
+result = logs_get(place_path="D:/game.rbxl")
+# 续读新日志
+result = logs_get(place_path="D:/game.rbxl", after_line=result["last_line"])
+```
+
+### 截图
+
+| 工具 | 说明 |
+|------|------|
+| `screenshot(place_path/place_id)` | 截取主窗口 |
+| `screenshot_full(place_path/place_id)` | 截取窗口（包含模态弹窗） |
+
+---
+
+## 注意事项
+
+1. **支持本地和云端 Place** - 使用 `place_path` 或 `place_id` 参数
+2. **启动后务必查询状态** - 调用 `studio_query` 检查是否有模态弹窗
+3. **处理模态弹窗** - `ready=false` 时调用 `modal_close` 关闭弹窗
+4. **最小化窗口自动恢复** - 检测工具栏状态时会自动恢复最小化的窗口
+5. **自动清理** - 关闭本地文件的 Studio 后会自动清理 .lock 文件
+6. **日志过滤** - `logs_get` 自动过滤 Studio 内部日志，只返回用户脚本输出
+
+---
+
+## 技术说明
+
+- 会话管理通过扫描进程命令行 + 日志文件自动匹配
+- 日志索引缓存减少 IO 操作
+- 游戏控制使用 SendInput API（需短暂切换窗口焦点）
+- 截图使用 PrintWindow API（可捕获被遮挡窗口）
+- 模态弹窗检测通过枚举同进程窗口实现
+- 工具栏状态通过 OpenCV 模板匹配检测
+- 支持多显示器环境

roblox_studio_physical_operation_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roblox-studio-physical-operation-mcp"
+version = "0.1.0"
+description = "MCP server for controlling Roblox Studio - toolbar detection, game control, log analysis"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "White Dragon Tools" }
+]
+keywords = [
+    "mcp",
+    "roblox",
+    "roblox-studio",
+    "model-context-protocol",
+    "automation"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "pillow",
+    "opencv-python",
+    "pywin32",
+]
+
+[project.urls]
+Homepage = "https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp"
+Repository = "https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp"
+Issues = "https://github.com/white-dragon-tools/roblox-studio-physical-operation-mcp/issues"
+
+[project.scripts]
+roblox-studio-physical-operation-mcp = "roblox_studio_physical_operation_mcp:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["roblox_studio_physical_operation_mcp"]
+
+[tool.hatch.build.targets.wheel.shared-data]
+"roblox_studio_physical_operation_mcp/templates" = "roblox_studio_physical_operation_mcp/templates"

roblox_studio_physical_operation_mcp-0.1.0/requirements.txt

@@ -0,0 +1,9 @@
+# MCP 服务核心依赖
+mcp>=1.0.0
+pillow
+opencv-python
+pywin32
+
+# 可选：测试依赖
+# dxcam
+# mss

roblox_studio_physical_operation_mcp-0.1.0/roblox_studio_physical_operation_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""
+Roblox Studio MCP 服务
+
+提供以下功能:
+- 游戏控制: start_game, stop_game, pause_resume_game
+- 日志分析: get_recent_logs, search_logs_by_pattern
+- 视觉捕获: capture_screenshot, start_recording, stop_recording
+- 系统工具: get_studio_status, clean_logs, open_place, close_place
+"""
+
+from .server import mcp, main
+
+__all__ = ["mcp", "main"]

roblox_studio_physical_operation_mcp-0.1.0/roblox_studio_physical_operation_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""
+Roblox Studio MCP 入口
+"""
+
+from roblox_studio_physical_operation_mcp import main
+
+if __name__ == "__main__":
+    main()