# MCP on My SAMP

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

![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white) ![MCP](https://img.shields.io/badge/MCP-stdio-7C3AED?style=for-the-badge) ![License](https://img.shields.io/badge/license-MIT-F59E0B?style=for-the-badge) [![M8ven Score](https://m8ven.ai/badge/mcp/marhenrik635-oss-mcponmysamp-f5v8cy)](https://m8ven.ai/mcp/marhenrik635-oss-mcponmysamp-f5v8cy)

> 🌐 **Website:** [marhenrik635-oss.github.io/mcponmysamp-web](https://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

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

Bukti valid:

```text
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:

```bat
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:

```bash
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:

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

## Konfigurasi

Salin template:

```bat
copy config.example.json local-server.json
```

Linux / macOS:

```bash
cp config.example.json local-server.json
```

Edit `local-server.json`:

```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:

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

Dengan headless RakClient:

```bat
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.

| 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_key_sequence` | Macro key blocking, steps `{keys, ms}` (on-foot 8=sprint 32=jump; incar 4=gas 8=rem 16/32=belok 64=klakson). |
| `bot_enter_vehicle` | Masuk kendaraan (ID, seat). |
| `bot_exit_vehicle` | Keluar kendaraan. |
| `bot_animation` | Paksa animasi (ID, flags). |
| `bot_play_animation` | Mainkan animasi bernama (sit/dance/wave/dll). |
| `bot_list_animations` | Daftar animasi bernama yang tersedia. |
| `bot_set_velocity` | Set velocity vector. |
| `bot_send_chat` | Kirim chat (tanpa slash). |
| `bot_send_command` | Kirim command slash via RPC (tanpa cek allowlist). |
| `bot_set_nick` | Ganti nickname bot. |
| `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_scan_textdraws` | Textdraw 2D yang tampil ke bot (ID, posisi, style, teks). |
| `bot_wait_for_textdraw` | Tunggu textdraw muncul (opsional marker teks). |
| `bot_pickup_pickup` | Ambil pickup (RPC 131). |
| `bot_get_checkpoint` | Checkpoint server aktif (posisi + radius), atau inactive. |
| `bot_goto_checkpoint` | Jalan ke checkpoint server aktif (direct). |
| `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_get_server_info` | Info world server: waktu, cuaca, gravitasi. |
| `bot_get_state` | State gabungan bot: posisi, kendaraan, waktu world, interior. |
| `bot_is_walking` | Apakah sedang berjalan? |
| `bot_ping` | Cek apakah bridge script hidup. |
| `bot_fire` | Pulse tombol fire (tembak sekali). |
| `bot_scan_players` | Player di sekitar (ID, posisi). |
| `bot_scan_players_detail` | Player di sekitar detail (HP, armour, senjata, kendaraan). |
| `bot_scan_vehicles` | Kendaraan di sekitar (ID, posisi, model). |
| `bot_scan_vehicles_detail` | Kendaraan di sekitar detail (HP, speed, posisi). |
| `bot_wait_for_chat` | Tunggu chat mengandung marker. |
| `bot_wait_for_player` | Tunggu player muncul (filter nick/jarak, timeout). |
| `observer_start` | Launch omp-launcher (rendered client) ke server localhost-only; default background (`visible=False` = window diparkir off-screen). |
| `observer_screenshot` | Screenshot PNG window game (PrintWindow, fallback fullscreen). |
| `observer_status` | Status observer (proses, judul window, connected). |
| `observer_stop` | Kill tree proses game yang di-start observer. |

## 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

```text
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:

```text
examples/mcp_test.pwn
```

Command:

```text
/help
/status
```

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

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

Pastikan `config.json` open.mp memuat gamemode:

```json
"main_scripts": ["mcp_test 1"]
```

## Contoh MCP client

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

```json
{
  "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

```bat
.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

```text
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](LICENSE).

[Repository](https://github.com/marhenrik635-oss/mcponmysamp) · [Website](https://marhenrik635-oss.github.io/mcponmysamp-web/) · [Issues](https://github.com/marhenrik635-oss/mcponmysamp/issues)

<p align="center"><strong>Testable. Local. Verifiable.</strong></p>