skynet-mcp

Обёртка отладочных команд DebugConsole игрового серверного фреймворка skynet в инструменты MCP (Model Context Protocol), чтобы coding-агент (например, opencode) мог напрямую управлять отладочной консолью skynet через естественный язык — больше не нужно запоминать команды list / mem / call / inject.

用户: "看看现在 skynet 里跑了哪些服务"
AI:   → 调用 list 工具
用户: "帮我把 watchdog 服务的卡住的任务栈打出来"
AI:   → 调用 task 工具（地址来自 list 输出）

Возможности

• 32 инструмента MCP, покрывающих все команды debug console (см. список инструментов ниже)

• Запасной инструмент raw_command: передаёт любую командную строку как есть, совместим с будущими новыми командами

• 2 ресурса: skynet://services (список сервисов в реальном времени), skynet://help (справка по командам)

• 1 шаблон промпта: skynet_troubleshoot (генерирует шаги диагностики в порядке «только чтение → опасные»)

• Команды с побочными эффектами (kill/exit/inject/call/signal/...) никогда не повторяются автоматически; при сбое передачи read-only команды выполняется одна автоматическая попытка повтора

Related MCP server: mc-mcp-server

Принцип взаимодействия

skynet debug console поддерживает HTTP-канал (POST / HTTP/1.0, тело запроса — командная строка, ответ — обычный текст + маркер <CMD OK> / <CMD Error>, после чего соединение закрывается). В этом проекте запрос вручную формируется через socket из стандартной библиотеки:

• Почему не http.client/requests: в ответе skynet нет HTTP-строки статуса (curl требуется --http0.9), стандартные HTTP-клиенты не могут его разобрать

• Почему POST, а не GET: тело POST обрабатывается сервером как командная строка через docmd(body), кавычки, запятые и пути со слэшами в call 3 "foo", 1, "bar" / inject 3 /home/x/patch.lua не искажаются URL-кодированием

Структура проекта

skynet-mcp/
├── skynet_mcp/
│   ├── main.py          # FastMCP 入口（工具注册 + 资源 + 提示词）
│   ├── config.py        # host/port/timeout（env + 命令行参数）
│   ├── backend.py       # 裸 socket HTTP POST 通信层
│   ├── parser.py        # 裸文本响应解析（去 Welcome/CMD 标记）
│   └── tools.py         # 32 个工具定义
├── tests/               # mock console + 单元测试
├── examples/            # opencode 集成示例
└── scripts/smoke_test.py

Установка (Linux, на той же машине, что и skynet)

# 1. 获取代码（git clone，或拷贝已有目录到 ~/skynet-mcp）
mkdir -p ~/skynet-mcp && cp -r <代码路径>/* ~/skynet-mcp/

# 2. 创建 venv 并安装依赖（python3 需 >= 3.10）
cd ~/skynet-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .

# 3. 验证
.venv/bin/python scripts/smoke_test.py --port 8000

Запуск

MCP-сервер запускается независимо в режиме streamable-http (вручную или под управлением systemd / supervisor и т.п.), прослушивает фиксированный порт, клиенты вроде opencode подключаются по HTTP удалённо — дочерний процесс больше не запускается клиентом автоматически.

# WSL 内启动，默认监听 127.0.0.1:8765（Windows 侧经 WSL2 localhost 转发访问）
.venv/bin/python -m skynet_mcp.main
# 自定义 HTTP 监听端口
.venv/bin/python -m skynet_mcp.main --http-port 8765

Параметры HTTP-прослушивания:

Параметры подключения к skynet debug console:

• URL конечной точки: http://127.0.0.1:8765/mcp (протокол MCP streamable-http), клиенты opencode / skynet-mcp-client подключаются через эту конечную точку

• Безопасность: по умолчанию привязка к 127.0.0.1 и включена защита от DNS-rebinding; для доступа с других машин используйте --http-host 0.0.0.0 и убедитесь, что сеть доверенная (или используйте SSH-туннель), не выставляйте в публичный интернет

Подключение к opencode

Сначала запустите MCP-сервер независимо (см. выше), затем подключайтесь через type: "remote". Конфигурацию нужно писать на той стороне, где запущен opencode — opencode читает только глобальную конфигурацию своего процесса ~/.config/opencode/opencode.json + проектный opencode.json в текущем каталоге; opencode, запущенный на стороне Windows, не видит конфигурацию в WSL (проявляется как opencode mcp list с сообщением No MCP servers configured).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "skynet": {
      "type": "remote",
      "url": "http://127.0.0.1:8765/mcp",
      "enabled": true
    }
  }
}

• opencode запущен внутри WSL: пишите в корневой opencode.json проекта WSL (уже включён в этот репозиторий) или в глобальный ~/.config/opencode/opencode.json

• opencode запущен на стороне Windows (PowerShell / Desktop): пишите в глобальный Windows C:\Users\Admin\.config\opencode\opencode.json (при наличии содержимого вроде instructions — объединяйте, сохраняя его) или в проектный opencode.json в каталоге запуска. url по-прежнему http://127.0.0.1:8765/mcp — переадресация localhost в WSL2 пропустит 127.0.0.1:8765 со стороны Windows напрямую к процессу MCP, слушающему в WSL, менять адрес прослушивания MCP не нужно

• MCP-сервер нужно запускать независимо (вручную или через менеджер процессов), opencode больше не запускает дочерний процесс автоматически; если сервер не запущен, opencode покажет ошибку подключения

• Для доступа из LAN/публичной сети нужно перезапустить MCP с --http-host 0.0.0.0 — но сервер не имеет аутентификации и содержит опасные команды kill / inject / raw_command, поэтому рекомендуется только SSH-туннель (ssh -L 8765:127.0.0.1:8765 user@remote) или добавление аутентификации Bearer Token, не выставляйте напрямую в публичный интернет

После изменений перезапустите opencode, введите /mcp в диалоге, убедитесь, что skynet подключён, затем попросите его «использовать инструменты skynet, чтобы вывести список всех текущих сервисов» — это сквозная проверка. Полные шаги тестирования и устранения неполадок см. в examples/opencode-mcp.md; тестовые промпты, покрывающие все 32 инструмента, см. в examples/mcp-test-prompts.md.

Способы развёртывания

1. Прямое подключение внутри WSL/Linux (рекомендуется): opencode, процесс MCP и skynet находятся в WSL, прямое подключение к 127.0.0.1:<port>, без переадресации

2. SSH-туннель (удалённая продакшн-машина): когда процесс MCP и skynet на разных машинах, ssh -L 8000:127.0.0.1:8000 user@remote, opencode подключается к локальному 8000. Никогда не выставляйте порт debug console напрямую в публичный интернет

Список инструментов (32)

Форматы адресов: :01000001 (восемь hex-цифр), 1 (сокращённая форма), .имя (имя локального сервиса).

Меры безопасности

• skynet debug console не имеет аутентификации и слушает только 127.0.0.1 — для удалённого использования используйте SSH-туннель, не открывайте порт

• 【Опасные】команды (kill/exit/signal/inject/call/raw_command) влияют на работающие сервисы, это отмечено в описаниях инструментов; перед вызовом coding-агент должен получить подтверждение пользователя

• Интерактивная команда debug требует постоянной терминальной сессии, HTTP-канал её не поддерживает, явно отклонена (подключайтесь вручную через telnet/nc)

• Путь скрипта в inject — с точки зрения сервера skynet (MCP и skynet могут находиться в разных файловых системах)

Разработка и тестирование

Воспроизводимые промпты для сквозного тестирования всех 32 инструментов skynet_* через opencode см. в examples/mcp-test-prompts.md; ниже — модульные/дымовые тесты для разработчика.

# 单元测试
python -m pytest tests/ -v

# 冒烟测试（先起 mock console）
python -m tests.mock_console          # 打印 mock 端口
python scripts/smoke_test.py --port <mock端口>

# 或对真实 skynet 冒烟
python scripts/smoke_test.py --port 8000

# 手工验证（nc 直连真实 console）
printf 'POST / HTTP/1.0\r\nContent-Length: 4\r\n\r\nlist' | nc 127.0.0.1 8000