Fledge MCP Server

Fledge MCP サーバー

これは、Fledge の機能を Cursor AI に接続し、自然言語のコマンドを介して AI が Fledge インスタンスとやり取りできるようにする Model Context Protocol（MCP）サーバーです。

前提条件

• Fledge がローカルにインストールされているか、API 経由でアクセスできること（デフォルト：https://localhost:8081）
• Cursor AI がインストールされていること
• Python 3.8 以降

インストール

1. このリポジトリをクローンします：

git clone https://github.com/Krupalp525/fledge-mcp.git
cd fledge-mcp

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

pip install -r requirements.txt

サーバーの実行

1. Fledge が実行中であることを確認します：

fledge start

2. MCP サーバーを起動します：

python mcp_server.py

API キー認証を使用して安全に運用する場合：

python secure_mcp_server.py

3. ヘルスエンドポイントにアクセスして、正常に動作していることを確認します：

curl http://localhost:8082/health

応答として「Fledge MCP Server is running」が返されます。

Cursor への接続

1. Cursor で、Settings > MCP Servers に移動します

2. 新しいサーバーを追加します：

   • URL：http://localhost:8082/tools
   • Tools ファイル：付属の tools.json をアップロードするか、ローカルパスを指定します

3. セキュアサーバーでは、セキュアサーバーの起動時に生成される api_key.txt ファイル内の値を使って、「X-API-Key」ヘッダーを設定します。

4. テストします：Cursor の Composer（Ctrl+I）を開き、「Check if Fledge API is reachable」と入力すると、AI が validate_api_connection ツールを呼び出します。

利用可能なツール

データへのアクセスと管理

1. get_sensor_data：時間範囲と件数を任意に指定して、Fledge からセンサーデータを取得します
2. list_sensors：Fledge で利用可能なすべてのセンサーを一覧表示します
3. ingest_test_data：件数を任意に指定して、テストデータを Fledge に取り込みます

サービス制御

4. get_service_status：すべての Fledge サービスのステータスを取得します
5. start_stop_service：種類を指定して Fledge サービスを開始または停止します
6. update_config：Fledge の設定パラメーターを更新します

フロントエンドコードの生成

7. generate_ui_component：Fledge のデータ可視化用の React コンポーネントを生成します
8. fetch_sample_frontend：さまざまなフレームワークのフロントエンドテンプレートのサンプルを取得します
9. suggest_ui_improvements：UI コードを改善するための AI による提案を取得します

リアルタイムデータストリーミング

10. subscribe_to_sensor：センサーデータの更新を購読するように設定します
11. get_latest_reading：特定のセンサーから最新の測定値を取得します

デバッグと検証

12. validate_api_connection：Fledge API に接続できるか確認します
13. simulate_frontend_request：さまざまなメソッドとペイロードで API リクエストをテストします

ドキュメントとスキーマ

14. get_api_schema：利用可能な Fledge API エンドポイントの情報を取得します
15. list_plugins：利用可能な Fledge プラグインを一覧表示します

高度な AI 支援機能

16. generate_mock_data：テスト用に現実的なモックセンサーデータを生成します

API のテスト

付属のテストスクリプトを使ってサーバーをテストできます：

# For standard server
python test_mcp.py

# For secure server with API key
python test_secure_mcp.py

セキュリティオプション

セキュアサーバー（secure_mcp_server.py）では、API キー認証が追加されます：

1. 初回実行時に、api_key.txt に保存される API キーが生成されます
2. すべてのリクエストに、このキーを含む X-API-Key ヘッダーが必要です
3. ヘルスチェックエンドポイントは、認証なしで引き続きアクセスできます

API リクエストの例

# Validate API connection
curl -X POST -H "Content-Type: application/json" -d '{"name": "validate_api_connection"}' http://localhost:8082/tools

# Generate mock data
curl -X POST -H "Content-Type: application/json" -d '{"name": "generate_mock_data", "parameters": {"sensor_id": "temp1", "count": 5}}' http://localhost:8082/tools

# Generate React chart component
curl -X POST -H "Content-Type: application/json" -d '{"name": "generate_ui_component", "parameters": {"component_type": "chart", "sensor_id": "temp1"}}' http://localhost:8082/tools

# For secure server, add API key header
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" -d '{"name": "list_sensors"}' http://localhost:8082/tools

サーバーの拡張

ツールを追加するには：

1. tools.json にツール定義を追加します
2. mcp_server.py と secure_mcp_server.py にツールハンドラーを実装します

本番環境での考慮事項

本番環境にデプロイする場合：

• HTTPS を使用します
• Nginx などのリバースプロキシの背後にデプロイします
• より堅牢な認証（JWT、OAuth）を実装します
• レート制限を追加します
• 購読用の永続データストレージを設定します

Smithery.ai へのデプロイ

Fledge MCP Server は、スケーラビリティと可用性を高めるために Smithery.ai にデプロイできます。デプロイするには、次の手順に従ってください。

1. 前提条件

   • ローカルマシンに Docker がインストールされていること
   • Smithery.ai アカウント
   • Smithery CLI ツールがインストールされていること

2. ビルドとデプロイ

   # Build the Docker image
   docker build -t fledge-mcp .
   
   # Deploy to Smithery.ai
   smithery deploy
   

3. 設定 smithery.json ファイルには、デプロイの設定が含まれています。

   • ポート 8082 での WebSocket トランスポート
   • 設定可能な Fledge API URL
   • ツールの定義とパラメーター
   • タイムアウト設定

4. 環境変数 Smithery.ai ダッシュボードで、次の環境変数を設定してください。

   • FLEDGE_API_URL：Fledge API エンドポイント
   • API_KEY：安全な API キー（セキュアモードを使用する場合）

5. 検証 デプロイ後、サーバーが稼働していることを確認してください。

   smithery status fledge-mcp
   

6. 監視 Smithery.ai ダッシュボードでデプロイを監視します。

   • リアルタイムログ
   • パフォーマンス指標
   • エラー追跡
   • リソース使用量

7. 更新 デプロイを更新するには、次の手順に従ってください。

   # Build new image
   docker build -t fledge-mcp .
   
   # Deploy updates
   smithery deploy --update
   

JSON-RPC プロトコルのサポート

サーバーは WebSocket 上の JSON-RPC 2.0 を使用して、Model Context Protocol（MCP）を実装しています。次のメソッドをサポートしています。

1. initialize

   {
       "jsonrpc": "2.0",
       "method": "initialize",
       "params": {},
       "id": "1"
   }
   

   応答：

   {
       "jsonrpc": "2.0",
       "result": {
           "serverInfo": {
               "name": "fledge-mcp",
               "version": "1.0.0",
               "description": "Fledge Model Context Protocol (MCP) Server",
               "vendor": "Fledge",
               "capabilities": {
                   "tools": true,
                   "streaming": true,
                   "authentication": "api_key"
               }
           },
           "configSchema": {
               "type": "object",
               "properties": {
                   "fledge_api_url": {
                       "type": "string",
                       "description": "Fledge API URL",
                       "default": "http://localhost:8081/fledge"
                   }
               }
           }
       },
       "id": "1"
   }
   

2. tools/list

   {
       "jsonrpc": "2.0",
       "method": "tools/list",
       "params": {},
       "id": "2"
   }
   

   応答：利用可能なツールとそのパラメーターの一覧を返します。

3. tools/call

   {
       "jsonrpc": "2.0",
       "method": "tools/call",
       "params": {
           "name": "get_sensor_data",
           "parameters": {
               "sensor_id": "temp1",
               "limit": 10
           }
       },
       "id": "3"
   }
   

エラーコード

サーバーは標準的な JSON-RPC 2.0 エラーコードに準拠しています。

• -32700：解析エラー
• -32600：無効なリクエスト
• -32601：メソッドが見つかりません
• -32602：パラメーターが無効です
• -32000：サーバーエラー