Inoyu Apache Unomi MCP Server

Inoyu Apache Unomi MCP サーバー

Claude が Apache Unomi プロファイル管理を通じてユーザー コンテキストを維持できるようにするモデル コンテキスト プロトコル サーバー。

⚠️早期導入のお知らせ

これはデモンストレーションを目的とした初期実装です。

• 実稼働環境での使用は検証されていません
• 変更される可能性があります
• まだ公式にはサポートされていません
• 学習と実験のみに使用

現在のスコープ

この実装では以下が提供されます。

• メールを使用したプロフィールの検索と作成
• プロフィールプロパティ管理
• 基本的なセッション処理
• コンテキスト分離のためのスコープ管理

その他のUnomi機能（イベント、セグメント、セッションプロパティなど）は現在実装されていません。今後の開発の優先順位について、コミュニティからのフィードバックをお待ちしております。

デモ

MCP サーバーによって Claude がコンテキストを維持し、ユーザー プロファイルを管理できるようになる様子をご覧ください。

インストール

Claude Desktop で使用するには、サーバー設定と環境変数を追加します。

MacOS の場合: ~/Library/Application Support/Claude/claude_desktop_config.json Windows の場合: %APPDATA%/Claude/claude_desktop_config.json

設定ファイルのenvセクションでは、サーバーに必要な環境変数を設定できます。値を実際のUnomiサーバーの詳細に置き換えてください。

設定を更新した後は、必ずClaude Desktopを再起動してください。その後、チャットウィンドウの右下にあるツールアイコンをクリックして、このサーバーが提供するすべてのツールが認識されていることを確認してください。

特徴

プロフィールアクセス

• 自動作成によるメールベースのプロフィール検索
• プロフィールプロパティ、セグメント、スコアへのアクセス
• すべてのデータ交換にJSON形式を使用する
• 日付ベースのIDによる自動セッション管理

ツール

• get_my_profile - 環境変数を使用してプロファイルを取得する
  • 環境またはメール検索から UNOMI_PROFILE_ID を使用します
  • 現在の日付に基づいてセッションIDを自動的に生成します
  • オプションパラメータ:
    • requireSegments: セグメント情報を含める
    • requireScores: スコア情報を含める
• update_my_profile - プロフィールのプロパティを更新する
  • 環境またはメール検索から UNOMI_PROFILE_ID を使用します
  • 更新するキーと値のペアを持つプロパティオブジェクトを取得します
  • 文字列、数値、ブール値、および null 値をサポートします
  • 例：
    { "properties": { "firstName": "John", "age": 30, "isSubscribed": true, "oldProperty": null } }
• get_profile - IDで特定のプロファイルを取得する
  • 必須パラメータとしてprofileIdを取ります
  • Unomiから完全なプロフィールデータを返します
• search_profiles - プロフィールを検索する
  • クエリ文字列とオプションの制限/オフセットパラメータを受け取ります
  • firstName、lastName、およびメールフィールドを検索します
• create_scope - 新しいUnomiスコープを作成する
  • スコープ識別子とオプションの名前/説明を取得します
  • イベントの追跡とプロフィールの更新に必要
  • 例：
    { "scope": "my-app", "name": "My Application", "description": "Scope for my application events" }

スコープ管理

サーバーはスコープを自動的に管理します。

1. デフォルトのスコープ:
   • デフォルトのスコープclaude-desktopすべての操作に使用されます
   • 必要に応じて自動的に作成
   • プロフィールの更新とイベントの追跡に使用されます
2. カスタムスコープ:
   • create_scopeツールを使用して作成できます
   • 異なるアプリケーションやコンテキストを分離するのに便利です
   • プロファイル操作で使用する前に存在している必要があります
3. 自動スコープ作成:
   • サーバーは必要なスコープが存在するかどうかを確認します
   • 不足している場合は自動的に作成します
   • スコープメタデータに意味のあるデフォルトを使用する

注: スコープは必要に応じて自動的に作成されますが、 create_scopeツールを使用してカスタム名と説明で手動で作成することもできます。

概要

このMCPサーバーにより、ClaudeはApache Unomiのプロファイル管理システムを通じてユーザーに関するコンテキストを維持できます。これにより、以下のことが可能になります。

主な機能

1. ユーザー認識:
   • メールまたはプロフィールIDを使用して会話全体でユーザーを識別する
   • セッション間で一貫したユーザーコンテキストを維持する
   • ユーザープロファイルを自動的に作成および管理する
2. コンテキスト管理:
   • ユーザー設定を保存および取得する
3. 統合機能:
   • シームレスなClaudeデスクトップ統合
   • 自動セッション管理
   • スコープベースのコンテキスト分離

あなたにできること

• 会話全体にわたってユーザーの好みをクロードに記憶させる
• ユーザー固有の情報を保存および取得する
• 一貫したユーザーコンテキストを維持する
• メール識別による複数ユーザー管理

前提条件

• Apache Unomiサーバーの実行
• クロードデスクトップインストール
• Unomiサーバーへのネットワークアクセス
• 適切なセキュリティ構成
• 必要な環境変数

構成

環境変数

サーバーには次の環境変数が必要です。

プロファイル解像度

サーバーは、プロファイル ID を解決するために 2 段階のプロセスを使用します。

1. 電子メール検索（ UNOMI_EMAILが設定されている場合）:
   • 一致するメールアドレスを持つプロフィールを検索します
   • 見つかった場合は、そのプロファイルのIDを使用します
   • セッション間で一貫したプロファイルを維持するのに役立ちます
2. フォールバックプロファイルID:
   • メール検索が失敗した場合、またはUNOMI_EMAIL設定されていない場合
   • 環境のUNOMI_PROFILE_IDを使用します
   • プロファイルが常に利用可能であることを保証する

応答では、 sourceフィールドを通じてどのメソッドが使用されたかが示されます。

• "email_lookup" : メールで見つかったプロフィール
• "environment" : フォールバックプロファイルIDを使用

Unomiサーバーの構成

1. etc/org.apache.unomi.cluster.cfgで保護されたイベントを設定します。
   # Required for protected events like property updates org.apache.unomi.cluster.authorization.key=your-unomi-key # Required to allow Claude Desktop to access Unomi # Replace your-claude-desktop-ip with your actual IP org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
2. Unomi サーバーのetc/org.apache.unomi.cors.cfgで CORS が適切に設定されていることを確認します。
   # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
3. 変更を適用するにはUnomiサーバーを再起動してください

重要: Unomi キーは、サーバー構成と Claude Desktop の UNOMI_KEY 環境変数の間で完全に一致する必要があります。

構成

環境変数

サーバーには次の環境変数が必要です。

プロファイル解像度

サーバーは、プロファイル ID を解決するために 2 段階のプロセスを使用します。

1. 電子メール検索（ UNOMI_EMAILが設定されている場合）:
   • 一致するメールアドレスを持つプロフィールを検索します
   • 見つかった場合は、そのプロファイルのIDを使用します
   • セッション間で一貫したプロファイルを維持するのに役立ちます
2. フォールバックプロファイルID:
   • メール検索が失敗した場合、またはUNOMI_EMAIL設定されていない場合
   • 環境のUNOMI_PROFILE_IDを使用します
   • プロファイルが常に利用可能であることを保証する

応答では、 sourceフィールドを通じてどのメソッドが使用されたかが示されます。

• "email_lookup" : メールで見つかったプロフィール
• "environment" : フォールバックプロファイルIDを使用

Unomiサーバーの構成

1. etc/org.apache.unomi.cluster.cfgで保護されたイベントを設定します。
   # Required for protected events like property updates org.apache.unomi.cluster.authorization.key=your-unomi-key # Required to allow Claude Desktop to access Unomi # Replace your-claude-desktop-ip with your actual IP org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
2. Unomi サーバーのetc/org.apache.unomi.cors.cfgで CORS が適切に設定されていることを確認します。
   # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
3. 変更を適用するにはUnomiサーバーを再起動してください

重要: Unomi キーは、サーバー構成と Claude Desktop の UNOMI_KEY 環境変数の間で完全に一致する必要があります。

発達

依存関係をインストールします:

サーバーを構築します。

自動リビルドを使用した開発の場合:

デバッグ

MCPサーバーはstdio経由で通信するため、デバッグが困難になる場合があります。パッケージスクリプトとして提供されているMCP Inspectorの使用をお勧めします。

インスペクターは、ブラウザでデバッグ ツールにアクセスするための URL を提供します。

Claude Desktop のログを tail して、MCP のリクエストと応答を確認することもできます。

セッションIDの形式

get_my_profileを使用すると、セッション ID は次の形式で自動的に生成されます。

たとえば、プロフィール ID が「user123」で、今日が 2024 年 3 月 15 日の場合、セッション ID は次のようになります。

トラブルシューティング

よくある問題

1. 保護されたイベントが失敗する
   • 両方の構成でUnomiキーが完全に一致することを確認する
   • IPアドレスが正しくホワイトリストに登録されているか確認する
   • プロパティを更新する前にスコープが存在することを確認する
   • 必要に応じて CORS 構成を確認する
2. プロフィールが見つかりません
   • UNOMI_EMAILが正しく設定されているか確認してください
   • メールの形式が有効であることを確認してください
   • Unomiにプロファイルが存在することを確認する
   • フォールバックUNOMI_PROFILE_IDが有効かどうかを確認します
3. セッションの問題
   • セッションは日付ベースであることを覚えておいてください
   • 1日に1つのプロファイルにつき1セッションのみ
   • セッションIDの形式がprofileId-YYYYMMDDと一致していることを確認します
   • セッションのスコープが存在することを確認する
4. 接続の問題
   • Unomiサーバーが実行中であることを確認する
   • ネットワーク接続を確認する
   • UNOMI_BASE_URLが正しいことを確認してください
   • 認証資格情報を確認する

確認すべきログ

1. クロードデスクトップログ:
   # MacOS ~/Library/Logs/Claude/mcp*.log # Windows %APPDATA%\Claude\mcp*.log
2. Unomi サーバーログ:
   # Usually in $UNOMI_HOME/logs/karaf.log

クイックフィックス

1. リセット状態:
   # Stop Claude Desktop # Clear logs rm ~/Library/Logs/Claude/mcp*.log # Restart Claude Desktop
2. 構成の確認:
   # Check Unomi connection curl -u username:password http://your-unomi-server:8181/cxs/cluster # Test scope exists curl -u username:password http://your-unomi-server:8181/cxs/scopes/claude-desktop

クロードデスクトップの設定オプション

1. Claude Desktop 構成を作成または編集します。
   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
2. NPX を使用してサーバー構成を追加します。
   { "mcpServers": { "unomi-server": { "command": "npx", "args": ["@inoyu/mcp-unomi-server"], "env": { "UNOMI_BASE_URL": "http://your-unomi-server:8181", "UNOMI_USERNAME": "your-username", "UNOMI_PASSWORD": "your-password", "UNOMI_PROFILE_ID": "your-profile-id", "UNOMI_KEY": "your-unomi-key", "UNOMI_EMAIL": "your-email@example.com", "UNOMI_SOURCE_ID": "claude-desktop" } } } }

注: NPX を使用すると、常に最新の公開バージョンのサーバーが実行されるようになります。

あるいは、特定のバージョンを使用する場合は、次のようにします。

開発またはローカルインストールの場合: