MCP on My SAMP

Umfang: Lokale Server oder Server, die dir gehören bzw. von dir autorisiert sind. Kein Werkzeug für die Automatisierung öffentlicher Server.

Was kann es?

MCP on My SAMP ermöglicht es KI-Agenten, Spieleserver mit wiederholbaren Workflows zu testen:

• open.mp starten / stoppen / Status prüfen;

• Headless-RakClient starten / stoppen / Status prüfen;

• warten, bis der Client tatsächlich Spawned ist;

• erlaubte Slash-Befehle senden;

• den Ausgabeverlauf des Clients lesen;

• verifizieren, dass die Serverantwort beim Client angekommen ist;

• Befehle aus dem Pawn-Quellcode des Gamemodes ermitteln;

• Befehle außerhalb der Zulassungsliste ablehnen.

Es bietet kein Flooding, Spamming, Lag Injection, beliebiges RCON oder die Automatisierung öffentlicher Server.

Arbeitsablauf

flowchart LR
    A[AI Agent] -->|MCP stdio| B[MCP on My SAMP]
    B --> C[open.mp Server]
    B --> D[Headless RakClient]
    D -->|UDP localhost| C
    C -->|server response| D
    D --> B
    B -->|assertion| A

Gültiger Roundtrip-Nachweis:

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

Allein Spawned ist kein Beweis dafür, dass der Befehl erfolgreich war.

Installation

1. Python einrichten

Python 3.10 oder neuer ist erforderlich.

2. Projekt installieren

Vom Repository-Stammverzeichnis ausführen:

Windows

py -3 -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install ".[dev]"

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install ".[dev]"

3. Überprüfen

pytest -q

Erwartete Ausgabe:

35 passed

Die open.mp- und RakClient-Binärdateien werden nur für Live-Tests benötigt. Die Python-Unit-Tests können auch ohne diese Binärdateien ausgeführt werden.

Konfiguration

Erstelle eine lokale Konfigurationsdatei aus der Vorlage:

Windows

copy config.example.json local-server.json

Linux / macOS

cp config.example.json local-server.json

Inhalt der Datei:

{
  "executable": "vendor/openmp/Server/omp-server.exe",
  "working_dir": "vendor/openmp/Server",
  "args": ["--config-path", "config.json"],
  "ready_text": "Legacy Network started on port",
  "startup_timeout": 30
}

Passe executable und working_dir an den Speicherort von open.mp auf deinem Computer an. local-server.json ist nicht in Git eingecheckt, da die Pfade auf jedem Computer unterschiedlich sind.

MCP-Server ausführen

Nur Server

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

Mit Headless-RakClient

Windows

mcp-gta-samp ^
  --config local-server.json ^
  --client-executable vendor/rakclient-bin/rakclient.exe ^
  --client-arg --server ^
  --client-arg 127.0.0.1:7777 ^
  --client-arg --nick ^
  --client-arg MCPBot ^
  --client-arg --scripts-dir ^
  --client-arg vendor/rakclient-bin/scripts ^
  --gamemode-source vendor/openmp/Server/gamemodes/mcp_test.pwn

Linux / macOS

mcp-gta-samp \
  --config local-server.json \
  --client-executable vendor/rakclient-bin/rakclient \
  --client-arg --server \
  --client-arg 127.0.0.1:7777 \
  --client-arg --nick \
  --client-arg MCPBot \
  --client-arg --scripts-dir \
  --client-arg vendor/rakclient-bin/scripts \
  --gamemode-source vendor/openmp/Server/gamemodes/mcp_test.pwn

Der MCP-Transport verwendet stdio.

MCP-Tools

Die letzten beiden Tools sind verfügbar, wenn --gamemode-source verwendet wird.

Workflow für KI-Agenten

1. server_status
2. server_start jika belum berjalan
3. client_start
4. tunggu state 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

Wichtige Anweisungen für den Agenten:

• greife nicht auf öffentliche Server zu;

• betrachte Booten, Beitreten oder Spawned nicht als Befehls-Roundtrip;

• klassifiziere bei Fehlern die Grenze: Boot, Verbindung, Spawn, Warteschlange, ausgehendes Paket, Server-Callback, Serverantwort, Client-Parser oder MCP-Assertion;

• beende die Prozesse nach dem Test immer;

• stelle sicher, dass der UDP-Port 7777 wieder frei ist.

Beispiel für einen Live-Test

Ein Test-Gamemode ist verfügbar unter:

vendor/openmp/Server/gamemodes/mcp_test.pwn

Verfügbare Befehle:

/help
/status

Wenn der Pawn-Quellcode geändert wird, kompiliere die .amx aus dem Serverordner neu:

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

Live-Workflow:

server_start
→ client_start
→ client mencapai Spawned
→ client_send_chat("/help")
→ client_assert_output("MCP Test Commands:")
→ client_assert_output("/status - show a test response")
→ client_stop
→ server_stop

Der Headless-RakClient weist Protokoll, Zustand und Befehle nach. Er erzeugt keine Screenshots. Für visuelle Tests ist ein separater gerenderter GTA-Client erforderlich.

Entwicklung

Tests ausführen:

pytest -q

Wheel erstellen:

python -m pip wheel . --no-deps -w dist

Wheel installieren:

python -m pip install dist/mcp_gta_samp-0.1.0-py3-none-any.whl

Kernstruktur:

mcp_gta_samp/       package Python dan MCP facade
tests/              unit, contract, dan bridge tests
config.example.json template konfigurasi
vendor/             binary dan fixture live test

Sicherheit

Dieses MCP beschränkt die Nutzung auf lokale/eigene Server. Gib keine Anmeldedaten, Proxy-Pools, privaten Konfigurationen, privaten Protokolle oder Testserverdaten in ein öffentliches Repository.

Wenn du den Server aus dem Internet erreichbar machst, füge selbst Authentifizierung und Netzwerkisolierung hinzu. Dieses Paket ist nicht als öffentliche Spielsteuerungs-API konzipiert.

Lizenz

MIT-Lizenz. Siehe LICENSE.

Links

• Repository: marhenrik635-oss/mcponmysamp

• Issues: Problem melden