Agent Node

Nodo de colaboración multiagente en LAN para múltiples máquinas. Despliega uno en cada equipo y podrás formar un «equipo de colaboración multiagente entre varias máquinas»: descubrimiento mutuo automático en LAN, ejecución simétrica de comandos controlados/remotos, estado visible en la bandeja del sistema, envío y recepción de archivos entre nodos, y servidor MCP integrado para que los clientes de IA lo invoquen.

Proyecto independiente minimizado, extraído del repositorio agent-bus. Se ejecuta desde el código fuente, sin entrega empaquetada.

1. Diseño de capacidades

2. Escenarios de uso

• Colaboración multiagente entre varias máquinas: un cliente de IA encapsula las capacidades de varios equipos como herramientas a través de MCP y las orquesta entre máquinas.

• Operación y depuración remota en LAN: desde cualquier nodo, envía comandos a otros nodos y recupera los resultados.

• Transferencia de archivos entre máquinas: envío y recepción bidireccional de archivos individuales / directorios (empaquetado automático en zip).

• Integración con clientes de IA: encapsula «enviar tarea / consultar bandeja de entrada / ejecutar comando / leer y escribir archivos / subir y descargar» como herramientas estándar para que Claude / Cursor las invoquen.

3. Arquitectura técnica

┌──────────── 中心节点 (一台, --role hub) ────────────┐
│  mosquitto (MQTT broker)                           │
│  bus_server (FastAPI + SQLite, Web 面板 + 文件服务) │
│  自身控制节点 (带全部功能)                            │
└────────────────────────────────────────────────────┘
          ▲ MQTT / HTTP               ▲ UDP beacon 发现
          │                           │
┌─────────┴─────────┐       ┌─────────┴─────────┐
│ worker (对称控制节点) │  ...  │ worker (对称控制节点) │
│ 连总线 + 受控/遥控    │       │ 连总线 + 受控/遥控    │
└───────────────────┘       └───────────────────┘

• Capa de comunicación: MQTT (mosquitto), los mensajes se enrutan por topic (agent/<id>/inbox, bus/register, bus/heartbeat/), QoS 1, registro con retain + testamento para desconexión.

• Capa de descubrimiento: beacon de difusión UDP (255.255.255.255:41830), simétrico sin maestro/esclavo; el worker escanea automáticamente los nodos is_master al iniciarse para obtener la dirección real del broker (sin configuración manual).

• Capa de archivos: HTTP (bus_server, FastAPI), carga/descarga con patrón Claim-Check, directorios con zip automático / descompresión segura (protección contra path traversal y zip-slip).

• Centro: el rol hub inicia mosquitto de forma integrada (si está instalado en la máquina lo reutiliza; si no, en el primer arranque lo descomprime desde build/mosquitto.zip) + bus_server + panel web.

• MCP: FastMCP por transporte stdio, desacoplado del modo GUI, se puede iniciar de forma independiente.

Herramientas MCP (10): list_online_agents · send_task · check_inbox · run_command · read_file · upload_file · download_file · fetch_file · post_file · reply_task

4. Instalación

4.1 Requisitos previos

• Python 3.10+ (en todas las máquinas)

• Interconexión LAN + firewall que permita el tráfico entrante (en el lado del hub):

  • TCP 1883 (MQTT; el pool de puertos puede retroceder a 1884/1885/8883/18830)

  • TCP 8000 (panel HTTP/archivos; el pool retrocede a 8001/8002/8010/8088)

  • UDP 41830 (difusión de descubrimiento)

4.2 Máquina principal del hub (una)

Se necesita el directorio completo del proyecto + mosquitto.

# 1. 获取代码（git clone 或拷贝整个 agent-node 文件夹）
git clone <本仓库地址>

# 2. 安装依赖
cd agent-node
pip install -r requirements.txt

# 3. 启动中心节点（起 broker + Web 面板 + 自身控制节点 + 托盘）
python executor/control_app.py --role hub

• mosquitto: si está instalado en la máquina, se reutiliza automáticamente (shutil.which("mosquitto") o C:\Program Files\mosquitto); si no está instalado, en el primer arranque se descomprime automáticamente desde build/mosquitto.zip a data/runtime/mosquitto, por lo que build/ debe conservarse.

• Panel web: tras el arranque, abre el navegador en http://127.0.0.1:8000/ (si el pool de puertos retrocede, consulta el puerto real en el log de arranque).

• El primer arranque del hub crea data/ (bus.db, files, broker.log, node_config.json), sin necesidad de preconfigurarlo.

4.3 Workers en otras máquinas (varias)

Solo se necesita el subconjunto reducido: el paquete agent_bus/ + executor/control_app.py + requirements.txt (no se necesitan server/, build/ ni scripts/).

# 1. 拷贝精简子集到目标机器（或 git clone 后仅运行，多余的目录会被自动忽略）
#    agent_bus/  executor/control_app.py  requirements.txt

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动 worker（无参数，自动扫描局域网中心）
python executor/control_app.py

• Sin necesidad de configurar la dirección del broker: si el worker no recibe --broker-host, escanea automáticamente los nodos is_master de la LAN para obtener la dirección real (host / puerto MQTT / puerto HTTP, los tres).

• Especificación manual del centro (para segmentos de red distintos / si falla el descubrimiento automático): python executor/control_app.py --broker-host 192.168.1.10

• La bandeja de entrada cae automáticamente en Downloads/agent-node/inbox; el directorio de configuración data/ se genera automáticamente. Nada requiere preconfiguración.

4.4 Lista de archivos reducida

5. Parámetros de comando

Pool de puertos

• MQTT: 1883 → 1884 → 1885 → 8883 → 18830

• HTTP: 8000 → 8001 → 8002 → 8010 → 8088

• Descubrimiento: 41830 → 41831 → 41832 → 41840 → 41850

6. Configuración de MCP (para clientes de IA)

--mcp usa stdin/stdout, para que Claude Desktop / Cursor, entre otros, lo lancen como cliente MCP mediante configuración JSON.

{
  "mcpServers": {
    "agent-node": {
      "command": "python",
      "args": [
        "C:/path/to/agent-node/executor/control_app.py",
        "--mcp", "--role", "worker", "--agent-id", "my-agent"
      ],
      "env": { "BUS_BROKER_HOST": "192.168.1.10" }
    }
  }
}

BUS_BROKER_HOST se puede omitir: el worker descubrirá el centro automáticamente; para segmentos de red distintos o si falla el descubrimiento, especifícalo explícitamente.

7. Estructura de directorios

agent-node/
├── executor/
│   └── control_app.py          # 节点主入口（对称 + 托盘 + MCP + 中心角色）
├── agent_bus/                  # 通信 SDK（client/config/discovery/provision/files/schema...）
├── server/
│   ├── bus_server.py           # 中心 HTTP + 消息服务（可编程 serve_bus_server 内联启动）
│   └── static/index.html       # Web 面板
├── scripts/
│   └── build_mosquitto_zip.py  # 重建 mosquitto 便携包
├── build/
│   └── mosquitto.zip           # 便携 mosquitto（hub 首启自解压）
├── docs/
│   ├── 需求与设计.md
│   └── BUGFIX_LOG_20260819.md
└── requirements.txt

8. Modelo de seguridad

Este proyecto está orientado a LAN de confianza: el broker usa allow_anonymous, los mensajes de control viajan en claro por MQTT, y solo se aplica una lista blanca de prefijo sender_id (el plano de control solo acepta identidades hub-*). No se implementa verificación HMAC / cifrado / lista blanca de nodos: para redes no confiables, deberás reforzarlo por tu cuenta.