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 を使用すると、常に最新の公開バージョンのサーバーが実行されるようになります。

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

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