marhenrik635-oss/mcponmysamp

MCP on My SAMP

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

🌐 Website: marhenrik635-oss.github.io/mcponmysamp-web — landing page interaktif: arsitektur 3D, daftar 77 tools, dan quickstart.

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.
• Visual observer: jalankan client render sungguhan via omp-launcher, screenshot PNG jendela game (PrintWindow), window diparkir off-screen agar tidak mengganggu desktop.
• 77 MCP tools: driving, dialog-awareness, textdraw/checkpoint awareness, key sequence, dan tool observasi visual.

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

Total 77 tools. Tool bot_wait_for_*, bot_scan_*, dan bot_key_sequence berjalan blocking di dalam newTask, jadi aman menunggu event server (textdraw, checkpoint, player) tanpa mengganggu dispatch.

Visual Observer

Fitur opsional: melihat hasil render client sungguhan lewat screenshot. Prasyarat (sekali saja, salin manual — tool tidak menyalin file sistem):

• samp.dll dari %LOCALAPPDATA%\mp.open.launcher\samp\0.3.7-R5\samp.dll
• omp-client.dll dari %LOCALAPPDATA%\mp.open.launcher\omp\omp-client.dll

keduanya ke direktori game, lalu isi launcher_path + game_path di config (lihat config.example.json). observer_start default background: window diparkir off-screen (Z-bottom, koordinat -32000) sehingga tidak mengganggu desktop, dan PrintWindow tetap valid untuk screenshot. Catatan: client yang idle tanpa fokus bisa crash ~90 detik; lakukan screenshot berkala bila butuh observasi lama.

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.

Rilis versi (semantic versioning): bump version di pyproject.toml dan mcp_gta_samp/__init__.py, perbarui README bila fitur berubah, commit, tag v<version>, push tag.

Struktur repository

mcp_gta_samp/       package MCP Python (cli, config, core, headless, mcp_server, observer, openmp, remote, server)
tests/              unit dan contract tests
examples/           fixture Pawn kecil
scripts/            CI helper (check_luau.py)
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 · Website · Issues