Lumenore Mcp

Lumenore Analytics MCP Server

AI アシスタントが Lumenore の分析機能と自然言語クエリ機能を利用できるようにする Model Context Protocol（MCP）サーバーです。FastMCP と Python 3.13 を使用して構築されており、拡張性の高いデータ分析統合を実現します。

クイックスタート

1. インストールと実行

git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your client credentials (LUMENORE_CLIENT_ID and LUMENORE_SECRET)
python main.py

2. AI アシスタントを接続

• URL：http://localhost:8080/mcp
• トランスポート：ストリーミング可能な HTTP

3. 分析を開始

# Example: Get sales insights
result = await client.call_tool("nlq_to_data", {
    "userQuery": "Top 5 sales regions last month",
    "schemaId": 123
})

📖 完全なドキュメント | 🐛 問題を報告 | 🔒 プライバシーポリシー

目次

• 概要
• インストール
• 設定
• 利用可能なツール
• 使用例
• 認証
• セキュリティとプライバシー
• トラブルシューティング
• コントリビューション
• サポート
• ライセンス

概要

この MCP サーバーにより、AI アシスタントは Lumenore の強力な分析機能を利用できます。

• 自然言語クエリ：質問をデータインサイトに変換します
• 高度な分析：トレンド、予測、相関、外れ値、変化、パレート分析
• リアルタイム処理：大規模なデータセットの応答をストリーミングします
• データを一切保存しない：永続的なログを残さず、メモリ内で処理します。MCP サーバーがリクエストを Lumenore のバックエンドに転送する場合、Lumenore のプライバシーポリシーが適用されます

インストール

前提条件

• Python 3.13+
• Lumenore のクライアント認証情報（クライアント ID とシークレット）
• Lumenore サーバーインスタンスへのアクセス

セットアップ

git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt

設定

プロジェクトのルートに .env ファイルを作成し、認証情報を設定します。テンプレートとして .env.example を使用できます。

cp .env.example .env

次に、設定内容を .env に記入します。

クライアント認証情報を使用する場合

LUMENORE_CLIENT_ID="your_client_id_here"
LUMENORE_SECRET="your_secret_here"
SERVER_URL="https://preview.lumenore.com"

設定パラメーター

パラメーター	必須	説明	デフォルト
LUMENORE_CLIENT_ID	はい	クライアント認証情報による認証に使用するクライアント ID	なし
LUMENORE_SECRET	はい	クライアント認証情報による認証に使用するクライアントシークレット	なし
SERVER_URL	いいえ	Lumenore サーバーの URL	https://preview.lumenore.com

サーバーの実行

MCP サーバーを起動します。

python main.py

サーバーは http://0.0.0.0:8080 で、リアルタイムストリーミング用の SSE トランスポートを使用して実行されます。

AI アシスタントの接続

Claude for Desktop

1. 設定 → MCP Servers
2. 次の内容でサーバーを追加します。

   Name: Lumenore Analytics
   URL: http://localhost:8080/mcp
   Transport: Streamable HTTP
   

プログラムからのアクセス（Python）

from mcp.client import MCPClient

client = MCPClient("http://localhost:8080/mcp", transport="streamable_http")
tools = await client.list_tools()
result = await client.call_tool("nlq_to_data", {
    "userQuery": "Top 5 sales regions last month",
    "schemaId": 123
})

接続の詳細：

• プロトコル：MCP 2024-11-05+
• トランスポート：ストリーミング可能な HTTP（SSE）
• ポート：8080（デフォルト）
• 認証：MCP レベルの認証は不要です

接続をテスト：

curl -I http://localhost:8080  # Should return HTTP/1.1 200 OK

認証

認証情報の取得

クライアント認証情報

1. Lumenore サポートに連絡し、クライアント認証情報を取得します
2. LUMENORE_CLIENT_ID と LUMENORE_SECRET を受け取ります
3. .env ファイルに安全に保存します

詳しいセットアップ手順については、設定セクションを参照してください。

セキュリティのベストプラクティス

認証に関するトラブルシューティング

「Authorization token missing or invalid」：

• .env ファイルに認証情報が設定されていることを確認します。
  • クライアント認証情報の場合：LUMENORE_CLIENT_ID と LUMENORE_SECRET の両方が設定されていることを確認します
• Lumenore AI クレジットが利用可能であることを確認します
• SERVER_URL が正しい Lumenore インスタンスを指していることを確認します

利用可能なツール

サーバーはデータ分析用の強力なツールを 8 個提供します。

データセット管理

get_dataset_metadata - 利用可能なデータセットとスキーマ ID を一覧表示します

自然言語クエリ

nlq_to_data - 質問を構造化データに変換します

{
  "userQuery": "Top 5 sales regions last month",
  "schemaId": 123
}

高度な分析

get_trend_data - 時系列のパターンと傾向を特定します get_prediction_data - 予測と推定を生成します get_outlier_data - 異常や通常とは異なるパターンを検出します get_correlation_data - 変数間の関係を分析します get_change_data - パターンの変化や移行を検出します get_pareto_data - 80/20のインパクト分析を実行します

エラー処理

すべてのツールは、標準化された応答を返します。

• 成功：{"data": {...}, "status": "success"}
• 検証エラー：{"error": "...", "status": "validation_error"}
• サービスエラー：{"error": "...", "status": "error"}

パフォーマンス

• 応答時間：1～7秒
• タイムアウト：60秒
• 同時実行：複数のリクエストを同時に処理できます

ベストプラクティス

1. まず get_dataset_metadata を使ってスキーマ ID を確認します
2. 自然言語クエリは具体的に記述します
3. 応答の status フィールドを必ず確認します
4. パフォーマンス向上のため、頻繁に実行するクエリをキャッシュします

使用例

AI アシスタントが Lumenore Analytics MCP Server とやり取りする、現実的な例を3つ紹介します。

例1：売上実績の分析

シナリオ：ビジネスアナリストが前四半期の売上実績を把握したいと考えています。

AI アシスタントとのやり取り：

# Step 1: Get available datasets
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Query sales data
sales_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show me total sales by region for Q4 2024, sorted by highest sales",
    "schemaId": 35403
})

# Step 3: Analyze trends
trend_analysis = await client.call_tool("get_trend_data", {
    "userQuery": "What are the monthly sales trends for Q4 2024?",
    "schemaId": 35403
})

# Step 4: Identify top performers
pareto_analysis = await client.call_tool("get_pareto_data", {
    "userQuery": "Which products contribute to 80% of our sales?",
    "schemaId": 35403
})

期待される分析結果：

• 合計を含む地域別の売上内訳
• 増減を示す月次傾向の可視化
• 主な収益要因を明らかにする製品別の貢献度分析

---

例2：顧客行動の分析

シナリオ：マーケティングチームが顧客の購買パターンを把握し、異常を検出したいと考えています。

AI アシスタントとのやり取り：

# Step 1: Get customer dataset information
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Analyze customer segments
customer_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show customer demographics and average order value by age group",
    "schemaId": 35404
})

# Step 3: Detect unusual patterns
anomaly_detection = await client.call_tool("get_outlier_data", {
    "userQuery": "Find customers with unusually high order values or frequency",
    "schemaId": 35404
})

# Step 4: Understand correlations
correlation_analysis = await client.call_tool("get_correlation_data", {
    "userQuery": "What factors correlate with customer lifetime value?",
    "schemaId": 35404
})

期待される分析結果：

• 顧客の属性と支出に基づくセグメンテーション
• 不正の可能性がある顧客や VIP 顧客の特定
• ターゲットマーケティングに活用できる顧客価値の主な要因

---

例3：在庫の最適化

シナリオ：オペレーションマネージャーが需要パターンと予測に基づいて在庫レベルを最適化する必要があります。

AI アシスタントとのやり取り：

# Step 1: Get inventory dataset
metadata = await client.call_tool("get_dataset_metadata", {})

# Step 2: Analyze historical demand
demand_data = await client.call_tool("nlq_to_data", {
    "userQuery": "Show monthly demand for each product category over the past year",
    "schemaId": 35405
})

# Step 3: Identify trends
trend_analysis = await client.call_tool("get_trend_data", {
    "userQuery": "What are the demand trends for each product category?",
    "schemaId": 35405
})

# Step 4: Generate forecasts
forecast = await client.call_tool("get_prediction_data", {
    "userQuery": "Predict demand for next 3 months by product category",
    "schemaId": 35405
})

# Step 5: Detect demand changes
change_detection = await client.call_tool("get_change_data", {
    "userQuery": "Have there been any significant changes in demand patterns recently?",
    "schemaId": 35405
})

期待される分析結果：

• カテゴリ別の過去の需要パターン
• 信頼区間を含む将来の需要予測
• 需要パターンの変化に対する早期警告
• データに基づく在庫最適化の推奨事項

---

利点：

• 手動操作なしでデータを自動更新
• 業務上の意思決定に役立つリアルタイムの分析結果
• 効率的なキャッシュによるバックエンドシステムの負荷軽減

---

例から学ぶベストプラクティス

1. メタデータから始める：利用可能なデータセットを把握するため、必ず get_dataset_metadata を使います
2. ツールを組み合わせる：包括的な分析のため、複数のツールを組み合わせて使います
3. 具体的なクエリを使う：自然言語クエリは明確かつ具体的に記述します
4. エラー処理：結果を処理する前に、必ず応答のステータスを確認します
5. パフォーマンス：頻繁にアクセスするデータをキャッシュして、応答時間を短縮します

Claude のプロンプト

この MCP サーバーに接続した状態で Claude に使用できるプロンプトの例を紹介します。

売上分析の場合：

「Lumenore Analytics のツールを使って、第4四半期の売上実績を分析してください。地域別の内訳を確認し、業績上位の製品を特定して、売上傾向を把握したいです。」

顧客インサイトの場合：

顧客の属性を分析し、通常とは異なる購買パターンがあれば見つけ、顧客価値を左右する要因を特定してください。利用可能な分析ツールを使って、包括的なインサイトを提供してください。」

在庫管理の場合：

「予測分析ツールと傾向分析ツールを使って、次の四半期の予測を生成し、最近の需要動向の変化を特定してください。」

---

エラー処理

すべてのツールで、種類ごとに詳細なエラー処理を実装しています。

# Validation errors
{
    "error": "Invalid request parameters: <details>",
    "status": "validation_error",
    "query": "<user_query>",
    "schema_id": <schema_id>
}

# Service errors
{
    "error": "<Operation> failed: <details>",
    "status": "error",
    "query": "<user_query>",
    "schema_id": <schema_id>
}

サーバーのテスト

MCP サーバーは、MCP 互換クライアントを使うか、SSE エンドポイントに HTTP リクエストを送信してテストできます。

# Example: Testing with curl (adjust based on MCP protocol)
curl -N http://localhost:8080

セキュリティとプライバシー

セキュリティの概要

Lumenore Analytics MCP Server は、データと API 認証情報を保護するために、複数のセキュリティ層を実装しています。

データ保護

• メモリ内処理：すべてのデータはメモリ内で処理され、レスポンスの生成後ただちに破棄されます
• データの保存なし：MCP サーバーは、ユーザーのクエリ、スキーマ ID、レスポンスデータを保存またはログに記録しません
• 安全な通信：すべてのバックエンド API リクエストで HTTPS 暗号化を使用します
• 認証情報のセキュリティ：クライアント認証情報がログに記録、保存されたり、レスポンスで公開されたりすることはありません

認証のセキュリティ

• クライアント認証情報フロー：クライアント ID とシークレットを使用する業界標準の認証方式です
• セッション管理：トークンを自動更新する、安全な Cookie ベースのセッション処理です
• MCP レベルの認証なし：MCP 接続に認証は必要ありません（バックエンドの認証はサーバー側で処理されます）
• セキュリティ監視：失敗した認証の試行は、セキュリティ分析のためにログに記録されます

認証情報のベストプラクティス

• 環境変数：認証情報は環境変数または .env ファイルに保存してください（コードには記述しないでください）
• 定期的なローテーション：90 日ごと、または必要に応じて認証情報をローテーションしてください
• スコープの制限：必要最小限の権限を持つ認証情報を使用してください
• 環境の分離：開発、ステージング、本番環境では異なる認証情報を使用してください

プライバシーポリシー

Lumenore によるデータの取り扱いについて詳しくは、プライバシーポリシーをご覧ください。

プライバシーの基本原則

• 最小限のデータ処理：ユーザーから提供されたクエリとスキーマ ID のみを処理します
• 会話履歴の保存なし：会話履歴を保存またはログに記録しません
• ユーザーによる制御：クエリおよび分析対象のデータはユーザーが制御します
• コンプライアンス：データ保護規制（GDPR、CCPA）への準拠を前提に設計されています

データフローのプライバシー

User Query → MCP Server → Lumenore Backend → Results → User
             (No storage)   (Lumenore's privacy policy applies)

プライバシーに関する考慮事項

• MCP サーバーは、AI アシスタントと Lumenore のバックエンドとの間で安全なプロキシとして機能します
• Lumenore のバックエンド API に適用されるプライバシーおよびデータ取り扱いポリシーは、すべてお客様のデータにも適用されます
• サーバー自体は、リクエストの処理中を除き、ユーザーデータを保持しません
• ユーザーは、クエリが適用されるデータ保護法に準拠していることを確認する責任があります

コンプライアンス

規制への準拠

• GDPR：一般データ保護規則に準拠しています
• CCPA：カリフォルニア州消費者プライバシー法に準拠しています
• SOC 2：バックエンドサービスは SOC 2 セキュリティ基準に従っています
• ISO 27001：情報セキュリティ管理のベストプラクティスに従っています

データレジデンシー

• データ処理は Lumenore のクラウドインフラストラクチャで行われます
• データレジデンシーの要件については、Lumenore の営業チームにご相談ください
• エンタープライズ向けの導入では、プライベートクラウドまたはオンプレミスの選択肢に対応できる場合があります

セキュリティ設定

環境のセキュリティ

# Secure credentials management
export LUMENORE_CLIENT_ID="your_client_id"
export LUMENORE_SECRET="your_secret"

# Restrict file permissions
chmod 600 .env
chmod 700 /path/to/server/directory

# Use secure network connections only
# Avoid using public Wi-Fi for sensitive operations

本番環境のセキュリティ

• 本番環境専用のクライアント認証情報を使用してください
• 認証情報のローテーションを自動化してください
• API の使用状況を監視し、不審なアクティビティに対するアラートを設定してください
• API アクセスに IP アドレスの許可リストを導入することを検討してください
• サーバー間の通信には VPN またはプライベートネットワークを使用してください

脆弱性管理

セキュリティ問題の報告

セキュリティを重視しています。脆弱性を発見した場合：

1. メールでご連絡ください：[email protected]
2. 脆弱性の詳細と再現手順をお知らせください
3. 24 時間以内に受領確認を行います
4. 一般公開する前に、問題の解決にご協力ください

セキュリティ更新

• セキュリティパッチを優先し、速やかに適用します
• サポートチャネルを通じてセキュリティ通知を購読してください
• インフラストラクチャに対して定期的にセキュリティ評価を実施しています

データ暗号化

通信中

• すべての API 通信で TLS 1.2 以上の暗号化を使用します
• すべてのバックエンド接続で HTTPS を必須としています
• セキュリティをさらに強化するため、証明書ピンニングを実装できます

保存時

• バックエンドのデータストレージでは、保存時に暗号化を使用します
• データベースの暗号化により、保存された分析データを保護します
• キー管理は、業界のベストプラクティスに従います

アクセス制御

最小権限の原則

• クライアントの認証情報には、必要最小限の権限を付与してください
• アプリケーションや環境ごとに、認証情報を分けてください
• 認証情報の権限と使用状況を定期的に確認してください

ネットワークセキュリティ

• ファイアウォールルールで、必要なポートのみにアクセスを制限してください
• サーバー管理に VPN アクセスを導入することを検討してください
• 本番環境へのデプロイでは、ネットワークセグメンテーションを使用してください

---

トラブルシューティング

簡単な診断手順

1. サーバーが稼働していることを確認：curl -I http://localhost:8080
2. トークンが読み込まれていることを確認：「No authorization token」警告がないか、サーバーの起動ログを確認します
3. バックエンドへの接続をテスト：curl -I https://preview.lumenore.com
4. MCP プロトコルを確認：クライアントが Streamable HTTP トランスポートを使用していることを確認します

クライアント設定の例：

{
    "server": {
        "lumenore-server": {
            "type": "streamable-http",
            "url": "http://localhost:8080/mcp",
        }
    }
}

Python を使った手動テスト：

from config import config
from core.lumenore_analytics import LumenoreAnalytics
import asyncio

async def test():
    client = LumenoreAnalytics()
    result = await client.make_request('get-domain', method='GET')
    print(result)

asyncio.run(test())

サポートを受ける

上記の手順を試しても問題が解決しない場合は、次の手順をお試しください。

1. サーバーログを確認し、詳細なエラーメッセージを確認します
2. トークンの有効性と権限を確認します
3. バックエンド API を直接テストして、MCP とバックエンドのどちらに問題があるかを切り分けます
4. MCP クライアントの設定で、トランスポートと URL の設定を確認します
5. ログとエラーメッセージを添えて、サポートにお問い合わせください（サポートセクションを参照）

コントリビューション

Lumenore Analytics MCP Server へのコントリビューションを歓迎します。以下のガイドラインに従ってください。

行動規範

このプロジェクトはContributor Covenantに基づいて公開されています。参加する場合は、この規範を遵守してください。

コントリビューションの方法

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

開発環境のセットアップ

# Clone your fork
git clone <your-fork-url>
cd lumenore-mcp

# Install development dependencies
pip install -r requirements.txt

# Run tests (if available)
python -m pytest

バグの報告

イシュートラッカーからバグを報告してください。以下の情報を含めてください。

• 再現手順
• 期待される動作と実際の動作
• 環境の詳細（Python のバージョン、OS）

機能リクエスト

GitHub Issues からの機能リクエストを歓迎します。以下の点にご留意ください。

• まず既存の Issue を検索してください
• ユースケースを明確に記載してください
• 希望する機能を説明してください

ライセンス

このプロジェクトは MIT ライセンスのもとで公開されています。詳細については、LICENSEファイルを参照してください。

サポート

お問い合わせ先

技術サポートやお問い合わせについては、以下をご利用ください。

• メール：[email protected]
• ウェブサイト：https://lumenore.com/
• ドキュメント：Lumenore Analytics ドキュメント

---

バージョン：1.0.0
最終更新日：2026年1月
Python：3.13+
MCP プロトコル：MCP 2024-11-05 仕様に準拠