skynet-mcp
skynet-mcp
把 skynet 游戏服务器框架的 DebugConsole
调试命令封装成 MCP(Model Context Protocol)工具,让 coding agent(如 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/...)绝不自动重试;只读命令传输失败时自动重试一次
Related MCP server: LLMMO Game Server
通信原理
skynet debug console 支持 HTTP 通道(POST / HTTP/1.0,body 即命令行,响应为裸文本 +
<CMD OK> / <CMD Error> 标记后断开)。本项目用标准库 socket 手工构造该请求:
为什么不用 http.client/requests:skynet 的响应没有 HTTP 状态行(curl 需
--http0.9), 标准 HTTP 客户端无法解析为什么用 POST 而不是 GET:POST 的 body 被服务端
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 8765HTTP 监听参数:
参数 | 默认值 | 说明 |
|
| HTTP 监听地址 |
|
| HTTP 监听端口(与 skynet console 端口区分) |
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;Windows 侧启动的 opencode 看不到 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
}
}
}WSL 内启动 opencode:写 WSL 的项目根
opencode.json(本仓库已带)或全局~/.config/opencode/opencode.jsonWindows 侧启动 opencode(PowerShell / Desktop):写 Windows 全局
C:\Users\Admin\.config\opencode\opencode.json(已有内容如instructions时合并保留) 或启动目录的项目级opencode.json。url仍用http://127.0.0.1:8765/mcp——WSL2 localhost 转发会把 Windows 侧127.0.0.1:8765直通到 WSL 里监听的 MCP 进程, 无需改 MCP 监听地址MCP 服务器需独立启动(手动或进程管理器托管),opencode 不再自动拉起子进程; 服务器未启动时 opencode 会显示连接失败
局域网/公网访问需把 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。
部署方式
WSL/Linux 内直连(推荐):opencode、MCP 进程与 skynet 都在 WSL 内, 直连
127.0.0.1:<port>,零转发SSH 隧道(远端生产机):MCP 进程与 skynet 不同机时,
ssh -L 8000:127.0.0.1:8000 user@remote,opencode 连本地 8000 即可。 切勿把 debug console 端口直接暴露到公网
工具清单(32 个)
工具 | 底层命令 | 说明 |
|
| 全部命令帮助 |
|
| 列出所有服务及地址 |
|
| 列出唯一服务与挂起请求 |
|
| 消息队列/挂起请求/消息总数 |
|
| 各服务 lua 内存 |
|
| 全服强制 GC + 内存报告 |
|
| 网络连接概况 |
|
| C 层 / jemalloc 内存 |
|
| 堆分析 |
| 同名 | 启动新服务(⚠) |
| 同名 | 中止服务(【危险】) |
|
| 打断死循环拿到调用栈(【危险】) |
| 同名 | 挂起请求调用栈 |
|
| 终止线程(⚠) |
|
| 服务内部信息 |
|
| 注入补丁脚本(【危险】,路径为 skynet 视角) |
|
| 任意 debug 协议命令(⚠) |
|
| 往返耗时 |
|
| 协议跟踪 |
| 同名 | 记录服务输入消息 |
|
| 调用服务 lua 接口(【危险】) |
| 同名 | 环境变量读写 |
| 透传 | 任意命令兜底(【危险】) |
地址写法::01000001(八位 hex)、1(简写)、.名字(本地服务名)。
安全注意事项
skynet debug console 无鉴权,且只监听
127.0.0.1——远程使用请走 SSH 隧道,不要暴露端口【危险】命令(kill/exit/signal/inject/call/raw_command)会影响运行中的服务, 工具描述中已标注;coding agent 调用前应让用户确认
debug交互式命令需要持久终端会话,HTTP 通道不支持,已显式拒绝(请用 telnet/nc 手动连接)inject的脚本路径是 skynet 服务器视角(MCP 与 skynet 可能在不同文件系统)
开发与测试
通过 opencode 端到端测试全部 32 个
skynet_*工具的可复制提示词见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 8000Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
All 20 YourAITools agent APIs in one MCP server. Most tools free; pay with credits or x402.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables control of a Minecraft server through RCON commands via natural language, including game commands, chat-based AI interactions, and server management capabilities.6-
- AlicenseNot gradedqualityDmaintenanceEnables LLM-driven text game state management by exposing MCP tools for managing players, locations, items, entities, and abstract concepts.MIT
- AlicenseNot gradedqualityBmaintenanceA Linux-native MCP server that gives AI assistants direct access to DMA-based memory operations for memory inspection, process analysis, reverse engineering, and game engine SDK extraction via natural language.13AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceLocal MCP server that gives AI agents 44 engine tools to build, run, and debug real 2D and 3D games through conversation.MIT