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 クライアントでは解析できません

• なぜ GET ではなく POST を使うのか：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 に接続すれば OK。 debug console のポートを公網に直接公開してはいけません

ツール一覧（32 個）

アドレスの書き方：:01000001（8 桁 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