Agent Node

LAN multi-machine agent collaboration node. Deploy one on each computer to form a "multi-machine multi-agent collaboration team": automatic LAN peer discovery, symmetric controlled/remote command execution, system tray status visibility, cross-node file send/receive, and a built-in MCP Server for AI clients to call.

A minimal standalone project extracted from the agent-bus repository. Runs from source; no packaged distribution.

1. Capabilities

2. Use Cases

• Multi-machine multi-agent collaboration: An AI client wraps the capabilities of multiple computers as tools via MCP and orchestrates them across machines.

• LAN remote operations / debugging: Issue commands from any node to other nodes and retrieve results.

• Cross-machine file transfer: Send and receive single files / directories (automatically zipped) in both directions.

• AI client integration: Wrap "send task / check inbox / execute command / read & write files / upload & download" into standard tools for Claude / Cursor to call.

3. Technical Architecture

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

• Communication layer: MQTT (mosquitto), messages routed by topic (agent/<id>/inbox, bus/register, bus/heartbeat/), QoS 1, retain registration + last will for offline detection.

• Discovery layer: UDP broadcast beacon (255.255.255.255:41830), symmetric with no master/slave; on startup, workers automatically scan for is_master nodes to obtain the real broker address (no manual configuration needed).

• File layer: HTTP (bus_server, FastAPI), Claim-Check upload/download, automatic directory zipping / safe extraction (prevents path traversal + zip-slip).

• Hub: The hub role starts mosquitto inline (reuses an existing local install, otherwise extracts from build/mosquitto.zip on first start) + bus_server + Web panel.

• MCP: FastMCP over stdio transport, decoupled from GUI mode and can be started independently.

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

4. Installation

4.1 Prerequisites

• Python 3.10+ (all machines)

• LAN connectivity + firewall rules (inbound on the hub side):

  • TCP 1883 (MQTT, port pool may fall back to 1884/1885/8883/18830)

  • TCP 8000 (HTTP panel/files, pool fallback 8001/8002/8010/8088)

  • UDP 41830 (discovery broadcast)

4.2 Hub host (one machine)

Requires the full project directory + 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: Automatically reused if already installed (shutil.which("mosquitto") or C:\Program Files\mosquitto); otherwise, it is automatically extracted from build/mosquitto.zip to data/runtime/mosquitto on first start, so build/ must be kept.

• Web panel: After startup, open http://127.0.0.1:8000/ in a browser (if the port pool falls back, check the startup log for the actual port).

• On first start, the hub creates data/ (bus.db, files, broker.log, node_config.json); no pre-provisioning needed.

4.3 Worker (other machines)

Only a minimal subset is needed: the agent_bus/ package + executor/control_app.py + requirements.txt (none of server/, build/, scripts/ are needed).

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

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

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

• No broker address configuration needed: without --broker-host, the worker automatically scans the LAN for is_master nodes to obtain the real address (all three: host / MQTT port / HTTP port).

• Manually specify the hub (cross-subnet / when auto-discovery fails): python executor/control_app.py --broker-host 192.168.1.10

• The inbox is automatically placed in Downloads/agent-node/inbox, and the data/ config directory is auto-generated; no pre-provisioning needed.

4.4 Minimal File Manifest

5. Command-Line Arguments

Port pools

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

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

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

6. MCP Configuration (for AI clients)

--mcp uses stdin/stdout so that Claude Desktop / Cursor etc. can launch it as an MCP Client via JSON configuration.

{
  "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 is optional — workers will auto-discover the hub; specify it explicitly when crossing subnets or when discovery fails.

7. Directory Structure

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. Security Model

This project is designed for trusted LANs: the broker uses allow_anonymous, control messages travel in plaintext over MQTT, and only a sender_id prefix allowlist is enforced (the control plane only accepts hub-* identities). It does not provide HMAC signing / encryption / node allowlisting — harden it yourself when crossing untrusted networks.