Agent Node

LAN内の複数マシン間で動作するインテリジェントエージェント連携ノード。各PCに1つデプロイするだけで、「複数マシン・複数エージェントの協働チーム」を構築可能：LAN内の自動相互検出、対称的な被制御/遠隔コマンド実行、システムトレイでの状態可視化、ノード間ファイル送受信、AIクライアントが呼び出せるMCP Server内蔵。

agent-bus リポジトリから切り出した最小構成の独立プロジェクト。ソースコードで実行し、パッケージ配布は行わない。

一、機能設計

二、利用シーン

• 複数マシン・複数エージェント協働：1つのAIクライアントがMCP経由で複数PCの機能をツールとしてカプセル化し、マシンを跨いでスケジューリング。

• LAN内リモート運用 / デバッグ：任意ノードから他ノードへコマンドを送信し、結果を取得。

• マシン間ファイル転送：単一ファイル / ディレクトリ（自動zip圧縮）の双方向送受信。

• AIクライアント接続：「タスク送信 / 受信箱確認 / コマンド実行 / ファイル読み書き / アップロード・ダウンロード」を標準ツールとしてカプセル化し、Claude / Cursor から呼び出し。

三、技術アーキテクチャ

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

• 通信層：MQTT（mosquitto）。メッセージはtopicでルーティング（agent/<id>/inbox、bus/register、bus/heartbeat/）、QoS 1、retain登録 + 遺言によるオフライン通知。

• 検出層：UDPブロードキャストbeacon（255.255.255.255:41830）、対称で主従なし。worker起動時に自動で is_master ノードをスキャンし、実際のbrokerアドレスを取得（手動設定不要）。

• ファイル層：HTTP（bus_server、FastAPI）。Claim-Check方式のアップロード/ダウンロード、ディレクトリ自動zip / 安全な解凍（パストラバーサル + zip-slip対策）。

• 中心：hubロールはmosquitto（本機にインストール済みなら再利用、なければ初回起動時に build/mosquitto.zip から解凍）+ bus_server + Webパネルをインライン起動。

• MCP：FastMCPはstdioトランスポートを使用。GUIモードと分離され、単独起動可能。

MCPツール（10個）：list_online_agents · send_task · check_inbox · run_command · read_file · upload_file · download_file · fetch_file · post_file · reply_task

四、インストール

4.1 前提条件

• Python 3.10+（全マシン）

• LAN内の通信が可能 + ファイアウォールで許可（hub側の受信）：

  • TCP 1883（MQTT、ポートプールで 1884/1885/8883/18830 にフォールバックする場合あり）

  • TCP 8000（HTTPパネル/ファイル、プールで 8001/8002/8010/8088 にフォールバック）

  • UDP 41830（検出ブロードキャスト）

4.2 hub マスター機（1台）

完全なプロジェクトディレクトリ + 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：本機にインストール済みなら自動再利用（shutil.which("mosquitto") または C:\Program Files\mosquitto）。未インストールなら初回起動時に自動で build/mosquitto.zip から data/runtime/mosquitto へ解凍。そのため build/ は必ず保持すること。

• Webパネル：起動後、ブラウザで http://127.0.0.1:8000/ を開く（ポートプールでフォールバックした場合は起動ログで実際のポートを確認）。

• hub初回起動時に data/（bus.db、files、broker.log、node_config.json）が自動作成される。事前準備は不要。

4.3 worker その他のマシン（複数台）

最小限のサブセットのみでOK：agent_bus/ パッケージ + executor/control_app.py + requirements.txt（server/、build/、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

• brokerアドレスの設定不要：workerは --broker-host 指定なしの場合、LAN内の is_master ノードを自動スキャンして実際のアドレスを取得（host / MQTTポート / HTTPポートの3点すべて）。

• 中心を手動指定（異なるセグメント / 自動検出失敗時）：python executor/control_app.py --broker-host 192.168.1.10

• 受信箱は自動的に Downloads/agent-node/inbox に配置。data/ 設定ディレクトリも自動生成。いずれも事前準備は不要。

4.4 最小ファイル構成

五、コマンドパラメータ

ポートプール

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

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

• 検出：41830 → 41831 → 41832 → 41840 → 41850

六、MCP設定（AIクライアント向け）

--mcp はstdin/stdoutを使用。Claude Desktop / Cursor などがMCP Clientとして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 は省略可能——workerは自動的に中心を検出。異なるセグメントや検出失敗時は明示的に指定。

七、ディレクトリ構造

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

八、セキュリティモデル

本プロジェクトは信頼できるLANを前提としている：brokerは allow_anonymous、制御メッセージは平文でMQTTを経由、sender_id プレフィックスによるホワイトリストのみ実施（制御面は hub-* 識別子のみ受け入れ）。HMAC署名検証 / 暗号化 / ノードホワイトリストは行わない——信頼できないネットワークを跨ぐ場合は自己責任でセキュリティ強化が必要。