Servidor MCP para Smart Cities

Smart Cities 向け MCP サーバー

この MCP（Model Context Protocol）サーバーを使用すると、AI がスマートシティの IoT デバイスデータ（街灯、水道メーター、ガスメーターなど）とやり取りできます。

注意：

• この MCP サーバーは現在、Stdio（標準入力／標準出力）経由の接続のみをサポートしています。
• Cursor および VSCode の GitHub Copilot を MCP クライアントとして使用し、テストと検証を行いました。

アプリケーションのログ

MCP サーバーのログは、プロジェクトの logs フォルダー内のファイル（デフォルトでは logs/server.log およびローテーションされたファイル）に保存されます。

理由：

• MCP クライアントと MCP サーバー間の通信は Stdio（標準入力／標準出力）経由で行われるため、コンソールにログを出力すると、クライアントとサーバー間のメッセージ交換に干渉する可能性があります。
• そのため、MCP の通信が正常に機能するよう、すべてのログをファイルに出力します。

ログを確認するには、logs フォルダー内のファイルを任意のテキストエディターで開くか、次のようなコマンドを使用してください。

cat logs/server.log

ファイルが過剰に大きくならないよう、自動的にローテーションされます。

📚 プロジェクトのドキュメント

このプロジェクトには、さまざまなニーズや対象者に合わせた、体系的なドキュメントが用意されています。各ファイルは、生産性を最大限に高め、プロジェクトへの理解を促進するため、それぞれ特定の目的に沿って作成されています。

🎯 ドキュメントの概要

ファイル	対象者	目的	読むタイミング
.cursorrules	Cursor AI	自動的なコンテキスト提供	自動
.github/copilot-instructions.md	GitHub Copilot	VSCode 向けの指示	自動
.vscode/mcp.json	VSCode/Copilot	MCP の設定	手動／自動
QUICKSTART.md	すべてのユーザー	クイックセットアップ	初回アクセス時
docs/DEVELOPMENT.md	開発者	規約とアーキテクチャ	開発中
docs/AI_CONTEXT.md	AI/Cursor	最適化されたやり取り	自動参照
README.md	一般	完全なドキュメント	リファレンス

---

🤖 .cursorrules - AI 向けの自動コンテキスト

目的： 手動で説明することなくプロジェクトのコンテキストを理解できるよう、Cursor が自動的に読み込むファイルです。

使用するタイミング：

• ✅ 常時 - Cursor はプロジェクトを開くと自動的に読み込みます
• ✅ プロジェクトについて初めて質問するとき
• ✅ Cursor が固有の規約を理解する必要があるとき

使用方法：

• Cursor： 自動的に読み込み、セッション全体を通じてコンテキストを維持します
• 開発者： 規約を理解する必要があるときに手動で参照します
• 新しい AI： コンテキストを把握するために最初に参照するファイルです

内容：

• プロジェクトの構成とテクノロジー
• コード規約（ID、タイムスタンプ、ログ）
• 重要なコマンド
• MCP 固有の考慮事項

使用例：

Você: "Crie uma nova ferramenta MCP para monitorar tráfego"
Cursor: (lê .cursorrules) "Entendo que preciso seguir o padrão Zod, usar logs em arquivo, e registrar no server.ts..."

---

🆕 .github/copilot-instructions.md - GitHub Copilot 向けの指示

目的： VSCode の GitHub Copilot 向けに、プロジェクトの詳細なコンテキストを提供する専用の指示ファイルです。

使用するタイミング：

• 🎯 Copilot を使用する VSCode - GitHub Copilot が自動的に読み込みます
• 🔧 VSCode での開発 - コンテキストに沿った提案に使用します
• 📋 コード規約 - プロジェクトの規約に自動的に従います

使用方法：

• GitHub Copilot： インテリジェントな提案のためにコンテキストを自動的に取得します
• VSCode： 開発環境とネイティブに統合されます
• 開発者： 固有のパターンを理解するために参照します

内容：

• Smart Cities プロジェクトの完全なコンテキスト
• 開発固有の規約
• 実装済み MCP ツールの構成
• 新機能を実装するためのパターン
• 検証とエラー処理に関する指示

使用例：

Você: Começa a digitar uma nova função MCP no VSCode
Copilot: (lê .github/copilot-instructions.md) Sugere automaticamente padrão Zod, timestamps UNIX, logs em arquivo

---

🔧 .vscode/mcp.json - VSCode 用 MCP 設定

目的： MCP サーバーへの接続に使用する VSCode 専用の設定です。GitHub Copilot 向けに最適化されています。

使用する場面：

• 🖥️ VSCode - MCP を自動設定する場合
• 🤝 GitHub Copilot - ツールと直接連携する場合
• ⚙️ 開発 - 開発環境を自動設定する場合

使用方法：

• VSCode： MCP の設定を自動的に読み込みます
• GitHub Copilot： サーバーのツールに直接アクセスします
• 開発者： 手動設定なしで簡単にセットアップできます

内容：

• stdio 用の MCP サーバー設定
• 安全な環境変数（inputs を使用）
• コンパイル済みサーバーへのパス
• MongoDB 専用の設定

使用例：

1. Abrir projeto no VSCode
2. VSCode detecta .vscode/mcp.json automaticamente
3. Solicita credenciais do MongoDB (primeira vez)
4. Copilot tem acesso às 13 ferramentas MCP

---

⚡ QUICKSTART.md - クイックスタートガイド

目的： 詳細なドキュメントを読まずに、5 分以内でプロジェクトを動作させます。

使用する場面：

• 🚀 プロジェクトに初めてアクセスするとき
• 🔧 問題が発生したとき - 何かが動作しない場合
• 👥 デモ - 動作を見せるためにすばやくセットアップするとき
• 🧪 テスト - 変更後にすばやく検証するとき
• 📅 後日 - 実行方法を忘れたとき（6 か月後など）

使用方法：

• 新しい開発者： 最初に読むファイル
• 自分用： コマンドのクイックリファレンス
• デモ： クライアントや同僚に見せるためのセットアップ
• CI/CD： 自動化スクリプトの基礎

内容：

• 完全なセットアップまでの 3 つの手順
• テストおよび検証用コマンド
• 基本的なトラブルシューティング
• すぐに使えるプロンプトの例
• 参照用の ID とタイムスタンプ
• 新機能： VSCode/Copilot の設定

使用例：

Cenário: Novo membro da equipe
1. Lê QUICKSTART.md (3 min)
2. Executa 3 comandos
3. Configura VSCode/Copilot
4. Testa com prompts prontos
5. Projeto funcionando ✅

---

🏗️ docs/DEVELOPMENT.md - 開発ガイド

目的： 開発およびメンテナンスに役立つ、コーディング規約、アーキテクチャ、ベストプラクティスを説明します。

使用する場面：

• 🔨 積極的な開発 - コードの作成や変更時
• 🏗️ アーキテクチャ - 構造やデザインパターンを理解するとき
• ➕ 新機能 - MCP ツールを追加するとき
• 🐛 デバッグ - 処理の流れやログを理解するとき
• 📖 コードレビュー - 規約への準拠を確認するとき

使用方法：

• 開発者： コーディング中に参照
• コードレビュー： 規約への準拠を確認
• リファクタリング： 一貫性を保つためのガイド
• オンボーディング： 技術的な内容を深く理解

内容：

• プロジェクトの詳細なアーキテクチャ
• Zod を使った検証規約
• MCP の応答構造
• ページネーション規約
• 新しいツールの追加方法
• コード例
• 新機能： VSCode と Copilot の設定

使用例：

Tarefa: Adicionar ferramenta de monitoramento de temperatura
1. Consulta DEVELOPMENT.md para padrões
2. Segue estrutura de validação Zod
3. Implementa paginação conforme exemplo
4. Registra no server.ts seguindo convenção
5. Testa com VSCode/Copilot

---

🧠 docs/AI_CONTEXT.md - AI との対話に役立つコンテキスト

目的： 具体的な例や既知の制限事項を用いて、人間、AI、IoT データ間のやり取りを最適化します。

使用する場面：

• 💬 複雑なプロンプト - 高度なデータクエリ
• 📊 分析 - データからインサイトを得たいとき
• 🗺️ 地理的なクエリ - 地域別のデータを調べるとき
• ⏰ 時間データ - 履歴を分析するとき
• 🤔 機能に関する疑問 - 可能な操作を確認するとき

使用方法：

• Cursor： より効果的なプロンプトのために自動的に参照
• GitHub Copilot： コード提案のためのコンテキスト
• ユーザー： 質問の仕方の例
• その他の AI： データ構造に関するコンテキスト
• 開発： よくあるユースケースを理解

内容：

• 効果的な自然言語プロンプトの例
• データの詳細な構造
• 制限事項とパフォーマンスに関する考慮事項
• よくある使用シナリオ
• 想定される応答形式
• より効果的にやり取りするためのヒント
• 新機能： VSCode/Copilot 向けの具体例

使用例：

Você: "Quero analisar eficiência energética"
Cursor/Copilot: (consulta AI_CONTEXT.md) "Baseado nos exemplos, sugiro consultar consumo por período específico..."
Resultado: Prompt mais eficaz e dados mais relevantes

---

📖 README.md - 完全なドキュメント

目的： プロジェクトの完全かつ公式なドキュメントであり、すべての情報を確認するための主要なリファレンスです。

使用する場面：

• 📚 完全なリファレンス - すべてのツールに関する詳細情報
• 🔍 具体的な検索 - パラメーターと応答の詳細
• 📋 公式ドキュメント - 外部リンクや参照先の確認
• 🎓 深く学ぶ - プロジェクトを完全に理解する
• 📝 第三者向けドキュメント - 公式資料

使用方法：

• 公式リファレンス： 外部ドキュメントへのリンク
• 詳細な確認： QUICKSTART では不十分な場合
• 統合： 他のシステム向けの情報
• トレーニング： チーム向けの完全な資料

内容：

• すべての MCP ツールの詳細
• 使用例の全体
• 詳細な設定
• 新規： VSCode/Copilot との統合
• データベースの構造
• 制限事項と考慮事項

---

🎯 推奨される使用フロー

初回アクセスの場合：

1. QUICKSTART.md → クイックセットアップとテスト
2. VSCode を設定 → .vscode/mcp.json による自動設定
3. README.md → 全体を理解する
4. docs/AI_CONTEXT.md → 使用例を確認する

開発の場合：

1. .cursorrules → 自動コンテキスト（Cursor）
2. .github/copilot-instructions.md → 自動コンテキスト（VSCode/Copilot）
3. docs/DEVELOPMENT.md → 規約とアーキテクチャ
4. README.md → API リファレンス

日常的な使用の場合：

1. VSCode/Copilot → MCP との自動統合
2. docs/AI_CONTEXT.md → 効果的なプロンプト
3. QUICKSTART.md → クイックコマンド
4. README.md → 個別の詳細

問題が発生した場合：

1. QUICKSTART.md → 基本的なトラブルシューティング
2. docs/DEVELOPMENT.md → 高度なデバッグ
3. ログ → logs/server.log
4. VSCode → MCP の設定を確認する

💡 生産性向上のヒント

• Cursor ユーザー： .cursorrules と AI_CONTEXT.md を組み合わせて、自動的にコンテキストを提供します
• VSCode ユーザー： .github/copilot-instructions.md と .vscode/mcp.json により、完全な統合を実現します
• 開発： DEVELOPMENT.md を参照することで、規約を崩さずに開発できます
• デモ： QUICKSTART.md と自動設定を組み合わせれば、数分でセットアップできます
• メンテナンス： 各ファイルが特定の役割を担っているため、更新が容易です

設定

オプション 1：GitHub Copilot を使用する VSCode（推奨）

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

npm install

2. VSCode でプロジェクトを開きます：

code .

3. VSCode が .vscode/mcp.json ファイルを自動的に検出し、MongoDB の設定を求めます

4. データベースを起動します：

cd db-init && docker-compose up --build -d

5. サーバーをコンパイルして起動します：

npm run build
npm start

オプション 2：Cursor（従来の方法）

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

npm install

2. 環境変数を設定します（任意）：

MONGO_URI=mongodb://cursor-mcp-client:cursor-mcp-password@localhost:27017/smart_city_iot

3. サーバーを起動します：

npm start

利用可能なツール

1. 照明デバイスの一覧表示

listLightingDevices({
    region?: string,    // Filtro opcional por região (nome ou busca geoespacial)
    status?: string,    // Filtro opcional por status
    geoJson?: boolean  // Se true, retorna FeatureCollection GeoJSON
})

• 公共照明デバイスの一覧を返します。
• region が指定されている場合、地理的な近接性（座標と地域のポリゴンを使用）で絞り込みます。
• geoJson=true の場合、GeoJSON（FeatureCollection）形式で返します。

プロンプトの例：

• 「南東部地域にある照明デバイスをすべて一覧表示してください」
• 「中西部付近の照明デバイスを GeoJSON で返してください」
• 「南部ではどの照明デバイスが稼働していますか？」
• 「北東部の照明デバイスの GeoJSON をください」

2. 照明のテレメトリーを確認

getLightingTelemetry({
    deviceId: string,   // ID do dispositivo
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

指定した期間における特定デバイスのテレメトリーデータを返します。以下が含まれます：

• 温度
• 状態（オン／オフ）
• 電流
• 電圧
• 累積エネルギー
• 力率
• 照明レベル
• 電力消費量
• 稼働時間

3. エネルギー消費量を分析

analyzeEnergyConsumption({
    deviceId: string,   // ID do dispositivo
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

エネルギー消費量の詳細な分析結果を返します：

• 総エネルギー消費量
• 平均電力
• 最大電力
• 最小電力

4. 水漏れの検出

detectWaterLeaks({
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

指定期間内に検出された水漏れの記録をすべて返します。以下を含みます。

• デバイス ID
• 場所
• 流量
• 圧力
• 温度
• 消費量

5. ガス消費量の分析

analyzeGasConsumption({
    region: string,     // Nome da região
    startTime: number,  // Timestamp inicial (UNIX)
    endTime: number     // Timestamp final (UNIX)
})

地域ごとのガス消費量の詳細な分析を返します。

• 総消費量
• 平均流量
• 検出された水漏れの数

🚀 高度なツール（新機能）

6. 地域別比較統計

getRegionalStatistics({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    includeComparison?: boolean  // Se true, inclui comparações entre regiões
})

すべての地域を比較した詳細な統計を返します。

• 地域ごとの電力、水、ガスの消費量
• パフォーマンスと効率の指標
• デバイス数と水漏れ件数
• 稼働時間と信頼性の分析

7. デバイスの健全性レポート

getDeviceHealthReport({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    region?: string,        // Filtro por região
    healthThreshold?: number // Limiar de saúde (0-100)
})

デバイスの「健全性」に関する詳細な分析を返します。

• 算出された健全性スコア（0～100）
• デバイスの種類別の指標
• メンテナンスが必要なデバイス
• 推定耐用年数

8. 都市の総合ダッシュボード

getCityDashboard({
    timeRange?: 'hour' | 'day' | 'week' | 'month',  // Período de análise
    includeAlerts?: boolean  // Se true, inclui alertas inteligentes
})

都市全体の概要を返します。

• すべてのシステムの全般的な統計
• 消費量と効率の概要
• 重大なアラート、警告、情報
• スマートシティの主要 KPI

9. メンテナンスの予測

predictMaintenance({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    predictionDays?: number,    // Dias para predição (1-90)
    riskThreshold?: number      // Limiar de risco (0-100)
})

機械学習に基づく予測を返します。

• 故障リスクのあるデバイス
• メンテナンスリスクスコア
• 故障までの推定日数
• 緊急メンテナンスと予防メンテナンス

10. 異常の検出

getAnomalyDetection({
    deviceType?: 'lighting' | 'water' | 'gas' | 'all',  // Tipo de dispositivo
    sensitivity?: 'low' | 'medium' | 'high',            // Sensibilidade
    timeRange?: 'hour' | 'day' | 'week'                 // Período de análise
})

インテリジェントな異常検出の結果を返します。

• 統計的な偏差による異常
• 異常な消費パターン
• 不審な動作
• 重大度別の分類

11. エネルギー効率の総合レポート

getEnergyEfficiencyReport({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    includeRecommendations?: boolean,  // Se true, inclui recomendações
    region?: string         // Filtro por região
})

エネルギー効率の包括的な分析を返します。

• デバイスごとの効率スコア
• 地域別の比較分析
• 最も優れたデバイスと最も劣るデバイス
• 最適化の推奨事項
• 節約可能量の見積もり

12. 水質レポート

getWaterQualityReport({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    region?: string,        // Filtro por região
    includeAlerts?: boolean // Se true, inclui alertas de segurança
})

水質の詳細な分析を返します。

• デバイスごとの水質スコア
• 圧力、温度、流量の指標
• 安定性と信頼性
• 安全性と品質に関するアラート
• 分類：優良／良好／不良

13. デバイス間の相関分析

getCrossDeviceAnalysis({
    startTime: number,      // Timestamp inicial (UNIX)
    endTime: number,        // Timestamp final (UNIX)
    region?: string,        // Filtro por região
    analysisType?: 'consumption' | 'efficiency' | 'maintenance' | 'environmental'
})

異なる種類のデバイス間の相関関係を返します。

• 相関する消費パターン
• 水漏れがシステムに与える影響
• システム間の相互効率
• 分析結果と戦略的な推奨事項
• 時間的および地理的な相関関係

使用例

例 1：エネルギー効率の分析

// Consultar consumo de energia de um poste
const consumo = await analyzeEnergyConsumption({
    deviceId: "LIGHT-000001",
    startTime: 1609459200,  // 01/01/2021
    endTime: 1640995200     // 01/01/2022
});

例 2：水漏れの監視

// Detectar vazamentos de água
const vazamentos = await detectWaterLeaks({
    startTime: 1609459200,  // 01/01/2021
    endTime: 1640995200     // 01/01/2022
});

例 3：地域別分析

// Analisar consumo de gás por região
const consumoGas = await analyzeGasConsumption({
    region: "São Paulo",
    startTime: 1609459200,  // 01/01/2021
    endTime: 1640995200     // 01/01/2022
});

例 4：都市のダッシュボード

// No Cursor, você pode solicitar um dashboard completo:
"Gere um dashboard da cidade com alertas para o último dia"

// O Cursor irá gerar e executar o código:
const dashboard = await getCityDashboard({
    timeRange: "day",
    includeAlerts: true
});

例 5：メンテナンスの予測

// No Cursor, você pode solicitar predições:
"Quais dispositivos de água precisam de manutenção urgente?"

// O Cursor irá gerar e executar o código:
const predicao = await predictMaintenance({
    deviceType: "water",
    riskThreshold: 80
});

例 6：異常の検出

// No Cursor, você pode detectar comportamentos anômalos:
"Detecte anomalias na iluminação com alta sensibilidade na última semana"

// O Cursor irá gerar e executar o código:
const anomalias = await getAnomalyDetection({
    deviceType: "lighting",
    sensitivity: "high",
    timeRange: "week"
});

例 7：エネルギー効率レポート

// No Cursor, você pode gerar relatórios completos:
"Gere um relatório de eficiência energética do último mês com recomendações"

// O Cursor irá gerar e executar o código:
const eficiencia = await getEnergyEfficiencyReport({
    startTime: Date.now()/1000 - (30 * 24 * 60 * 60),
    endTime: Date.now()/1000,
    includeRecommendations: true
});

例 8：相関分析

// No Cursor, você pode analisar correlações:
"Analise a correlação entre consumo de energia e água na região Sudeste"

// O Cursor irá gerar e executar o código:
const correlacao = await getCrossDeviceAnalysis({
    startTime: Date.now()/1000 - (7 * 24 * 60 * 60),
    endTime: Date.now()/1000,
    region: "Sudeste",
    analysisType: "consumption"
});

データベース構成

サーバーは、以下のコレクションを持つ MongoDB データベース smart_city_iot に接続します。

デバイス

• lighting_devices：照明デバイス 10,000 台
• water_devices：水道メーター 50,000 台
• gas_devices：ガスメーター 50,000 台

テレメトリー

• lighting_telemetry：照明データ
• water_telemetry：水道データ
• gas_telemetry：ガスデータ

最適化されたインデックス

データベースには、頻繁に実行されるクエリ向けに最適化されたインデックスがあります。

• lighting_telemetry：{ deviceId: 1, timestamp: 1 }
• water_telemetry：{ deviceId: 1, timestamp: 1 }
• gas_telemetry：{ deviceId: 1, timestamp: 1 }

セキュリティ

• 専用ユーザーによる MongoDB 認証
• 読み取り操作のみ許可
• Zod による入力検証
• 堅牢なエラー処理

制限事項

• タイムスタンプは UNIX 形式（1970 年からの秒数）で指定する必要があります
• クエリで指定できる期間には制限があります
• 期間が長い場合、一部の分析は計算負荷が高くなることがあります

データベースに関する重要な注意事項

サーバーが動作するには、ローカルの MongoDB インスタンスにデータベース smart_city_iot が存在している必要があります。

データベースの初期化方法：

1. ターミナルを開き、db-init フォルダーに移動します：

   cd db-init
   

2. docker-compose を実行して、MongoDB を初期化し、サンプルデータを登録します：

   docker-compose up --build -d
   

   このコマンドでは、次の処理が行われます：

   • ローカルの MongoDB インスタンスを初期化します
   • データベースにサンプルデータを自動的に登録します
   • アクセス認証情報を設定します

代替方法：データベースへの手動登録

すでに MongoDB インスタンスを実行している場合は、次のスクリプトを使ってデータベースに手動でデータを登録できます：

node populate_mongodb.js

このスクリプトは、データベース smart_city_iot に次のコレクションを作成し、データを登録します：

• lighting_devices：街路照明デバイス。各デバイスには deviceId、latitude、longitude、status などのフィールドがあります。
• water_devices：水道メーター
• gas_devices：ガスメーター
• lighting_telemetry、water_telemetry、gas_telemetry：各種デバイスのシミュレーション済みテレメトリデータ

注意：

• スクリプトを実行する前に、MongoDB がローカルで実行されていることを確認してください。
• 作成されるデータは、テストおよび開発用のサンプルです。

IDE との統合

🆕 GitHub Copilot を使用した VSCode の設定

VSCode は、.vscode/mcp.json の設定を通じて MCP サーバーとネイティブに統合できます：

{
    "inputs": [
        {
            "type": "promptString",
            "id": "mongo-uri",
            "description": "MongoDB Connection URI",
            "default": "mongodb://cursor-mcp-client:cursor-mcp-password@localhost:27017/smart_city_iot?authSource=admin"
        }
    ],
    "servers": {
        "smart-city": {
            "type": "stdio",
            "command": "node",
            "args": [
                "~/Wesley/Github/mcp-server/dist/server.js"
            ],
            "env": {
                "MONGO_URI": "${input:mongo-uri}",
                "READ_ONLY": "false"
            }
        }
    }
}

VSCode 設定のメリット：

• ✅ セキュリティ：認証情報を対話形式で要求します（ハードコードされません）
• ✅ 自動化：VSCode が設定を自動的に検出して読み込みます
• ✅ Copilot：GitHub Copilot が MCP ツールに直接アクセスできます
• ✅ 安全な入力：環境変数は VSCode によって管理されます

Cursor の設定（従来の方法）

1. .cursor/mcp.json ファイルを次の設定内容で構成します：

{
    "mcpServers": {
        "smart-city": {
            "command": "node",
            "args": [
                "/CAMINHO/ABSOLUTO/PARA/dist/server.js"
            ],
            "env": {
                "MONGO_URI": "mongodb://cursor-mcp-client:cursor-mcp-password@localhost:27017/smart_city_iot?authSource=admin",
                "READ_ONLY": "false"
            }
        }
    }
}

重要：

• server.js ファイルへのパスは絶対パスにする必要があります（例：/home/usuario/projeto/dist/server.js）。
• TypeScript を使用する場合は、事前に npm run build を実行し、生成された dist/server.js ファイル（またはビルド出力の設定に応じたファイル）を使用してください。

VSCode/GitHub Copilot を使用した例

例 1：VSCode でのデバイス検索

// No VSCode com Copilot, você pode usar linguagem natural:
// Digite: "Liste dispositivos de iluminação no Sudeste"

// O Copilot sugere automaticamente:
const dispositivos = await listLightingDevices({
    region: "Sudeste",
    limit: 100
});
console.log(`Encontrados ${dispositivos.total} dispositivos`);

例 2：Copilot による自動分析

// Digite: "Analise energia do LIGHT-000001 último mês"

// Copilot gera código otimizado baseado nas instruções:
const endTime = Math.floor(Date.now() / 1000);
const startTime = endTime - (30 * 24 * 60 * 60); // 30 dias em segundos

const analise = await analyzeEnergyConsumption({
    deviceId: "LIGHT-000001",
    startTime,
    endTime
});

// Copilot também sugere tratamento de erros e formatação
if (analise.totalEnergy > 0) {
    console.log(`Consumo total: ${analise.totalEnergy.toFixed(2)} kWh`);
}

例 3：スマートダッシュボード

// Digite: "Crie dashboard cidade com alertas hoje"

// Copilot gera solução completa:
const dashboard = await getCityDashboard({
    timeRange: "day",
    includeAlerts: true
});

// Copilot sugere análise dos alertas
const alertasCriticos = dashboard.alerts.critical.length;
if (alertasCriticos > 0) {
    console.log(`⚠️ ${alertasCriticos} alertas críticos detectados`);
    dashboard.alerts.critical.forEach(alert => {
        console.log(`- ${alert.type}: ${alert.message}`);
    });
}

Cursor を使用した例（従来の方法）

例 1：デバイス検索

// No Cursor, você pode usar o prompt para consultar dispositivos:
"Liste todos os dispositivos de iluminação na região Sudeste"

// O Cursor irá gerar e executar o código:
const dispositivos = await listLightingDevices({
    region: "Sudeste"
});

例 2：データ分析

// No Cursor, você pode solicitar análises específicas:
"Analise o consumo de energia do dispositivo LIGHT-000001 no último mês"

// O Cursor irá gerar e executar o código:
const consumo = await analyzeEnergyConsumption({
    deviceId: "LIGHT-000001",
    startTime: Date.now() - (30 * 24 * 60 * 60 * 1000),
    endTime: Date.now()
});

例 3：漏水の監視

// No Cursor, você pode solicitar monitoramento:
"Verifique se há vazamentos de água nas últimas 24 horas"

// O Cursor irá gerar e executar o código:
const vazamentos = await detectWaterLeaks({
    startTime: Date.now() - (24 * 60 * 60 * 1000),
    endTime: Date.now()
});

MCP ツールでの結果のページネーション

この MCP サーバーの一部のツールは、大量のデータを返す場合があります。タイムアウトを防ぎ、パフォーマンスを向上させるため、次のツールにページネーションが実装されています：

• listLightingDevices
• getLightingTelemetry
• detectWaterLeaks

ページネーションの使用方法

これらのツールでは、次のオプションパラメーターを指定できます：

• limit（数値）：1 回のリクエストで返すレコードの最大数です。デフォルト値：100。
• offset（数値）：結果の返却を開始する前にスキップするレコード数です。デフォルト値：0。

呼び出し例

{
  "limit": 100,
  "offset": 200
}

ページネーションされたレスポンスの形式

これらのツールのレスポンスは、次の内容を含む JSON オブジェクトです：

• 要求されたデータ（例：devices、telemetry、leaks）
• total：クエリで取得可能なレコードの総数
• offset：クエリで使用されたオフセット
• limit：クエリで使用された上限
• hasNext：データの次のページがあるかどうかを示すブール値

レスポンス例

{
  "devices": [ ... ],
  "total": 60819,
  "offset": 200,
  "limit": 100,
  "hasNext": true
}

注： listLightingDevices で geoJson パラメーターを使用する場合、レスポンスは GeoJSON オブジェクトとなり、上記のメタデータを含む pagination フィールドが追加されます。

推奨事項

• すべてのデータを取得するには、limit に従って offset を増やしながら、hasNext が false になるまで複数回リクエストしてください。
• サーバーへの過負荷を避けるため、limit に非常に大きな値を指定しないでください。

使用上のヒント

1. 必要な内容を自然言語で説明します
2. Cursor が文脈を理解し、適切なコードを生成します
3. 1 つのリクエストで複数のクエリを組み合わせることができます
4. Cursor は今後参照できるよう、クエリの履歴を保持します

高度な機能

• トレンド分析：「南部地域のガス消費量の傾向を表示してください」
• 比較：「2 台のデバイス間でエネルギー消費量を比較してください」
• アラート：「水漏れのアラートを設定してください」
• レポート：「エネルギー効率のレポートを生成してください」

他の MCP クライアントでの使用と認証

他の MCP クライアント（Cursor 以外）を使用したり、外部アプリケーションと連携したりする必要がある場合は、HTTP トランスポートとトークン認証（OAuth 2.1 を推奨）を有効にする必要があります。

HTTP と認証を有効にする方法

1. HTTP トランスポートを追加する：

   • src/server.ts ファイルで、MCP サーバーの作成（const server = new McpServer(...)）後に、HTTP トランスポートのインポートと初期化を追加します。例：

     import { HttpServerTransport } from "@modelcontextprotocol/sdk/server/http.js";
     // ...
     const httpTransport = new HttpServerTransport({ port: 3000 });
     await server.connect(httpTransport);
     

   • これにより、サーバーは指定したポートで HTTP 接続を受け付けられるようになります。

2. トークン認証（OAuth 2.1）を追加する：

   • HTTP トランスポートの初期化時に認証ミドルウェアを実装します。
   • 連携の詳細については、MCP SDK と使用する OAuth プロバイダーのドキュメントを参照してください。
   • 追加する箇所の例：

     // httpTransport の作成後、リクエストを受け付ける前に認証ロジックを追加します
     // （フックやミドルウェアの詳細については SDK のドキュメントを参照してください）
     

重要：

• このプロジェクトでは、HTTP と認証のサポートはデフォルトで有効になっていません。
• 本番環境では、安全な認証を実装することが不可欠です。