skynet-mcp

Envuelve los comandos de depuración del DebugConsole del framework de servidores de juegos skynet como herramientas MCP (Model Context Protocol), para que los agentes de codificación (como opencode) puedan controlar directamente la consola de depuración de skynet mediante lenguaje natural — sin necesidad de memorizar comandos como list / mem / call / inject.

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

Funciones

• 32 herramientas MCP, que cubren todos los comandos de la consola de depuración (ver la lista de herramientas más abajo)

• Herramienta de respaldo raw_command: transmite cualquier línea de comando tal cual, compatible con comandos futuros

• 2 recursos: skynet://services (lista de servicios en tiempo real), skynet://help (ayuda de comandos)

• 1 plantilla de prompt: skynet_troubleshoot (genera pasos de diagnóstico en orden de "solo lectura → peligroso")

• Los comandos con efectos secundarios (kill/exit/inject/call/signal/...) nunca se reintentan automáticamente; los comandos de solo lectura se reintentan una vez automáticamente si falla la transmisión

Related MCP server: mc-mcp-server

Principio de comunicación

La consola de depuración de skynet admite el canal HTTP (POST / HTTP/1.0, el body es la línea de comando, la respuesta es texto plano + marcador <CMD OK> / <CMD Error> y luego se cierra la conexión). Este proyecto construye manualmente dicha solicitud con sockets de la biblioteca estándar:

• Por qué no usar http.client/requests: la respuesta de skynet no tiene línea de estado HTTP (curl necesita --http0.9), los clientes HTTP estándar no pueden analizarla

• Por qué usar POST en lugar de GET: el body del POST es ejecutado tal cual por el servidor como línea de comando mediante docmd(body), las comillas, comas y rutas con barras de call 3 "foo", 1, "bar" / inject 3 /home/x/patch.lua no se ven dañadas por la codificación de URL

Estructura del proyecto

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

Instalación (Linux, en la misma máquina que 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

Inicio

El servidor MCP se inicia de forma independiente mediante streamable-http (manualmente, o gestionado por systemd / supervisor u otros gestores de procesos), escuchando en un puerto fijo, y los clientes como opencode se conectan de forma remota a través de HTTP — ya no es el cliente quien lanza el subproceso automáticamente.

# 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

Parámetros de escucha HTTP:

Parámetros de conexión a la consola de depuración de skynet:

• URL del endpoint: http://127.0.0.1:8765/mcp (protocolo MCP streamable-http), clientes como opencode / skynet-mcp-client se conectan a través de este endpoint

• Seguridad: por defecto se vincula a 127.0.0.1 y se activa la protección contra DNS rebinding; si se necesita acceso entre máquinas, usa --http-host 0.0.0.0 y asegúrate de que la red sea de confianza (o usa un túnel SSH), no lo expongas a la red pública

Integración con opencode

Primero inicia el servidor MCP de forma independiente como se indicó arriba, y luego conéctate con type: "remote". La configuración debe escribirse en el lado donde se ejecuta opencode — opencode solo lee la configuración global de su propio proceso ~/.config/opencode/opencode.json + la configuración a nivel de proyecto opencode.json del directorio actual; el opencode iniciado en el lado de Windows no ve la configuración de WSL (se manifiesta como opencode mcp list mostrando No MCP servers configured).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "skynet": {
      "type": "remote",
      "url": "http://127.0.0.1:8765/mcp",
      "enabled": true
    }
  }
}

• Iniciar opencode dentro de WSL: escribe el opencode.json de la raíz del proyecto en WSL (este repositorio ya lo incluye) o el global ~/.config/opencode/opencode.json

• Iniciar opencode en el lado de Windows (PowerShell / Desktop): escribe el global de Windows C:\Users\Admin\.config\opencode\opencode.json (si ya hay contenido como instructions, combínalo y consérvalo) o el opencode.json a nivel de proyecto del directorio de inicio. La url sigue siendo http://127.0.0.1:8765/mcp — el reenvío de localhost de WSL2 hace que 127.0.0.1:8765 del lado de Windows llegue directamente al proceso MCP que escucha en WSL, no es necesario cambiar la dirección de escucha del MCP

• El servidor MCP debe iniciarse de forma independiente (manualmente o gestionado por un gestor de procesos); opencode ya no lanza subprocesos automáticamente; si el servidor no está iniciado, opencode mostrará un error de conexión

• Para acceso desde LAN/red pública hay que reiniciar el MCP con --http-host 0.0.0.0 — pero el servidor no tiene autenticación y tiene comandos peligrosos como kill / inject / raw_command, por lo que solo se recomienda usar un túnel SSH (ssh -L 8765:127.0.0.1:8765 user@remote) o añadir autenticación Bearer Token, no lo expongas directamente a la red pública

Después de los cambios, reinicia opencode, escribe /mcp en el chat para confirmar que skynet está conectado, y luego pídele "usa las herramientas de skynet para listar todos los servicios actuales" para verificar de extremo a extremo. Los pasos completos de prueba y resolución de problemas están en examples/opencode-mcp.md; los prompts de prueba que cubren las 32 herramientas están en examples/mcp-test-prompts.md.

Formas de despliegue

1. Conexión directa dentro de WSL/Linux (recomendado): opencode, el proceso MCP y skynet están todos dentro de WSL, conexión directa a 127.0.0.1:<port>, cero reenvíos

2. Túnel SSH (máquina de producción remota): cuando el proceso MCP y skynet están en máquinas distintas, ssh -L 8000:127.0.0.1:8000 user@remote, opencode se conecta al 8000 local. Nunca expongas el puerto de la consola de depuración directamente a la red pública

Lista de herramientas (32)

Formato de direcciones: :01000001 (hex de ocho dígitos), 1 (abreviado), .nombre (nombre de servicio local).

Notas de seguridad

• La consola de depuración de skynet no tiene autenticación y solo escucha en 127.0.0.1 — para uso remoto usa un túnel SSH, no expongas el puerto

• Los comandos 【Peligrosos】 (kill/exit/signal/inject/call/raw_command) afectan a los servicios en ejecución; ya están marcados en las descripciones de las herramientas; el agente de codificación debe pedir confirmación al usuario antes de llamarlos

• El comando interactivo debug requiere una sesión de terminal persistente, el canal HTTP no lo soporta, por lo que se rechaza explícitamente (usa telnet/nc para conectarte manualmente)

• La ruta del script de inject es desde la perspectiva del servidor skynet (MCP y skynet pueden estar en sistemas de archivos diferentes)

Desarrollo y pruebas

Los prompts reproducibles para probar de extremo a extremo las 32 herramientas skynet_* a través de opencode están en examples/mcp-test-prompts.md; a continuación están las pruebas unitarias/de humo del lado del desarrollador.

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