IoEHub MQTT MCP 서버

IoEHub MQTT MCP 서버

1. 개요

이 문서는 MQTT를 통해 온도 센서 데이터를 읽고 LED를 제어하는 MCP(Model Context Protocol) 서버를 설명합니다. 이 서버는 FastMCP 프레임워크를 기반으로 하며, JSON-RPC 프로토콜을 사용하여 통신합니다.

1.1 구조도

MCP Client (Claude AI) MCP Server (Python/FastMCP)

JSON-RPC (stdio) Request/Response

MQTT Broker (172.30.1.100)

MQTT (JSON)

IoT Device (Temperature/LED)

MQTT (JSON)

1.2 主なコンポーネント：

1. MCP クライアント（Claude AI）

• ユーザーインターフェースを提供します

• MCP サーバーに JSON-RPC リクエストを送信します

• 結果をユーザーに表示します

1. MCP サーバー（Python/FastMCP）

• クライアントのリクエストを処理します

• MQTT ブローカーと通信します

• JSON-RPC と MQTT のプロトコル間を変換します

1. MQTT ブローカー（172.30.1.100）

• MQTT メッセージの中央ハブです

• サーバーとデバイス間でメッセージをルーティングします

• パブリッシュ／サブスクライブのメッセージパターンを処理します

1. IoT デバイス（温度センサー／LED）

• 物理ハードウェアデバイスです

• 温度データを提供します

• コマンドに基づいて LED の状態を制御します

データフロー：

1. クライアント → サーバー：関数呼び出し ioehub_mqtt_get_temperature() または ioehub_mqtt_set_led()

2. サーバー → ブローカー：MQTT メッセージをパブリッシュします（トピック：ioehub/mcp/command）

3. ブローカー → デバイス：コマンドを該当するデバイスに転送します

4. デバイス → ブローカー：データを含む応答をパブリッシュします（トピック：ioehub/mcp/response）

5. ブローカー → サーバー：サブスクライブしているサーバーに応答を配信します

6. サーバー → クライアント：処理済みデータを含む関数呼び出しの結果を返します

この縦方向のレイアウトにより、クライアントからサーバー、ブローカーを経て IoT デバイスに至る通信の階層的な流れが明確に示されます。

2. システム構成

• フレームワーク：FastMCP
• 通信プロトコル：MQTT、JSON-RPC 2.0
• 実装言語：Python
• サポート機能：温度測定、LED 制御

3. MQTT 設定

MQTT_BROKER = "172.30.1.100"
MQTT_PORT = 1883
MQTT_USERNAME = "ioehub"
MQTT_PASSWORD = "password"
MQTT_PUBLISH_TOPIC = "ioehub/mcp/command"
MQTT_SUBSCRIBE_TOPIC = "ioehub/mcp/response"

4. 実装済み機能

4.1 温度測定（ioehub_mqtt_get_temperature）

• 説明：MQTT を介して温度センサーから現在の温度データを読み取ります。
• 戻り値：現在の温度（摂氏）を文字列で返します
• デフォルトピン：13 番

4.2 LED 制御（ioehub_mqtt_set_led）

• 説明：MQTT を介して指定したピンの LED の状態を制御します。
• パラメーター：
  • pin（整数）：LED のピン番号（デフォルト値：0）
  • state（整数）：LED の状態（1=オン、0=オフ）
• 戻り値：処理の成功 여부（True/False）

5. メッセージ形式

5.1 温度測定リクエスト

{
  "function": "ioehub_mqtt_get_temperature",
  "params": {
    "pin": 13
  }
}

5.2 温度測定レスポンス

{
  "function": "ioehub_mqtt_get_temperature",
  "result": 26.5,
  "timestamp": "749817"
}

5.3 LED 制御リクエスト

{
  "function": "ioehub_mqtt_set_led",
  "params": {
    "pin": 0,
    "state": 1
  }
}

5.4 LED 制御レスポンス

{
  "function": "ioehub_mqtt_set_led",
  "result": true,
  "timestamp": "749820"
}

6. 動作方法

1. サーバーの初期化：

   • MQTT クライアントを作成して設定します
   • サブスクライブするトピックを設定します（ioehub/mcp/response）
   • FastMCP インスタンスを作成します

2. 接続プロセス：

   • MQTT ブローカーに接続します
   • バックグラウンドスレッドでメッセージの受信を待機します

3. 関数呼び出しの処理：

   • MCP ツールの呼び出し時に該当する関数を実行します
   • MQTT を介してリクエストを送信します
   • 応答を待機します（最大 5 秒）
   • 結果を返します

4. メッセージ受信の処理：

   • サブスクライブしているトピックからメッセージを受信します
   • JSON を解析してデータを抽出します
   • 応答フラグを設定します

7. エラー処理

• 応答タイムアウト：5 秒以内に応答がない場合、デフォルト値を返します
• JSON 解析エラー：形式が正しくないメッセージを処理します
• MQTT 接続エラー：接続に失敗した場合、エラーメッセージを出力します

8. 使用方法

8.1 サーバーの実行

python mcp_server.py

8.2 クライアントからの関数呼び出し

# MCP 클라이언트 예시
temperature = client.invoke("ioehub_mqtt_get_temperature")
print(f"현재 온도: {temperature}°C")

# LED 켜기
result = client.invoke("ioehub_mqtt_set_led", {"pin": 0, "state": 1})
print(f"LED 켜기 결과: {'성공' if result else '실패'}")

9. MCP サーバーの設定（Windows 版 Claude デスクトップ）

{
  "mcpServers": {
    "IoEHubMqttMcpServer": {
        "command": 
           "Your project path\\.venv\\Scripts\\python.exe",

        "args": [
	        "Your project path\\mcp_server.py"
	        ]

    }    
  }
}

10. Python 環境の構築（Windows）

cd "your project path"
uv venv .venv
uv pip install mcp
uv pip install paho-mqtt 

11. 制限事項と注意事項

• MQTT ブローカーが実行中である必要があります。
• 応答を処理する際は、「function」フィールドを確認して適切な応答を識別します。
• すべてのデバッグメッセージは stdout ではなく stderr に出力する必要があります。
• 実際のハードウェアと通信するには、該当するデバイス上で MQTT クライアントが実行されている必要があります。