================================================================================
                    SCARTOOLKIT MCP INTEGRATION GUIDE
                    Model Context Protocol for Claude
================================================================================

OVERVIEW
--------
ScarToolkit includes an embedded HTTP REST API server that allows Claude (via MCP)
to remotely execute Lua scripts, manage saved scripts, and monitor game state in
Age of Empires IV.

The MCP server acts as a bridge between Claude Code and ScarToolkit.

Port: 52737 (localhost)


================================================================================
PART 1: QUICK START (5 Minutes)
================================================================================

REQUIREMENTS:
- ScarToolkit installed
- Node.js v18+ installed (https://nodejs.org)
- Claude Code CLI installed (https://claude.ai/code)

STEP 1: Open Command Prompt in ScarToolkit folder
-------------------------------------------------
Navigate to where ScarToolkit.exe is located.

STEP 2: Install MCP Server Dependencies (First Time Only)
---------------------------------------------------------
cd mcp-server
npm install

STEP 3: Start ScarToolkit
-------------------------
Run ScarToolkit.exe

STEP 4: Open Claude Code in ScarToolkit folder
----------------------------------------------
In Command Prompt, from the ScarToolkit folder:

claude

STEP 5: Verify Connection
-------------------------
In Claude, type:  /mcp
You should see "scartoolkit" listed as connected.

The MCP indicator in ScarToolkit (Custom Scripts tab) should turn GREEN.

DONE! You can now ask Claude to execute Lua scripts in your game.


================================================================================
PART 2: EXAMPLE COMMANDS FOR CLAUDE
================================================================================

Once connected, try these prompts:

CHECKING STATUS:
- "Check if the game is running"
- "Is SCAR ready?"
- "Get the current game status"

EXECUTING SCRIPTS:
- "Give me 10000 of each resource"
- "Spawn 5 villagers at my location"
- "Reveal the entire map"
- "Run the AI sheep collection script"

MANAGING SCRIPTS:
- "List all my saved scripts"
- "Load and show me the Game Over overlay script"
- "Save this as 'my_cheat.lua': [paste your code]"
- "Delete the test script"

WAITING FOR GAME:
- "Wait until I'm in a match, then give me resources"
- "Execute this script when SCAR is ready: [code]"


================================================================================
PART 3: AVAILABLE MCP TOOLS
================================================================================

Claude has access to these tools:

1. get_status
   Returns: gameAttached, scarState, scarReady, mcpConnected

2. execute_lua
   Parameters: code (required), mode ("safe" or "raw")
   Executes Lua/SCAR script in the game

3. debug_lua
   Parameters: code (required)
   Executes with debug overlay visible

4. list_scripts
   Returns list of saved .lua scripts

5. load_script
   Parameters: name (script filename)
   Returns script content

6. save_script
   Parameters: name, content
   Saves a new script

7. delete_script
   Parameters: name
   Deletes a script

8. wait_for_scar
   Parameters: timeout_seconds (optional)
   Waits until game match is loaded and ready

9. get_editor
   Returns current content of the script text editor

10. set_editor
    Parameters: content
    Sets/replaces the script text editor content


================================================================================
PART 4: DIRECT HTTP API (Advanced)
================================================================================

You can also access the API directly without Claude:

BASE URL: http://localhost:52737

ENDPOINTS:
GET  /status              - Get game/connection status
POST /heartbeat           - Keep connection alive
POST /execute?mode=safe   - Execute Lua (body = code)
POST /execute?mode=raw    - Execute Lua without error wrapper
POST /debug               - Execute with debug overlay
GET  /scripts             - List saved scripts
GET  /scripts/{name}      - Get script content
POST /scripts/{name}      - Save script (body = content)
DELETE /scripts/{name}    - Delete script
GET  /editor              - Read editor content
POST /editor              - Set editor content (body = code)

CURL EXAMPLES:

# Check status
curl http://localhost:52737/status

# Execute Lua script
curl -X POST http://localhost:52737/execute -d "print('Hello')"

# List scripts
curl http://localhost:52737/scripts


================================================================================
PART 5: CONNECTING FROM ANOTHER COMPUTER
================================================================================

By default, ScarToolkit only accepts connections from localhost for security.

OPTION A: SSH Tunnel (Recommended)
----------------------------------
On the remote computer, create a tunnel:

ssh -L 52737:localhost:52737 user@scartoolkit-pc

Then use Claude Code normally - it connects to localhost:52737 which tunnels
to the remote ScarToolkit.

OPTION B: Network Access (Less Secure)
--------------------------------------
Requires modifying ScarToolkit source code to listen on 0.0.0.0 instead of
127.0.0.1. Contact the developer for a network-enabled build.

If enabled:
1. Allow port 52737 through Windows Firewall
2. Edit mcp-server/dist/index.js and change localhost to the PC's IP address
3. Rebuild the MCP server


================================================================================
PART 6: TROUBLESHOOTING
================================================================================

PROBLEM: MCP indicator stays RED
--------------------------------
- Make sure ScarToolkit.exe is running
- Make sure you ran "npm install" in the mcp-server folder
- Restart Claude Code from the ScarToolkit folder
- Check if port 52737 is in use: netstat -an | findstr 52737

PROBLEM: "Game not attached" errors
-----------------------------------
- Start Age of Empires IV
- Wait for ScarToolkit status bar to show "Attached"

PROBLEM: "SCAR not ready" errors
--------------------------------
- You must be IN A GAME MATCH (not main menu)
- Wait for the match to fully load
- Use the wait_for_scar tool to automatically wait

PROBLEM: Claude doesn't see scartoolkit in /mcp
-----------------------------------------------
- Make sure you opened Claude from the ScarToolkit folder
- Check that .mcp.json file exists in the folder
- Check that mcp-server/dist/index.js exists

PROBLEM: "npm install" fails
----------------------------
- Make sure Node.js is installed: node --version
- Try running as Administrator
- Delete node_modules folder and try again


================================================================================
PART 7: FILE STRUCTURE
================================================================================

Your ScarToolkit folder should contain:

ScarToolkit/
├── ScarToolkit.exe           # Main application
├── .mcp.json                 # Claude MCP configuration
├── MCP_INTEGRATION_GUIDE.txt # This file
├── mcp-server/               # MCP bridge server
│   ├── package.json
│   ├── dist/
│   │   └── index.js          # Compiled server
│   └── node_modules/         # (created by npm install)
└── lua_scripts/              # Your saved Lua scripts
    └── *.lua


================================================================================
PART 8: SECURITY NOTES
================================================================================

- The HTTP API has NO authentication
- Only localhost connections are accepted by default
- The API can execute ANY Lua code in the game
- Do not expose port 52737 to untrusted networks
- Use SSH tunnels for remote access


================================================================================
PART 9: INSTRUCTIONS FOR AI/CLAUDE (IMPORTANT!)
================================================================================

If you are an AI (Claude, GPT, Codex, etc.) reading this guide, follow these
critical instructions:

*** YOU CANNOT SEE THE GAME SCREEN ***

After executing ANY script, you MUST:
1. STOP and wait for the user to confirm if it worked
2. ASK the user: "Did that work? What do you see in-game?"
3. DO NOT assume the script executed correctly just because API returned success
4. DO NOT chain multiple scripts without user verification between each one

The API only confirms the script was SENT to the game - it does NOT confirm:
- The script ran without Lua errors
- The expected effect happened in-game
- The game state changed as intended

CORRECT WORKFLOW:
-----------------
User: "Give me 1000 gold"
You:  *execute script*
You:  "I've sent the script to add 1000 gold. Did your gold increase in-game?"
User: "Yes it worked!"
You:  "Great! What else would you like?"

WRONG WORKFLOW (DO NOT DO THIS):
--------------------------------
User: "Give me resources and reveal map"
You:  *execute both scripts* "Done! I gave you resources and revealed the map."

This is WRONG because you cannot verify either action worked!

REMEMBER: You are BLIND to the game. The user is your eyes.
Always verify with them after executing scripts.


================================================================================
PART 10: COMMON LUA/SCAR FUNCTIONS REFERENCE
================================================================================

PLAYER REFERENCE:
-----------------
local player = World_GetPlayerAt(1)  -- Get local player

RESOURCES:
----------
Player_AddResource(player, RT_Food, 1000)
Player_AddResource(player, RT_Wood, 1000)
Player_AddResource(player, RT_Gold, 1000)
Player_AddResource(player, RT_Stone, 1000)

Resource types: RT_Food, RT_Wood, RT_Gold, RT_Stone

MAP:
----
FOW_RevealAll()  -- Reveal entire map

UNITS:
------
-- Spawn units at marker or position
UnitEntry_SpawnSquadsInWorld(player, sbp, target, count, pop)

UI MESSAGES:
------------
UI_CreateEventCue(
    "Title Text",
    "Description text",
    "sfx_ui_event_queue_high_priority_play",
    "",
    "low_priority"
)

STATUS RESPONSE FIELDS:
-----------------------
{
  "gameAttached": true,    // Is AoE4 process found
  "scarState": 3,          // 3 = ready for scripts
  "scarReady": true,       // Shorthand for scarState == 3
  "mcpConnected": true     // MCP heartbeat active
}


================================================================================
QUICK REFERENCE CARD
================================================================================

START:
1. Run ScarToolkit.exe
2. Open terminal in ScarToolkit folder
3. Type: claude
4. Verify: /mcp shows "scartoolkit"

ASK CLAUDE:
- "Check game status"
- "Give me 50000 gold"
- "List my scripts"
- "Run [script name]"
- "Save this script as [name]: [code]"

STATUS INDICATOR:
- GREEN = Connected
- RED = Disconnected (restart Claude from ScarToolkit folder)

AI REMINDER:
- Always ask user to verify after executing scripts
- You cannot see the game screen
- Wait for user confirmation before continuing

================================================================================
