Opm MCP Server

OpenMOHAA MCP服务器

一个完整的模型上下文协议（MCP）服务器，用于在Linux上自动化、测试和控制OpenMOHAA。

特性

• 游戏生命周期控制：启动、停止、重新启动和终止OpenMOHAA
• 控制台交互：发送命令、读取输出、管理cvar
• UI自动化：鼠标移动、点击、键盘输入
• 屏幕截图：截图、像素采样、图像匹配
• 测试自动化：使用条件和断言运行脚本测试序列
• 构建系统：从源代码克隆、配置、编译和打包OpenMOHAA
• 演示管理：录制、播放、暂停、查找和管理演示文件
• 组态管理：读取、写入、解析、备份和验证配置文件
• 服务器管理：通过RCON启动、停止、查询和控制专用服务器
• 性能监控：跟踪FPS、内存、CPU/GPU使用情况，运行基准测试
• 日志分析：解析、搜索和分析游戏和服务器日志
• 脚本验证：使用mfuse_exec验证Morpheus脚本

需求

系统要求

• Linux（Ubuntu、Arch或兼容）
• Node.js 18+
• X11或Wayland显示服务器

依赖项

安装所需的系统包：

# Ubuntu/Debian
sudo apt install xdotool imagemagick x11-utils scrot

# Arch Linux
sudo pacman -S xdotool imagemagick xorg-xprop xorg-xwininfo scrot

# For Wayland support (optional)
sudo apt install ydotool grim

安装

# Clone or copy the repository
cd opm-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

添加到您的MCP客户端配置中（例如，VS Code MCP.json）：

{
  "servers": {
    "openmohaa": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/opm-mcp/dist/index.js"],
      "env": {
        "OPENMOHAA_EXEC_PATH": "/path/to/openmohaa",
        "OPENMOHAA_GAME_DIR": "/path/to/game/directory",
        "OPENMOHAA_MFUSE_EXEC_PATH": "/path/to/mfuse_exec",
        "OPENMOHAA_COMMANDS_LIST_PATH": "/path/to/commands.txt"
      }
    }
  }
}

环境变量

您可以通过以下方式检查配置的默认值 openmohaa_get_defaults.

用法

基本游戏控制

Launch OpenMOHAA

（用途 OPENMOHAA_EXEC_PATH 从env或显式传递路径）

Send command "map dm/mohdm1" to the game

Take a screenshot of the game window

可用工具

游戏生命周期

• openmohaa_launch -启动游戏（如果没有指定路径，则使用OPENMOHAA_EXC_PATH）
• openmohaa_stop -优雅地停下
• openmohaa_restart -重新开始游戏
• openmohaa_kill -武力杀戮
• openmohaa_status -获取进程状态
• openmohaa_get_defaults -获取配置的默认路径

控制台命令

• openmohaa_send_command -发送任何控制台命令
• openmohaa_set_cvar -设置控制台变量
• openmohaa_get_cvar -获取控制台变量
• openmohaa_exec_config -执行配置文件
• openmohaa_load_map -加载地图
• openmohaa_get_console_output -读取控制台输出

鼠标控制

• openmohaa_mouse_move -移动鼠标光标
• openmohaa_mouse_click -单击鼠标按钮
• openmohaa_mouse_drag -拖动鼠标
• openmohaa_scroll -滚动鼠标滚轮

键盘控制

• openmohaa_type_text -键入文本
• openmohaa_press_key -按一个键
• openmohaa_key_combo -按组合键

窗口控件

• openmohaa_focus_window -聚焦游戏窗口
• openmohaa_find_window -查找窗口信息
• openmohaa_toggle_console -切换游戏内控制台

屏幕截图

• openmohaa_screenshot -截图
• openmohaa_get_pixel -获取像素颜色
• openmohaa_check_pixel -验证像素颜色
• openmohaa_find_image -在屏幕上查找图像

等待和条件

• openmohaa_wait -等待时间
• openmohaa_wait_for_console -等待控制台文本
• openmohaa_wait_for_pixel -等待像素颜色
• openmohaa_wait_for_image -等待图像

自动化

• openmohaa_run_script -运行自动化脚本
• openmohaa_create_map_test -创建地图负载测试

公用事业

• openmohaa_check_dependencies -检查系统依赖关系
• openmohaa_get_screen_resolution -获取屏幕分辨率
• openmohaa_get_display_server -获取显示服务器类型

构建系统

• openmohaa_build_check_tools -检查构建工具是否可用
• openmohaa_build_clone -克隆或更新存储库
• openmohaa_build_configure -使用CMake进行配置
• openmohaa_build_compile -构建项目
• openmohaa_build_clean -清理构建目录
• openmohaa_build_status -获取构建状态
• openmohaa_build_cancel -取消当前构建
• openmohaa_build_git_info -获取git信息
• openmohaa_build_run_tests -运行CTest测试
• openmohaa_build_package -创建发布包

演示管理

• openmohaa_demo_start_recording -开始录制
• openmohaa_demo_stop_recording -停止录制
• openmohaa_demo_play -播放演示
• openmohaa_demo_stop -停止播放
• openmohaa_demo_list -列出所有演示
• openmohaa_demo_delete -删除演示
• openmohaa_demo_rename -重命名演示
• openmohaa_demo_pause -暂停播放
• openmohaa_demo_resume -恢复播放
• openmohaa_demo_set_speed -设置播放速度
• openmohaa_demo_seek -寻求时间
• openmohaa_demo_cleanup -清理旧演示
• openmohaa_demo_set_dir -设置演示目录

组态管理

• openmohaa_config_read -读取配置文件
• openmohaa_config_write -写入配置文件
• openmohaa_config_list -列出配置文件
• openmohaa_config_parse -将配置解析为结构化数据
• openmohaa_config_get_autoexec -获取autoexec.cfg
• openmohaa_config_set_cvar -在autoexec中设置cvar
• openmohaa_config_set_bind -在autoexec中设置键绑定
• openmohaa_config_backup -备份配置
• openmohaa_config_restore -从备份还原
• openmohaa_config_validate -验证配置语法
• openmohaa_config_graphics_preset -应用图形预设
• openmohaa_config_set_game_dir -设置游戏目录

服务器管理

• openmohaa_server_start -启动专用服务器
• openmohaa_server_stop -停止服务器
• openmohaa_server_restart -重新启动服务器
• openmohaa_server_status -获取服务器状态
• openmohaa_server_rcon -发送RCON命令
• openmohaa_server_query -通过UDP查询服务器
• openmohaa_server_output -获取服务器输出
• openmohaa_server_change_map -更改地图
• openmohaa_server_kick -踢球运动员
• openmohaa_server_say -发送服务器消息

性能监控

• openmohaa_perf_start -开始监控
• openmohaa_perf_stop -停止监控
• openmohaa_perf_collect -收集指标
• openmohaa_perf_stats -获取统计数据
• openmohaa_perf_benchmark -运行基准测试
• openmohaa_perf_check_issues -检查问题
• openmohaa_perf_export_csv -导出到CSV
• openmohaa_perf_clear -清除样本

日志分析

• openmohaa_log_list -列出日志文件
• openmohaa_log_parse -解析日志文件
• openmohaa_log_stats -获取日志统计信息
• openmohaa_log_search -搜索日志
• openmohaa_log_errors -获取错误
• openmohaa_log_kills -解析kill事件
• openmohaa_log_sessions -分析玩家会话
• openmohaa_log_tail -获取最后N行
• openmohaa_log_watch -关注新条目
• openmohaa_log_unwatch -别看了
• openmohaa_log_summary -生成摘要
• openmohaa_log_set_dir -设置日志目录

脚本验证

• openmohaa_script_validate_file -验证Morpheus脚本文件
• openmohaa_script_validate_content -验证脚本内容
• openmohaa_script_validate_files -验证多个脚本文件
• openmohaa_script_validator_status -获取验证器状态
• openmohaa_script_set_mfuse_path -设置mfuse_exec路径
• openmohaa_script_set_commands_list -设置commands.txt路径

自动化脚本

创建自动化测试序列：

{
  "name": "Load Map Test",
  "description": "Test map loading",
  "setup": [
    {
      "action": "launch",
      "params": {
        "executablePath": "/path/to/openmohaa",
        "windowed": true,
        "width": 1280,
        "height": 720
      }
    }
  ],
  "steps": [
    { "action": "wait", "params": { "ms": 5000 } },
    { "action": "toggle_console", "params": {} },
    { "action": "type", "params": { "text": "map dm/mohdm1" } },
    { "action": "press_key", "params": { "key": "enter" } },
    { 
      "action": "wait_for_console", 
      "params": { "pattern": "loaded", "timeout": 60000 } 
    },
    { "action": "screenshot", "params": { "path": "/tmp/map_test.png" } }
  ],
  "teardown": [
    { "action": "command", "params": { "command": "quit" } }
  ]
}

发展

# Run in development mode
npm run dev

# Type check
npm run typecheck

# Run tests
npm test

建筑

src/
  index.ts            # MCP server entry point (106 tools)
  types.ts            # Type definitions
  launcher.ts         # Process control module
  console-manager.ts  # Console interaction
  ui-controller.ts    # Mouse/keyboard automation
  screen-capture.ts   # Screenshot and image matching
  automation.ts       # Test automation framework
  build-system.ts     # Build system integration
  demo-manager.ts     # Demo recording/playback
  config-manager.ts   # Config file management
  server-manager.ts   # Dedicated server control
  performance-monitor.ts # Performance tracking
  log-analyzer.ts     # Log parsing and analysis
  script-validator.ts # Morpheus script validation

故障排除

缺少的依赖

跑 openmohaa_check_dependencies 查看缺少哪些系统工具。

未找到窗口

• 确保游戏正在运行
• 检查窗口标题是否匹配（默认：“OpenMOHAA”）
• 尝试在X11而不是Wayland上运行，以获得更好的兼容性

控制台命令不起作用

• 确保控制台已启用(+set con_enable 1)
• 在发送命令之前尝试使用控制台切换

许可证

麻省理工学院