MCP on My SAMP

Alcance: servidor local o servidores que poseas o para los que tengas permiso. No es una herramienta para automatización de servidores públicos.

¿Qué puede hacer?

MCP on My SAMP permite que un agente de IA pruebe servidores de juego con flujos de trabajo repetibles:

• iniciar / detener / comprobar el estado de open.mp;

• iniciar / detener / comprobar el estado de RakClient headless;

• esperar a que el cliente esté realmente Spawned;

• enviar comandos slash permitidos;

• leer el historial de salida del cliente;

• verificar que el cliente ya ha recibido la respuesta del servidor;

• descubrir comandos del código fuente Pawn del gamemode;

• rechazar comandos fuera de la allowlist.

No proporciona flood, spam, inyección de lag, RCON arbitrario ni automatización hacia servidores públicos.

Flujo de trabajo

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

Prueba válida de round-trip:

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

Spawned por sí solo no es prueba de que el comando haya tenido éxito.

Instalación

1. Prepara Python

Se requiere Python 3.10 o superior.

2. Instala el proyecto

Ejecuta desde la raíz del repositorio:

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. Verificación

pytest -q

Salida esperada:

35 passed

Los binarios de open.mp y RakClient solo son necesarios para la prueba en vivo. Las pruebas unitarias de Python se pueden ejecutar sin esos binarios.

Configuración

Crea un archivo de configuración local a partir de la plantilla:

Windows

copy config.example.json local-server.json

Linux / macOS

cp config.example.json local-server.json

Rellena el archivo:

{
  "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
}

Cambia executable y working_dir según la ubicación de open.mp en tu ordenador. local-server.json no se incluye en Git porque la ruta difiere en cada ordenador.

Ejecutar el servidor MCP

Solo el servidor

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

Con RakClient headless

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

El transporte MCP utiliza stdio.

Herramientas MCP

Las dos últimas herramientas están disponibles si se usa --gamemode-source.

Flujo de trabajo para el agente de IA

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

Instrucciones importantes para el agente:

• no accedas a servidores públicos;

• no consideres el arranque, la conexión o Spawned como un round-trip de comando;

• si falla, clasifica el límite: arranque, conexión, spawn, cola, paquete saliente, callback del servidor, respuesta del servidor, parser del cliente o aserción MCP;

• detén siempre los procesos después de la prueba;

• asegúrate de que el puerto UDP 7777 vuelva a estar libre.

Ejemplo de prueba en vivo

El gamemode de prueba está disponible en:

vendor/openmp/Server/gamemodes/mcp_test.pwn

Comandos disponibles:

/help
/status

Si se modifica el código fuente Pawn, recompila el .amx desde la carpeta del servidor:

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

Flujo de trabajo en vivo:

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

El RakClient headless demuestra el protocolo, el estado y los comandos. No genera capturas de pantalla. Las pruebas visuales requieren un cliente GTA renderizado por separado.

Desarrollo

Ejecutar las pruebas:

pytest -q

Crear el wheel:

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

Instalar el wheel:

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

Estructura principal:

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

Seguridad

Este MCP limita el uso a servidores locales o propios. No incluyas credenciales, grupos de proxies, configuraciones privadas, registros privados ni datos de prueba del servidor en un repositorio público.

Si ejecutas el servidor desde internet, añade tu propia autenticación y aislamiento de red. Este paquete no está diseñado como una API pública de control de juegos.

Licencia

Licencia MIT. Consulta LICENSE.

Enlaces

• Repositorio: marhenrik635-oss/mcponmysamp

• Issues: informar de un problema