# GameMaker MCP Pro

## What
MCP server for AI-powered runtime debugging, testing, and inspection of GameMaker games. 123 tools across 20 categories.

## Architecture
AI Client <-> Node.js MCP Server (stdio) <-> GameMaker GML Extension (TCP/JSON-RPC 2.0)

## Key Features
- Runtime inspection: instances, variables, layers, rooms
- Screenshot capture: game screen, GUI, surfaces
- Input simulation: keyboard, mouse, gamepad
- Game control: pause, resume, step frame, speed control
- Performance profiling: FPS, memory, step timing
- GML execution: run code dynamically

## Requirements
- GameMaker 2024.2+
- Node.js 18+
- MCP-compatible AI client (Claude Code, Cursor, VS Code)

## Install
1. npm install && npm run build (server/)
2. Copy GML scripts + obj_mcp_server to GameMaker project
3. Configure MCP client to point to server/build/index.js

## Auto-disable
Uses #macro MCP_ENABLED with Debug config - zero overhead in release builds.

## Port
Default: 6705 (configurable via GAMEMAKER_MCP_PORT env var)

## Tool Categories (123 total)
- Project (6): get_project_info, get_resource_tree, search_resources, get_room_order, get_config_info, get_resource_count
- Instance (10): get_all_instances, get_instance_info, find_instances_by_object, get_instance_variables, set_instance_variable, create_instance, destroy_instance, move_instance, get_instance_count, find_nearest_instance
- Room (7): get_current_room, get_room_info, goto_room, restart_room, get_room_instances, get_room_list, room_get_viewport
- Variable (8): get_global_variables, set_global_variable, get_instance_variable_value, set_instance_variable_value, get_built_in_variables, evaluate_expression, watch_variable, get_variable_type
- Debug (7): get_fps, get_memory_usage, get_draw_calls, get_step_time, show_debug_overlay, get_error_log, execute_gml
- Input (7): simulate_key_press, simulate_key_release, simulate_mouse_move, simulate_mouse_click, simulate_mouse_wheel, simulate_gamepad, simulate_input_sequence
- Screenshot (6): get_game_screenshot, get_gui_screenshot, get_surface_screenshot, compare_screenshots, start_recording, stop_recording
- Audio (6): get_playing_sounds, play_sound, stop_sound, set_sound_volume, get_audio_info, stop_all_sounds
- Layer (6): get_layers, get_layer_instances, get_layer_elements, set_layer_visible, set_layer_depth, get_layer_info
- Tilemap (6): get_tilemap_data, set_tilemap_cell, get_tilemap_info, clear_tilemap, get_tileset_info, fill_tilemap_region
- Camera (6): get_camera_info, set_camera_position, set_camera_size, camera_shake, follow_instance, get_view_info
- Surface (5): list_surfaces, get_surface_info, capture_surface, create_surface, free_surface
- Particle (6): get_particle_systems, create_particle_system, create_particle_type, emit_particles, get_particle_count, clear_particles
- Physics (6): get_physics_info, apply_force, apply_impulse, set_physics_properties, get_fixtures, raycast
- Data Structures (6): inspect_ds_list, inspect_ds_map, inspect_ds_grid, inspect_ds_stack, inspect_array, inspect_struct
- Game Control (6): pause_game, resume_game, set_game_speed, restart_game, get_game_state, step_frame
- Alarm (4): get_alarms, set_alarm, get_all_alarms, cancel_alarm
- Animation (6): get_sprite_info, set_sprite_index, set_image_index, set_image_speed, get_animation_state, set_image_properties
- Collision (5): check_collision_point, check_collision_rectangle, check_collision_line, get_collision_mask, find_collisions
- Profiling (5): get_performance_stats, start_profiling, stop_profiling, get_profiling_report, get_texture_page_info

## Protocol
JSON-RPC 2.0 over TCP. Default request timeout: 5000ms. All responses include success boolean and data/error fields.

## Security
- Debug config only (MCP_ENABLED macro)
- Local connections only (127.0.0.1)
- No authentication required (local dev tool)
- Auto-disables in release builds with zero overhead