MCP on My SAMP

Область применения: локальные серверы или серверы, которыми вы владеете/на которые у вас есть разрешение. Это не инструмент для автоматизации публичных серверов.

Что умеет?

MCP on My SAMP позволяет AI-агенту тестировать игровые серверы с помощью воспроизводимых рабочих процессов:

• запуск / остановка / проверка статуса open.mp;

• запуск / остановка / проверка статуса headless RakClient;

• ожидание фактического перехода клиента в состояние Spawned;

• отправка разрешённых slash-команд;

• чтение истории вывода клиента;

• проверка того, что ответ сервера получен клиентом;

• поиск команд в исходном коде Pawn-гаммода;

• отклонение команд, не входящих в allowlist.

Не предоставляет flood, спам, инъекцию задержек, произвольный RCON или автоматизацию публичных серверов.

Рабочий процесс

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

Доказательство корректного round-trip:

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

Состояние Spawned само по себе не является доказательством успешного выполнения команды.

Установка

1. Подготовьте Python

Требуется Python 3.10 или новее.

2. Установите проект

Выполните из корня репозитория:

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. Проверка

pytest -q

Ожидаемый вывод:

35 passed

Бинарные файлы open.mp и RakClient требуются только для live-тестов. Модульные тесты Python можно запускать и без этих бинарных файлов.

Конфигурация

Создайте локальный файл конфигурации из шаблона:

Windows

copy config.example.json local-server.json

Linux / macOS

cp config.example.json local-server.json

Заполните файл:

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

Измените executable и working_dir в соответствии с расположением open.mp на вашем компьютере. local-server.json не попадает в Git, поскольку пути на каждом компьютере разные.

Запуск MCP-сервера

Только сервер

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

С 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

Транспорт MCP использует stdio.

MCP-инструменты

Последние два инструмента доступны, если используется --gamemode-source.

Рабочий процесс для AI-агента

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

Важные инструкции для агента:

• не обращаться к публичным серверам;

• не считать boot, join или Spawned подтверждением round-trip команды;

• при сбое классифицировать границу: boot, соединение, спавн, очередь, исходящий пакет, серверный callback, ответ сервера, клиентский парсер или assertion MCP;

• всегда останавливать процессы после теста;

• убедиться, что UDP-порт 7777 снова свободен.

Пример live-теста

Тестовый гаммод доступен по адресу:

vendor/openmp/Server/gamemodes/mcp_test.pwn

Доступные команды:

/help
/status

Если исходный код Pawn изменён, перекомпилируйте .amx из папки сервера:

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

Live-рабочий процесс:

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

Headless RakClient доказывает протокол, состояние и команды. Он не создаёт скриншоты. Для визуального тестирования требуется отдельный отрендеренный GTA-клиент.

Разработка

Запуск тестов:

pytest -q

Создание wheel:

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

Установка wheel:

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

Основная структура:

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

Безопасность

Этот MCP ограничивает использование локальными/принадлежащими вам серверами. Не помещайте учётные данные, прокси-пулы, приватные конфиги, приватные логи или данные тестовых серверов в публичный репозиторий.

Если вы запускаете сервер из интернета, добавьте собственную аутентификацию и сетевую изоляцию. Этот пакет не предназначен для использования в качестве публичного API управления играми.

Лицензия

Лицензия MIT. См. LICENSE.

Ссылки

• Репозиторий: marhenrik635-oss/mcponmysamp

• Issues: сообщить о проблеме