skynet-mcp

skynet 게임 서버 프레임워크의 DebugConsole 디버그 명령을 MCP(Model Context Protocol) 도구로 캡슐화하여, coding agent(예: opencode)가 자연어로 skynet 디버그 콘솔을 직접 구동할 수 있게 합니다. list / mem / call / inject 같은 명령을 더 이상 외울 필요가 없습니다.

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

기능

• MCP 도구 32개, 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는 연결 실패를 표시

• LAN/공개망 접근은 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>로 직접 연결, 포워딩 0회

2. SSH 터널(원격 운영 머신): MCP 프로세스와 skynet이 다른 머신일 때 ssh -L 8000:127.0.0.1:8000 user@remote, opencode는 로컬 8000으로 연결하면 됩니다. 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