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: mc-mcp-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 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；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.json

• Windows 侧启动 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。

部署方式

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 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 8000