Mcponmysamp

AI-native testing bridge untuk server open.mp / SA-MP lokal.

M8ven Score

Gunakan hanya untuk server lokal atau server yang kamu miliki / izinkan. Bukan tool public-server automation.

Fitur

• Lifecycle open.mp: start, status, stop.
• Lifecycle headless RakClient: start, status, stop.
• Spawn-gated command dispatch.
• Command allowlist dari source Pawn.
• Client history dan response assertion.
• Evidence-based command round-trip.

Tidak menyediakan flood, spam, lag injection, arbitrary RCON, atau automation server publik.

Alur kerja

AI agent
  │ MCP stdio
  ▼
MCP on My SAMP ──► open.mp server
        │              ▲
        └── RakClient ─┘ UDP lokal

Bukti valid:

command dikirim
→ server callback menerima command
→ gamemode mengirim response
→ client menerima response
→ MCP assertion berhasil

Instalasi Windows

Jalankan dari root repository yang baru di-clone:

git clone https://github.com/marhenrik635-oss/mcponmysamp.git
cd mcponmysamp
py -3 -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install ".[dev]"
pytest -q

Linux / macOS:

git clone https://github.com/marhenrik635-oss/mcponmysamp.git
cd mcponmysamp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install ".[dev]"
pytest -q

Dependency game

Binary open.mp, RakClient, dan Pawn compiler tidak disimpan di Git repository agar clone tetap kecil dan tidak mendistribusikan binary pihak ketiga.

Siapkan dependency tersebut sendiri. Struktur lokal bebas; contoh:

D:/Games/open.mp/omp-server.exe
D:/Games/RakClient/rakclient.exe
D:/Games/RakClient/scripts/

Konfigurasi

Salin template:

copy config.example.json local-server.json

Linux / macOS:

cp config.example.json local-server.json

Edit local-server.json:

{
  "executable": "D:/Games/open.mp/omp-server.exe",
  "working_dir": "D:/Games/open.mp",
  "args": ["--config-path", "config.json"],
  "ready_text": "Legacy Network started on port",
  "startup_timeout": 30
}

local-server.json sengaja di-ignore Git. Gunakan path sesuai komputer sendiri.

Menjalankan MCP

Server saja:

mcp-gta-samp --config local-server.json

Dengan headless RakClient:

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 ^
  --client-arg --scripts-dir ^
  --client-arg D:/Games/RakClient/scripts ^
  --gamemode-source examples/mcp_test.pwn

Untuk PowerShell, gunakan satu baris. MCP menggunakan transport stdio; terminal yang diam berarti proses sedang menunggu request dari MCP client.

MCP tools

Tool	Fungsi
server_start	Start server dan tunggu readiness.
server_status	Cek server dan PID.
server_stop	Stop server.
server_list_commands	Daftar command dari source Pawn.
server_assert_command	Validasi command terhadap allowlist.
client_start	Start headless RakClient.
client_status	Cek status client.
client_stop	Stop client.
client_send_chat	Kirim command slash allowlisted setelah Spawned.
client_get_history	Ambil output client.
client_assert_output	Pastikan response diterima client.
bot_walk_to	Jalan ke titik (walk/jog/sprint/direct).
bot_stop	Berhenti jalan.
bot_teleport	Teleport body.
bot_face_heading	Hadap arah (derajat).
bot_face_point	Hadap titik.
bot_jump	Pulse lompat.
bot_key_hold	Hold key mask (8=sprint, 4=fire, 32=jump, 128=crouch).
bot_key_release	Lepas semua key.
bot_enter_vehicle	Masuk kendaraan (ID, seat).
bot_exit_vehicle	Keluar kendaraan.
bot_animation	Paksa animasi (ID, flags).
bot_set_velocity	Set velocity vector.
bot_send_chat	Kirim chat (tanpa slash).
bot_respawn	Force respawn.
bot_reconnect	Putus & reconnect ke server.
bot_dialog	Jawab dialog server.
bot_vehicle_drive	Hold key kendaraan (gas/rem/stir -1/0/1).
bot_vehicle_horn	Klakson.
bot_vehicle_health	HP kendaraan (1000 = sempurna).
bot_vehicle_position	Posisi kendaraan.
bot_vehicle_velocity	Set velocity kendaraan.
bot_vehicle_speed	Kecepatan kendaraan (units/s).
bot_get_dialog	Baca dialog server aktif.
bot_wait_for_dialog	Tunggu dialog muncul.
bot_wait_for_message	Tunggu pesan server (opsional marker).
bot_click_textdraw	Klik textdraw (RPC 83).
bot_pickup_pickup	Ambil pickup (RPC 131).
bot_target_entity	Set target aim (object/vehicle/player/actor).
bot_scan_textlabels	3D text label di sekitar.
bot_scan_pickups	Pickup di sekitar.
bot_scan_objects	Object di sekitar.
bot_get_position	Posisi body.
bot_get_rotation	Heading body.
bot_get_vehicle	ID kendaraan saat ini.
bot_get_health	HP + armour.
bot_get_weapon	ID senjata saat ini.
bot_get_money	Uang.
bot_get_nick	Nickname.
bot_get_interior	Interior ID.
bot_get_camera	Posisi kamera.
bot_get_keys	Key mask yang dihold.
bot_get_server	Alamat server.
bot_is_walking	Apakah sedang berjalan?
bot_ping	Cek apakah bridge script hidup.
bot_scan_players	Player di sekitar (ID, posisi).
bot_scan_vehicles	Kendaraan di sekitar (ID, posisi, model).
bot_wait_for_chat	Tunggu chat mengandung marker.

Workflow AI agent

1. server_status
2. server_start jika belum berjalan
3. client_start
4. tunggu Spawned
5. server_list_commands
6. server_assert_command("/help")
7. client_send_chat("/help")
8. client_assert_output("MCP Test Commands:")
9. client_get_history bila perlu diagnosis
10. client_stop
11. server_stop

Jangan menganggap boot, join, atau Spawned sebagai bukti command berhasil. Jika gagal, klasifikasikan boundary: boot, koneksi, spawn, queue, outbound packet, callback server, response server, parser client, atau assertion MCP.

Fixture gamemode

Source minimal ada di:

examples/mcp_test.pwn

Command:

/help
/status

Fixture ini perlu dimasukkan ke folder gamemodes pada instalasi open.mp lalu di-compile menggunakan Pawn compiler. Dari folder instalasi open.mp:

qawno\pawncc.exe -i.\qawno\include -o.\gamemodes\mcp_test examples\mcp_test.pwn

Pastikan config.json open.mp memuat gamemode:

"main_scripts": ["mcp_test 1"]

Contoh MCP client

MCP client menjalankan executable sebagai subprocess melalui stdio. Sesuaikan semua path:

{
  "mcpServers": {
    "mcponmysamp": {
      "command": "D:/path/mcponmysamp/.venv/Scripts/mcp-gta-samp.exe",
      "args": [
        "--config", "D:/path/mcponmysamp/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",
        "--client-arg", "--scripts-dir",
        "--client-arg", "D:/Games/RakClient/scripts",
        "--gamemode-source", "D:/path/mcponmysamp/examples/mcp_test.pwn"
      ]
    }
  }
}

Testing dan build

.venv\Scripts\activate
pytest -q
python -m pip wheel . --no-deps -w dist

Target minimal: seluruh test Python lulus. Live test membutuhkan dependency game lokal dan tidak dijalankan di CI.

Struktur repository

mcp_gta_samp/       package MCP Python
tests/              unit dan contract tests
examples/           fixture Pawn kecil
config.example.json template konfigurasi
README.md           dokumentasi
LICENSE             MIT License

Keamanan dan batasan

Gunakan hanya pada server lokal atau server yang kamu miliki / izinkan. Jangan commit credential, proxy, log privat, konfigurasi sensitif, atau binary game besar. Headless RakClient membuktikan protocol, state, command, dan response; bukan screenshot atau gameplay visual.

Lisensi

MIT License. Lihat LICENSE.

Repository · Issues

Testable. Local. Verifiable.