skynet-mcp

Kapselt die Debug-Befehle der DebugConsole des skynet-Spielserver-Frameworks als MCP (Model Context Protocol) Tools, sodass Coding-Agenten (wie opencode) die skynet-Debug-Konsole direkt über natürliche Sprache steuern können – ohne sich list / mem / call / inject und andere Befehle merken zu müssen.

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

Funktionen

• 32 MCP-Tools, die alle Befehle der Debug-Konsole abdecken (siehe Tool-Liste unten)

• raw_command Fallback-Tool: leitet beliebige Befehlszeilen unverändert durch, kompatibel mit zukünftigen neuen Befehlen

• 2 Ressourcen: skynet://services (Live-Serviceliste), skynet://help (Befehlshilfe)

• 1 Prompt-Vorlage: skynet_troubleshoot (generiert Fehlerbehebungsschritte in der Reihenfolge "nur lesen → gefährlich")

• Befehle mit Nebenwirkungen (kill/exit/inject/call/signal/...) werden niemals automatisch wiederholt; bei Übertragungsfehlern von Nur-Lese-Befehlen wird einmal automatisch wiederholt.

Related MCP server: mc-mcp-server

Kommunikationsprinzip

Die skynet-Debug-Konsole unterstützt einen HTTP-Kanal (POST / HTTP/1.0, der Body ist die Befehlszeile, die Antwort ist roher Text + <CMD OK> / <CMD Error> Marker, danach wird die Verbindung geschlossen). Dieses Projekt konstruiert diese Anfrage manuell mit dem Standard-Socket:

• Warum nicht http.client/requests: Die Antwort von skynet hat keine HTTP-Statuszeile (curl benötigt --http0.9), Standard-HTTP-Clients können sie nicht parsen.

• Warum POST statt GET: Der Body von POST wird vom Server docmd(body) unverändert als Befehlszeile ausgeführt, Anführungszeichen, Kommas und Schrägstrichpfade in call 3 "foo", 1, "bar" / inject 3 /home/x/patch.lua werden nicht durch URL-Kodierung beschädigt.

Projektstruktur

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, auf demselben Rechner wie 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

Start

Der MCP-Server wird unabhängig über streamable-http gestartet (manuell oder von einem Prozessmanager wie systemd / supervisor verwaltet), lauscht auf einem festen Port und wird von Clients wie opencode über HTTP remote verbunden – nicht mehr automatisch vom Client als Unterprozess gestartet.

# 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-Listener-Parameter:

Verbindungsparameter der skynet-Debug-Konsole:

• Endpunkt-URL: http://127.0.0.1:8765/mcp (MCP streamable-http Protokoll), Clients wie opencode / skynet-mcp-client verbinden sich über diesen Endpunkt.

• Sicherheit: Standardmäßig an 127.0.0.1 gebunden und DNS-Rebinding-Schutz aktiviert; für Zugriff über mehrere Rechner --http-host 0.0.0.0 verwenden und sicherstellen, dass das Netzwerk vertrauenswürdig ist (oder SSH-Tunnel verwenden), nicht öffentlich freigeben.

Anbindung an opencode

Starten Sie zuerst den MCP-Server unabhängig wie oben beschrieben und verbinden Sie sich dann mit type: "remote". Die Konfiguration muss auf der Seite geschrieben werden, auf der opencode läuft – opencode liest nur die globale Konfiguration ~/.config/opencode/opencode.json auf seiner eigenen Prozessseite plus die projektbezogene opencode.json im aktuellen Verzeichnis; opencode, das auf der Windows-Seite gestartet wird, sieht die Konfiguration in WSL nicht (erscheint als opencode mcp list zeigt 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 in WSL starten: Schreiben Sie opencode.json im Projektstamm von WSL (im Repository enthalten) oder global ~/.config/opencode/opencode.json.

• opencode auf der Windows-Seite starten (PowerShell / Desktop): Schreiben Sie die Windows-globale C:\Users\Admin\.config\opencode\opencode.json (bei vorhandenem Inhalt wie instructions zusammenführen und beibehalten) oder die projektbezogene opencode.json im Startverzeichnis. url bleibt http://127.0.0.1:8765/mcp – die WSL2-localhost-Weiterleitung leitet 127.0.0.1:8765 von der Windows-Seite direkt an den in WSL lauschenden MCP-Prozess weiter, keine Änderung der MCP-Listener-Adresse erforderlich.

• Der MCP-Server muss unabhängig gestartet werden (manuell oder von einem Prozessmanager verwaltet), opencode startet keine Unterprozesse mehr automatisch; wenn der Server nicht läuft, zeigt opencode einen Verbindungsfehler an.

• Für LAN/öffentlichen Zugriff muss MCP mit --http-host 0.0.0.0 neu gestartet werden – aber der Server hat keine Authentifizierung und gefährliche Befehle wie kill / inject / raw_command, daher wird nur ein SSH-Tunnel empfohlen (ssh -L 8765:127.0.0.1:8765 user@remote) oder Bearer-Token-Authentifizierung hinzufügen, nicht direkt öffentlich freigeben.

Nach den Änderungen opencode neu starten, im Chat /mcp eingeben, um zu bestätigen, dass skynet verbunden ist, und dann lassen Sie es "mit skynet-Tools alle aktuellen Dienste auflisten" für eine End-to-End-Verifikation. Vollständige Test- und Fehlerbehebungsschritte finden Sie in examples/opencode-mcp.md; Test-Prompts, die alle 32 Tools abdecken, finden Sie in examples/mcp-test-prompts.md.

Bereitstellungsmethoden

1. Direkte Verbindung in WSL/Linux (empfohlen): opencode, MCP-Prozess und skynet befinden sich alle in WSL, direkte Verbindung zu 127.0.0.1:<port>, keine Weiterleitung.

2. SSH-Tunnel (entfernte Produktionsmaschine): Wenn MCP-Prozess und skynet auf verschiedenen Rechnern laufen, ssh -L 8000:127.0.0.1:8000 user@remote, opencode verbindet sich mit lokalem Port 8000. Den Debug-Console-Port niemals direkt öffentlich freigeben.

Tool-Liste (32)

Adressschreibweise: :01000001 (achtstelliges Hex), 1 (Kurzform), .Name (lokaler Dienstname).

Sicherheitshinweise

• Die skynet-Debug-Konsole hat keine Authentifizierung und lauscht nur auf 127.0.0.1 – für Remote-Nutzung SSH-Tunnel verwenden, Port nicht freigeben.

• 【Gefährliche】Befehle (kill/exit/signal/inject/call/raw_command) beeinflussen laufende Dienste, in der Tool-Beschreibung markiert; Coding-Agent sollte vor dem Aufruf die Benutzerbestätigung einholen.

• Der interaktive Befehl debug benötigt eine persistente Terminalsitzung, die der HTTP-Kanal nicht unterstützt, wurde explizit abgelehnt (bitte manuell mit telnet/nc verbinden).

• Der Skriptpfad von inject ist aus Sicht des skynet-Servers (MCP und skynet können sich auf unterschiedlichen Dateisystemen befinden).

Entwicklung und Tests

Reproduzierbare Prompts für End-to-End-Tests aller 32 skynet_*-Tools über opencode finden Sie in examples/mcp-test-prompts.md; unten sind die Unit-/Smoke-Tests für Entwickler.

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