network-mcp

Servidor HTTP MCP independiente para la gestión de la red doméstica a través de una UniFi Dream Machine.

La implementación actual del controlador utiliza la API local de la interfaz/controlador de UniFi Network porque admite el comportamiento de bloqueo directo de clientes necesario para la gestión de dispositivos en texto plano. El resto de la aplicación depende de una pequeña interfaz NetworkController para que esta pueda reemplazarse o complementarse con la API oficial de UniFi Network más adelante.

Configuración

bun install
cp .env.example .env
bun run start

El servicio escucha en 127.0.0.1:4123 por defecto.

Docker

Para la configuración alojada/doméstica, ejecútalo con Docker Compose:

cp .env.example .env
docker compose up -d --build

El archivo compose vincula el servicio a 0.0.0.0 dentro del contenedor, lo publica solo en el bucle local del host en 127.0.0.1:4123 y persiste los datos de LowDB en ./data.

Reconstruye/reinicia tras los cambios de código:

docker compose up -d --build

Consulta los registros:

docker compose logs -f network-mcp

Los registros se emiten como JSON a stdout con Winston. Establece LOG_LEVEL=debug para incluir el tiempo de las solicitudes de UniFi y los diagnósticos de las solicitudes MCP.

Puntos de conexión

• GET /health

• POST /mcp

• GET /mcp

• DELETE /mcp

Si MCP_AUTH_TOKEN está definido, /mcp requiere:

Authorization: Bearer <token>

Configuración de OpenCode

Añade un servidor MCP remoto a /home/zac/.config/opencode/opencode.json:

{
  "mcp": {
    "home-network": {
      "type": "remote",
      "url": "http://127.0.0.1:4123/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:HOME_NETWORK_MCP_TOKEN}"
      }
    }
  }
}

Reinicia el servicio OpenCode alojado después de cambiar la configuración de MCP.

Herramientas

• list_clients

• find_device

• add_tag

• remove_tag

• list_tags

• add_displayname

• block_device

• unblock_device

• block_by_tag

• unblock_by_tag

• show_blocked

• unblock_all

• recent_actions

Las direcciones MAC son la clave canónica del dispositivo. Las etiquetas y los nombres para mostrar se almacenan localmente en LowDB bajo DB_PATH.