AI-native testing bridge // open.mp + SA-MP

MCPON MY SAMP

A Model Context Protocol bridge that lets an AI agent start, drive, and verify a local open.mp / SA-MP server through a headless RakClient — 77 tools over stdio. Testable. Local. Verifiable.

View on GitHub How it works

mcponmysamp — local bridge · stdio

AI agent ──MCP stdio──► bridge ──► open.mp server

└── RakClient ⇄ UDP 127.0.0.1 ──┘

$ mcp-gta-samp — waiting for MCP request

scroll

// How it works

Four layers. One local loop.

Keep scrolling — the bridge stacks itself, layer by layer.

Layer 01

MCP

Connect

Your agent speaks standard Model Context Protocol over stdio — no plugins, no gateways, no cloud. Claude, Cursor, or any MCP client works.

MCPstdioAI agent

Layer 02

RakClient

Bridge

A headless RakClient joins your local open.mp / SA-MP server over UDP loopback — a real game client, with no window and no desktop footprint.

RakClientUDP 127.0.0.1headless

Layer 03

spawn-gated

Control

Commands are spawn-gated and checked against an allowlist parsed from your Pawn source. Flood, spam, lag injection, and arbitrary RCON: off the table.

spawn-gatedPawn allowlistno arbitrary RCON

Layer 04

round-trip

Verify

Every command is an evidence-based round-trip: sent, received by the gamemode callback, answered by the server, then asserted by the bridge.

round-tripassertionevidence

// 3D Architecture Core

MCP Stdio Protocol Node

Representasi visual model 3D inti server MCP. Mengontrol bridge I/O stream secara terisolasi tanpa latency external.

Icosahedron Core: ActiveTransport: Stdio

// Headless RakClient Orbit

Local UDP 127.0.0.1 Synchronizer

Ring data luar merepresentasikan koneksi headless RakClient yang terhubung langsung ke port SA-MP/open.mp via UDP loopback lokal.

Zero-Window DaemonSpawn-Gated GID

// State Inspector

Live Telemetry & Assertion Vector

Setiap putaran rotasi memproses 77+ tool events secara real-time: textdraws, vehicle physics, body heading, dan dialog capture.

77 RPC Tool VectorsDeterministic Assertion

// Realtime Visual Observer

Virtual Game Frame Interceptor

Off-screen visual window renderer yang mengekstrak bukti frame game PrintWindow lossless secara simultan ke agent AI.

PrintWindow PNGOff-Screen Sandbox

// Features

Built for evidence, not vibes

Everything the bridge does — and nothing it won't. Local servers only, proof in every response.

LIFECYCLE

Full lifecycle

server_start, server_status, server_stop — plus a matching start / status / stop lifecycle for the headless RakClient.

ALLOWLIST

Spawn-gated dispatch

Slash commands are gated until the bot is Spawned, then checked against an allowlist parsed straight from your Pawn source.

ASSERTION

Evidence round-trip

Every command is sent, received by the gamemode callback, answered, and asserted by the bridge. No blind assumptions.

OBSERVER

Visual observer

Run a real rendered client parked off-screen and capture PNG screenshots of the game window via PrintWindow.

// MCP Tools

77 tools. One bridge.

Lifecycle, driving, dialog and textdraw awareness, key sequences, world scanning — and a visual observer that screenshots a real rendered client.

Server

5 tools

server_startserver_statusserver_stopserver_list_commandsserver_assert_command

Client

6 tools

client_startclient_statusclient_stopclient_send_chatclient_get_historyclient_assert_output

Bot · Movement

19 tools

bot_walk_tobot_stopbot_teleportbot_face_headingbot_face_pointbot_jumpbot_key_holdbot_key_releasebot_key_sequencebot_firebot_enter_vehiclebot_exit_vehiclebot_vehicle_drivebot_vehicle_hornbot_set_velocitybot_animationbot_play_animationbot_list_animationsbot_dialog

Bot · World

18 tools

bot_click_textdrawbot_scan_textdrawsbot_wait_for_textdrawbot_get_checkpointbot_goto_checkpointbot_target_entitybot_scan_textlabelsbot_scan_pickupsbot_scan_objectsbot_pickup_pickupbot_scan_playersbot_scan_players_detailbot_scan_vehiclesbot_scan_vehicles_detailbot_wait_for_chatbot_wait_for_messagebot_wait_for_dialogbot_wait_for_player

Bot · State

24 tools

bot_get_positionbot_get_rotationbot_get_vehiclebot_get_healthbot_get_weaponbot_get_moneybot_get_nickbot_get_interiorbot_get_camerabot_get_keysbot_get_serverbot_get_server_infobot_get_statebot_is_walkingbot_pingbot_send_chatbot_send_commandbot_set_nickbot_respawnbot_reconnectbot_vehicle_healthbot_vehicle_positionbot_vehicle_velocitybot_vehicle_speed

Observer

4 tools

observer_startobserver_screenshotobserver_statusobserver_stop

// The agent loop

Boot. Join.
Send. Assert.

The reference workflow an agent follows. Boot is not proof, and neither is joining or spawning — only an asserted round-trip counts.

01server_status# is the server up?

02server_start# boot if not running

03client_start# headless RakClient joins

04await Spawned# spawn-gated dispatch

05server_list_commands# allowlist from Pawn source

06server_assert_command("/help")# validate against allowlist

07client_send_chat("/help")# send the command

08client_assert_output("MCP Test Commands:")# assert round-trip response

09client_get_history# diagnose if needed

10client_stop# teardown client

11server_stop# done

✓done — repeat with the next test case

MCP tools

step agent loop

layers, one bridge

% local & verifiable

// Quickstart

Up in five commands

Windows, Linux, macOS — Python 3.10+. The bridge speaks stdio, so wire it into Claude, Cursor, or any MCP client.

local-server.json → mcp-gta-samp

# 1 · clone + venv
git clone https://github.com/marhenrik635-oss/mcponmysamp.git
cd mcponmysamp
py -3 -m venv .venv
.venvScriptsactivate
python -m pip install ".[dev]"

# 2 · run the bridge (stdio)
mcp-gta-samp --config local-server.json   --client-executable D:/Games/RakClient/rakclient.exe   --client-arg --server --client-arg 127.0.0.1:7777   --client-arg --nick --client-arg MCPBot

No cloud. No API key.

Everything runs against localhost. The bridge never touches a public server, and ships no game binaries — point it at your own open.mp install.

Config is yours

Copy config.example.json → local-server.json, set your executable paths, and let the agent do the rest.

MIT licensed

Free to use, fork, and extend. Built as an AI-native integration testing foundation for SA-MP / open.mp.