skynet-mcp

Wraps the DebugConsole debug commands of the skynet game server framework into MCP (Model Context Protocol) tools, letting coding agents (such as opencode) drive the skynet debug console directly through natural language—no need to memorize commands like list / mem / call / inject anymore.

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

Features

• 32 MCP tools, covering all debug console commands (see the tool list below)

• raw_command fallback tool: passes any command line through verbatim, compatible with future new commands

• 2 resources: skynet://services (real-time service list), skynet://help (command help)

• 1 prompt template: skynet_troubleshoot (generates troubleshooting steps in "read-only → dangerous" order)

• Commands with side effects (kill/exit/inject/call/signal/...) are never auto-retried; read-only commands are retried once automatically on transport failure

Related MCP server: mc-mcp-server

Communication Principle

The skynet debug console supports an HTTP channel (POST / HTTP/1.0, the body is the command line, the response is raw text + a <CMD OK> / <CMD Error> marker, then the connection closes). This project hand-crafts that request using the standard library socket:

• Why not http.client/requests: skynet's response has no HTTP status line (curl needs --http0.9), standard HTTP clients cannot parse it

• Why POST instead of GET: the POST body is executed verbatim as a command line by the server's docmd(body), so quotes, commas, and slash paths in call 3 "foo", 1, "bar" / inject 3 /home/x/patch.lua are not mangled by URL encoding

Project Structure

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

Installation (Linux, same machine as 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

Startup

The MCP server starts independently via streamable-http (manually, or managed by a process manager such as systemd / supervisor), listening on a fixed port, with clients like opencode connecting remotely over HTTP—no longer auto-spawned as a child process by the client.

# 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 listening parameters:

skynet debug console connection parameters:

• Endpoint URL: http://127.0.0.1:8765/mcp (MCP streamable-http protocol), clients such as opencode / skynet-mcp-client all connect through this endpoint

• Security: binds to 127.0.0.1 by default with DNS rebinding protection enabled; for cross-machine access, use --http-host 0.0.0.0 and ensure the network is trusted (or use an SSH tunnel), never expose to the public internet

Connecting to opencode

First start the MCP server independently as described above, then connect with type: "remote". The configuration must be written on the side where opencode runs—opencode only reads the global config on its own process side ~/.config/opencode/opencode.json + the project-level opencode.json in the current directory; opencode launched on the Windows side cannot see config inside WSL (shown as opencode mcp list displaying 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 launched inside WSL: write the WSL project root opencode.json (already included in this repo) or the global ~/.config/opencode/opencode.json

• opencode launched on the Windows side (PowerShell / Desktop): write the Windows global C:\Users\Admin\.config\opencode\opencode.json (merge and keep existing content such as instructions) or the project-level opencode.json in the launch directory. The url still uses http://127.0.0.1:8765/mcp—WSL2 localhost forwarding passes the Windows-side 127.0.0.1:8765 straight through to the MCP process listening inside WSL, no need to change the MCP listen address

• The MCP server must be started independently (manually or managed by a process manager); opencode no longer auto-spawns child processes; if the server is not running, opencode will show a connection failure

• For LAN/public network access, restart MCP with --http-host 0.0.0.0—but the server has no authentication and includes dangerous commands like kill / inject / raw_command, so only an SSH tunnel (ssh -L 8765:127.0.0.1:8765 user@remote) or Bearer Token authentication is recommended; do not expose directly to the public internet

After making changes, restart opencode, type /mcp in the conversation to confirm skynet is connected, then ask it to "use the skynet tools to list all current services" for an end-to-end verification. Full testing and troubleshooting steps are in examples/opencode-mcp.md; test prompts covering all 32 tools are in examples/mcp-test-prompts.md.

Deployment Methods

1. Direct connection inside WSL/Linux (recommended): opencode, the MCP process, and skynet are all inside WSL, connecting directly to 127.0.0.1:<port>, zero forwarding

2. SSH tunnel (remote production machine): when the MCP process and skynet are on different machines, use ssh -L 8000:127.0.0.1:8000 user@remote, and opencode connects to local port 8000. Never expose the debug console port directly to the public internet

Tool List (32 tools)

Address notation: :01000001 (eight hex digits), 1 (shorthand), .name (local service name).

Security Notes

• The skynet debug console has no authentication and only listens on 127.0.0.1—for remote use, go through an SSH tunnel, do not expose the port

• 【Dangerous】commands (kill/exit/signal/inject/call/raw_command) affect running services; this is marked in the tool descriptions; the coding agent should have the user confirm before calling

• The debug interactive command requires a persistent terminal session, which the HTTP channel does not support, so it is explicitly rejected (use telnet/nc to connect manually)

• The script path for inject is from the skynet server's perspective (MCP and skynet may be on different file systems)

Development and Testing

Copy-paste prompts for end-to-end testing of all 32 skynet_* tools through opencode are in examples/mcp-test-prompts.md; below are developer-side unit/smoke tests.

# 单元测试
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