Coreflux MQTT MCP Server

Coreflux MQTT MCP サーバー

Claude やその他の MCP 対応 AI アシスタントに、Coreflux MQTT ブローカーへの安全でスケーラブルなアクセスと包括的な自動化機能を提供する、エンタープライズグレードの Model Context Protocol（MCP）サーバーです。

🚀 機能

主な機能

• 🔌 MQTT 連携：TLS を完全にサポートし、Coreflux MQTT ブローカーにシームレスに接続します
• 🛠️ Coreflux API の完全サポート：モデル、アクション、ルール、ルートにフルアクセスできます
• 🤖 AI コード生成：Coreflux Copilot API による LOT（Language-of-Things）コード生成
• 🔍 動的検出：利用可能なアクションを自動的に検出して一覧表示します
• 🏥 ヘルスモニタリング：包括的なシステムのヘルスチェックとモニタリング

エンタープライズ機能

• 🔒 本番環境向けセキュリティ：包括的なログのサニタイズ、入力検証、セキュリティ機能
• ⚡ 非同期処理：レート制限とキュー管理を備えた、ノンブロッキングのメッセージ処理
• � 強化されたロギング：ローテーション、フィルタリング、セキュリティサニタイズを備えた構造化ロギング
• ✅ 設定の検証：包括的な環境およびファイルの検証システム
• 🧪 テストフレームワーク：モックとカバレッジレポート機能を備えた、完全なユニットテストスイート

DevOps とデプロイ

• 🐳 コンテナー対応：ヘルスチェックを備えた、Docker と Kubernetes の完全なデプロイサポート
• 🔄 CI/CD パイプライン：自動テスト、セキュリティスキャン、品質チェックに対応した GitHub Actions
• 📦 開発ツール：プリコミットフック、コードフォーマット、リンティング、ドキュメント生成
• ⚙️ 簡単なセットアップ：検証とテスト機能を備えた対話型セットアップアシスタント
• 📚 充実したドキュメント：API ドキュメント、セキュリティガイド、デプロイ手順

クイックスタート

Docker によるデプロイ（推奨）

1. クローンして設定：

   git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
   cd Coreflux-MQTT-MCP-Server
   cp .env.example .env
   # Edit .env with your configuration
   

2. Docker でデプロイ：

   docker-compose up -d
   

🚀 クイックスタート

前提条件

• Python 3.11 以上
• Docker（任意。コンテナー化されたデプロイに使用）
• Coreflux MQTT ブローカーへのアクセス
• Coreflux Copilot API キー（任意。AI 支援に使用）

オプション 1：Docker によるデプロイ（推奨）

1. クローンして設定：

   git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
   cd Coreflux-MQTT-MCP-Server
   cp .env.example .env
   # Edit .env with your configuration
   

2. Docker でデプロイ：

   docker-compose up -d
   

3. デプロイを確認：

   docker-compose logs -f coreflux-mcp-server
   

オプション 2：開発環境へのインストール

1. クローンしてセットアップ：

   git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
   cd Coreflux-MQTT-MCP-Server
   

2. 依存関係をインストール：

   pip install -r requirements.txt
   # For development
   pip install -r requirements-dev.txt
   

3. 環境を設定：

   python setup_assistant.py  # Interactive configuration
   # OR
   cp .env.example .env && nano .env  # Manual configuration
   

4. 検証してテスト：

   make validate  # Validate configuration
   make test      # Run tests
   

5. サーバーを起動：

   python server.py
   # OR
   make run
   

詳しいデプロイ手順については、DEPLOYMENT.md を参照してください。

⚙️ 設定

対話型セットアップアシスタント

このサーバーには、設定を案内する包括的なセットアップアシスタントが含まれています。

python setup_assistant.py

アシスタントでできること：

• 🔧 MQTT ブローカーの接続設定
• 🔐 TLS 証明書の設定
• 🤖 Coreflux Copilot API との連携
• 📝 ロギングとモニタリングの設定
• ✅ 設定の検証とテスト

次の場合にセットアップアシスタントを使用してください：

• 初期設定を作成するとき
• 既存の設定を更新するとき
• 接続の問題をトラブルシューティングするとき
• TLS 証明書を設定するとき
• 環境間で移行するとき

環境設定

.env.example を .env にコピーし、設定してください。

# MQTT Broker Configuration
MQTT_BROKER=your-broker-host.com
MQTT_PORT=8883
MQTT_USER=your-username
MQTT_PASSWORD=your-password
MQTT_USE_TLS=true

# TLS Configuration (when MQTT_USE_TLS=true)
MQTT_CA_CERT=/path/to/ca.crt
MQTT_CERT_FILE=/path/to/client.crt  
MQTT_KEY_FILE=/path/to/client.key

# Coreflux Copilot API
DO_AGENT_API_KEY=your-api-key-here

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=/var/log/coreflux-mcp.log

設定オプションの詳細については、設定ガイドを参照してください。

🔌 Claude を MCP サーバーに接続する

Claude Desktop を使用する

1. Claude Desktop の設定ファイルを確認します：

   • macOS/Linux：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json

2. サーバー設定を追加します：

   {
     "mcpServers": {
       "coreflux": {
         "command": "python",
         "args": ["/path/to/your/server.py"],
         "env": {
           "MQTT_BROKER": "your-broker-host.com",
           "MQTT_PORT": "8883",
           "MQTT_USER": "your-username", 
           "MQTT_PASSWORD": "your-password",
           "MQTT_USE_TLS": "true",
           "DO_AGENT_API_KEY": "your-copilot-api-key"
         }
       }
     }
   }
   

3. Claude Desktop を再起動します

セキュリティに関する注意：本番環境へのデプロイでは、Claude の設定ファイルではなく、安全な環境変数またはシークレット管理システムにシークレットを保存してください。

環境変数を使用する

セキュリティを強化するには、認証情報をハードコードせず、環境変数を使用してください。

{
  "mcpServers": {
    "coreflux": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "MQTT_BROKER": "${COREFLUX_MQTT_BROKER}",
        "MQTT_PORT": "${COREFLUX_MQTT_PORT}",
        "MQTT_USER": "${COREFLUX_MQTT_USER}",
        "MQTT_PASSWORD": "${COREFLUX_MQTT_PASSWORD}",
        "DO_AGENT_API_KEY": "${COREFLUX_API_KEY}"
      }
    }
  }
}

接続をテストする

設定が完了したら、Claude に次のように尋ねて接続をテストします。

Can you check the health of the Coreflux MCP server and show me the broker information?

接続に成功すると、Claude はシステムの状態とブローカーの詳細を返します。

🛠️ 利用可能なツール

このサーバーは、Claude に次のツールを提供します。

MQTT のコアツール

• publish_to_coreflux - QoS および保持オプションを指定して、MQTT トピックにメッセージをパブリッシュします
• get_broker_info - MQTT ブローカー接続の詳細情報を取得します

AI アシスタンスツール

• copilot_assist - 自動化の支援やコード生成について、Coreflux Copilot AI に問い合わせます

システム管理ツール

• comprehensive_health_check - すべてのシステムコンポーネントの詳細なヘルスチェックを実行します

API の詳細については、API_DOCUMENTATION.md を参照してください。

🧪 開発とテスト

開発環境のセットアップ

1. 開発用の依存関係をインストールします：

   pip install -r requirements-dev.txt
   

2. pre-commit フックをインストールします：

   pre-commit install
   

3. 開発環境を一括でセットアップします：

   make dev-setup  # Complete development environment setup
   

テスト

包括的なテストスイートを実行します。

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run specific test categories
make test-unit        # Unit tests only
make test-integration # Integration tests only

コード品質

自動化ツールを使用してコード品質を維持します。

# Format code
make format

# Run linters
make lint

# Security scanning
make security-check

# Type checking
make type-check

# Run all quality checks
make quality-check

利用可能な開発コマンド：

# Development workflow
make dev-setup     # Set up complete development environment
make validate      # Validate configuration and environment  
make run           # Start the server with validation
make run-debug     # Start server in debug mode

# Testing and validation
make test          # Run all tests
make test-coverage # Run tests with coverage report
make test-unit     # Run unit tests only
make validate-config # Validate configuration files

# Code quality
make format        # Format code with black and isort
make lint          # Run all linters (flake8, bandit, mypy)
make security-check # Run security scanning
make type-check    # Run type checking with mypy

# Docker operations  
make docker-build  # Build Docker image
make docker-run    # Run in Docker container
make docker-test   # Run tests in Docker

# Documentation
make docs          # Generate documentation
make docs-serve    # Serve documentation locally

🔧 システムアーキテクチャ

コアコンポーネント

• server.py - ツールを実装するメインの MCP サーバー
• config_validator.py - 設定の検証と環境チェック
• message_processor.py - レート制限機能を備えた非同期 MQTT メッセージ処理
• enhanced_logging.py - ローテーションとセキュリティフィルタリングに対応した構造化ログ
• config_schema.py - 型安全な設定のための Pydantic スキーマ
• parser.py - サニタイズおよび解析ユーティリティ

セキュリティ機能

• 入力のサニタイズ - インジェクション攻撃を防ぐため、すべての入力をサニタイズします
• ログのセキュリティ - ログ内の機密データを自動的にサニタイズします
• TLS のサポート - MQTT 接続を完全に TLS 暗号化します
• 設定の検証 - すべての設定パラメーターを包括的に検証します
• シークレット管理 - 認証情報と API キーを安全に取り扱います

パフォーマンス機能

• 非同期処理 - ブロッキングを伴わないメッセージ処理
• コネクションプーリング - 効率的な MQTT 接続管理
• レート制限 - 不正使用を防ぐ設定可能なレート制限
• ヘルスモニタリング - リアルタイムのヘルスチェックとシステム監視

📚 ドキュメント

• API ドキュメント - API リファレンスの完全版
• デプロイガイド - 本番環境へのデプロイ手順
• シークレット管理 - セキュリティとシークレット管理のガイド
• 設定リファレンス - 設定オプションの完全版

🐳 Docker デプロイ

Docker を使用したクイックスタート

# Clone and configure
git clone https://github.com/CorefluxCommunity/Coreflux-MQTT-MCP-Server.git
cd Coreflux-MQTT-MCP-Server

# Copy and edit environment file
cp .env.example .env
nano .env  # Configure your settings

# Start with Docker Compose
docker-compose up -d

# Check logs
docker-compose logs -f coreflux-mcp-server

# Health check
docker-compose exec coreflux-mcp-server python -c "
import os
os.system('python server.py --health-check')
"

本番環境への Docker デプロイ

マルチステージ Docker ビルド、Kubernetes へのデプロイ、ヘルスチェックと監視、負荷分散とスケーリング、セキュリティ設定を含む、本番環境への包括的なデプロイ手順については、DEPLOYMENT.md を参照してください。

🔑 Coreflux Copilot の統合

このサーバーには、Coreflux Copilot API による強力な AI アシスタンス機能が含まれています。

セットアップ

1. Coreflux Copilot ダッシュボードから API キーを取得します
2. キーを設定します：

   # Option 1: Environment file
   echo "DO_AGENT_API_KEY=your_api_key_here" >> .env
   
   # Option 2: Environment variable
   export DO_AGENT_API_KEY=your_api_key_here
   

機能

• LOT コード生成 - 自然言語から Language-of-Things コードを生成します
• 自動化支援 - Coreflux の自動化タスクを支援します
• ベストプラクティス - 最適な実装方法について案内します
• トラブルシューティング - デバッグと最適化を支援します

使用例

Claude に Coreflux の自動化について尋ねます。

Generate LOT code for a temperature monitoring system that triggers an alert when the temperature exceeds 75°F

Help me create a rule that processes sensor data and stores it in a database

🚀 高度な機能

非同期メッセージ処理

このサーバーには、次の機能を備えた堅牢な非同期メッセージプロセッサーが含まれています。

• ブロッキングの防止 - メインスレッドをブロックせずにメッセージを処理します
• レート制限 - システムの過負荷を防ぐための制限を設定できます
• キュー管理 - バックプレッシャーに対応したインテリジェントなキュー処理を行います
• 統計情報 - 処理状況のメトリクスをリアルタイムで監視できます

拡張ロギングシステム

エンタープライズ向け機能を備えた包括的なロギング機能です。

• 構造化ロギング - 解析しやすい JSON 形式のログを出力します
• ログローテーション - ディスク容量を管理するため、ログファイルを自動的にローテーションします
• セキュリティフィルタリング - 機密情報を自動的にサニタイズします
• 複数の出力先 - コンソール、ファイル、syslog に対応しています

設定の検証

次の項目をチェックする、堅牢な検証システムです。

• 環境変数 - 必須の設定がすべて有効か検証します
• ファイル権限 - 証明書ファイルにアクセスできることを確認します
• ネットワーク接続 - MQTT ブローカーへの接続をテストします
• API の可用性 - Copilot API にアクセスできることを検証します

🛡️ セキュリティとコンプライアンス

セキュリティ機能

• 入力のサニタイズ - すべての入力を検証し、サニタイズします
• TLS 暗号化 - MQTT 接続で TLS を全面的にサポートします
• シークレット管理 - 認証情報を安全に取り扱います
• 監査ログ - セキュリティイベントを包括的に記録します
• root 以外での実行 - 最小限の権限で実行します

コンプライアンスへの対応

このサーバーは、さまざまなコンプライアンス要件に対応しています。

• SOC 2 - セキュリティ制御と監視
• GDPR - データ保護とプライバシー
• HIPAA - 医療データの保護（適切に設定されている場合）

セキュリティの詳細については、SECRET_MANAGEMENT.md を参照してください。

📊 監視とヘルスチェック

ヘルスチェックツール

comprehensive_health_check ツールで包括的なヘルス監視を行えます。

# Manual health check
python server.py --health-check

# Or ask Claude:
# "Please run a comprehensive health check on the Coreflux MCP server"

監視メトリクス

サーバーは詳細なメトリクスを提供します。

• 接続状態 - MQTT ブローカーへの接続状況
• メッセージ処理 - キューサイズと処理速度
• システムリソース - メモリと CPU の使用状況
• エラー率 - 失敗した操作とエラーの統計情報
• API の状態 - Copilot API の可用性と応答時間

アラート

次の項目についてアラートを設定できます。

• 接続の失敗
• 高いエラー率
• リソースの枯渇
• セキュリティイベント

🤝 コントリビューション

コントリビューションを歓迎します。コントリビューションガイドラインをご確認ください。

開発プロセス

1. リポジトリを フォーク します
2. フィーチャーブランチを 作成 します：git checkout -b feature/amazing-feature
3. 開発用の依存関係を インストール します：pip install -r requirements-dev.txt
4. pre-commit フックを セットアップ します：pre-commit install
5. テストを追加して変更を 行います
6. 品質チェックを 実行 します：make quality-check
7. 変更を コミット します：git commit -am 'Add amazing feature'
8. ブランチに プッシュ します：git push origin feature/amazing-feature
9. プルリクエストを 作成 します

コード規約

• Python 3.11 以降 との互換性
• すべての関数に 型ヒント を記述
• 包括的なテスト を実施し、カバレッジを 90% 超にする
• bandit による セキュリティスキャン
• black と isort による コードフォーマット
• すべての公開 API に ドキュメント を用意

📄 ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については LICENSE ファイルを参照してください。

🆘 サポートとトラブルシューティング

よくある問題

接続が拒否されました

Error: MQTT connection failed

• ブローカーのホスト名とポートを確認してください
• ネットワーク接続を確認してください
• TLS の設定を確認してください

認証に失敗しました

Error: Authentication failed

• ユーザー名とパスワードを確認してください
• API キーの有効性を確認してください
• ブローカーのアクセス許可を確認してください

TLS ハンドシェイクに失敗しました

Error: TLS handshake failed

• 証明書のパスを確認してください
• 証明書の有効性を確認してください
• TLS バージョンの互換性を確認してください

デバッグモード

トラブルシューティングのために詳細なログ記録を有効にします。

export LOG_LEVEL=DEBUG
python server.py

サポート

• GitHub Issues：バグを報告し、機能をリクエストする
• Discussions：コミュニティのサポートと質問
• ドキュメント：完全なドキュメント
• セキュリティの問題：[email protected] に報告してください

🗺️ ロードマップ

現在のステータス：v1.0.0 ✅

• ✅ MQTT のコア機能
• ✅ Copilot API 統合
• ✅ エンタープライズ向けセキュリティ機能
• ✅ 包括的なテスト
• ✅ 本番環境へのデプロイをサポート

今後の機能

• v1.1.0 - モニタリングとメトリクスの強化
• v1.2.0 - Coreflux API エンドポイントの追加
• v1.3.0 - リアルタイムデータ向け WebSocket サポート
• v2.0.0 - 複数ブローカーのサポートとフェデレーション

---

📋 クイックリファレンス

基本コマンド

# Setup and configuration
python setup_assistant.py    # Interactive setup
make validate                 # Validate configuration

# Development
make dev-setup               # Complete dev environment
make test                    # Run all tests
make quality-check           # Run all quality checks

# Deployment
docker-compose up -d         # Docker deployment
make docker-build           # Build Docker image

# Monitoring
make health-check           # System health check
docker-compose logs -f      # View logs

主要ファイル

• server.py - メインの MCP サーバー
• .env - 設定ファイル
• requirements.txt - Python の依存関係
• docker-compose.yml - Docker デプロイ
• Makefile - 開発コマンド

---

Coreflux Community が ❤️ を込めて開発

• remove_action: アクションイベント／関数を削除します
• run_action: アクションイベント／関数を実行します
• remove_all_models: すべてのモデルを削除します
• remove_all_actions: すべてのアクションを削除します
• remove_all_routes: すべてのルートを削除します
• list_discovered_actions: 検出されたすべての Coreflux アクションを一覧表示します
• request_lot_code: 自然言語のプロンプトに基づいて、Coreflux Copilot API を使用して LOT コードを生成します

デバッグとトラブルシューティング

MQTT ブローカーが利用できない場合でも MCP サーバーが起動するようになったため、MCP ツールを使って接続のトラブルシューティングや設定を行えます。

接続ステータスと復旧

• MQTT ブローカーに接続できない場合でも、サーバーは正常に起動します
• get_connection_status ツールを使用して、接続の状態を確認し、トラブルシューティングのガイダンスを取得します
• setup_mqtt_connection ツールを使用して、再起動せずに新しいブローカー接続を設定します
• check_broker_health または reconnect_mqtt ツールを使用して、接続をテストし、再試行します

接続管理に使用できるツール

• get_connection_status：トラブルシューティングのガイダンスとともに、詳細な接続ステータスを取得します
• setup_mqtt_connection：新しい MQTT ブローカー接続を動的に設定します
• mqtt_connect：カスタムパラメーターを指定して、特定の MQTT ブローカーに接続します
• check_broker_health：ブローカーへの接続をテストし、再接続を試みます
• reconnect_mqtt：設定済みのブローカーへの再接続を強制します

従来のトラブルシューティング手順

問題が発生した場合は、次の手順を実行してください。

1. Claude の設定で MQTT ブローカーの認証情報を確認します
2. ブローカーにアクセスできることを確認します
3. セットアップアシスタントを実行して、設定を確認または更新します。

   python setup_assistant.py
   

4. Claude Desktop のログを確認します。

   # Check Claude's logs for errors (macOS/Linux)
   tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
   # Windows PowerShell
   Get-Content -Path "$env:USERPROFILE\AppData\Roaming\Claude\Logs\mcp*.log" -Tail 20 -Wait
   

5. デバッグログを有効にしてサーバーを実行します。

   # Direct execution with debug logging
   python server.py --mqtt-host localhost --mqtt-port 1883 --log-level DEBUG
   

参考資料とドキュメント

• DEPLOYMENT.md - 本番環境へのデプロイガイド
• SECURITY.md - セキュリティガイドラインとベストプラクティス
• MCP Documentation - MCP 公式ドキュメント
• Coreflux Platform - Coreflux オートメーションプラットフォーム

コントリビューション

コントリビューションを歓迎します。コントリビューションガイドラインをお読みのうえ、development ブランチにプルリクエストを送信してください。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

サポート

• 📖 ドキュメント：README、DEPLOYMENT.md、SECURITY.md ファイルを確認してください
• 🐛 問題：バグや機能リクエストを GitHub で報告してください
• 💬 コミュニティ：Coreflux コミュニティに参加して、ディスカッションに加わってください