Inoyu Apache Unomi MCP Server

Name: Inoyu Apache Unomi MCP Server
Author: sergehuber

ローカル

github.com/sergehuberビジネス・マーケティング113 週間前に更新

リポジトリ

Inoyu Apache Unomi MCP Server について

Apache Unomiを利用するチーム向けのMCPサーバーで、プロフィール管理を通じて会話をまたいだユーザー文脈を保持します。プロフィール、属性、セッション、スコープ、同意を扱い、READMEではデモと実験向けの初期実装とされています。

主な機能

01メールによるプロフィール検索・作成
02プロフィール属性の取得と更新
03ユーザー同意と状態の管理
04スコープによる文脈の分離
05Apache Unomi V2・V3への対応

活用シーン

01会話をまたいだユーザー設定の保持
02顧客プロフィールの取得と管理
03同意状態の確認や更新

MCP 対応

MCPサーバーとして、Apache Unomiのプロフィール、スコープ、同意を管理するツールをクライアントに公開し、対話中のユーザー文脈の取得と維持を可能にします。

#inoyu #unomi #customer-data-platform

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "inoyu-mcp-unomi-server": {
      "command": "npx",
      "args": [
        "-y",
        "@inoyu/mcp-unomi-server"
      ],
      "env": {
        "UNOMI_BASE_URL": "<UNOMI_BASE_URL>",
        "UNOMI_VERSION": "<UNOMI_VERSION>",
        "UNOMI_USERNAME": "<UNOMI_USERNAME>",
        "UNOMI_PASSWORD": "<UNOMI_PASSWORD>",
        "UNOMI_PROFILE_ID": "<UNOMI_PROFILE_ID>",
        "UNOMI_KEY": "<UNOMI_KEY>",
        "UNOMI_EMAIL": "<UNOMI_EMAIL>",
        "UNOMI_SOURCE_ID": "<UNOMI_SOURCE_ID>",
        "UNOMI_TENANT_ID": "<UNOMI_TENANT_ID>",
        "UNOMI_PUBLIC_KEY": "<UNOMI_PUBLIC_KEY>",
        "UNOMI_PRIVATE_KEY": "<UNOMI_PRIVATE_KEY>"
      }
    }
  }
}

起動コマンドnpx -y @inoyu/mcp-unomi-server

設定が必要な環境変数

UNOMI_BASE_URL

UNOMI_VERSION

UNOMI_USERNAME

UNOMI_PASSWORDシークレット

UNOMI_PROFILE_ID

UNOMI_KEYシークレット

UNOMI_EMAIL

UNOMI_SOURCE_ID

UNOMI_TENANT_ID

UNOMI_PUBLIC_KEYシークレット

UNOMI_PRIVATE_KEYシークレット

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npm@inoyu/mcp-unomi-serverstdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Inoyu Apache Unomi MCP サーバー

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

⚠️ 初期実装に関するお知らせ

この初期実装は、デモを目的としています。

本番環境での使用は検証されていません

変更される可能性があります

（現時点では）公式サポートの対象ではありません

学習および実験のみを目的としています

現在の対応範囲

この実装では、以下を提供します。

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

イベント、セグメント、セッションプロパティなど、その他の Unomi 機能は現在実装されていません。今後の開発の優先事項に関するコミュニティからのフィードバックを歓迎します。

デモ

この MCP サーバーを使って Claude がコンテキストを維持し、ユーザープロファイルを管理する様子をご覧ください。

インストール

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

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

{
  "mcpServers": {
    "unomi-server": {
      "command": "npx",
      "args": ["@inoyu/mcp-unomi-server"],
      "env": {
        "UNOMI_BASE_URL": "http://your-unomi-server:8181",
        "UNOMI_VERSION": "3", // Use "2" for Unomi V2, "3" for Unomi V3 (default)
        "UNOMI_USERNAME": "your-username", // Required for V2, fallback for V3
        "UNOMI_PASSWORD": "your-password", // Required for V2, fallback for V3
        "UNOMI_PROFILE_ID": "your-profile-id",
        "UNOMI_KEY": "your-unomi-key", // Required for V2 only
        "UNOMI_EMAIL": "[email protected]",
        "UNOMI_SOURCE_ID": "claude-desktop",
        "UNOMI_TENANT_ID": "your-tenant-id", // Required for V3
        "UNOMI_PUBLIC_KEY": "your-public-key", // Required for V3
        "UNOMI_PRIVATE_KEY": "your-private-key" // Required for V3
      }
    }
  }
}

設定の 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 - プロファイルを検索します
- 検索文字列と、オプションの limit／offset パラメーターを受け取ります
- firstName、lastName、email フィールドを対象に検索します
create_scope - 新しい Unomi スコープを作成します
- スコープ識別子と、オプションの name／description を受け取ります
- イベントのトラッキングやプロファイルの更新に必要です
- 例：
```
{
  "scope": "my-app",
  "name": "My Application",
  "description": "Scope for my application events"
}
```
get_tenant_info - 現在のテナントに関する情報を取得します（V3 のみ）
- テナントの詳細、バージョン情報、キーのステータスを返します
- Unomi V3 の使用時のみ利用できます
- パラメーターは不要です

同意管理ツール

update_consent - modifyConsent イベントを使用してユーザーの同意ステータスを更新します
- 公式ドキュメントに記載されている Apache Unomi Consent API を使用します
- 必須パラメーター：
  - consentId：同意の一意の識別子
  - status：同意ステータス（GRANTED、DENIED、または REVOKED）
- 任意パラメーター：
  - typeIdentifier：同意のタイプ識別子
  - scope：同意のスコープ（デフォルトは claude-desktop）
  - metadata：同意に関する追加メタデータ
- GDPR への準拠：
  - GRANTED の同意は1年後に期限切れになります（GDPR の推奨）
  - DENIED／REVOKED の同意は直ちに期限切れになります
- 例：
```
{
  "consentId": "marketing-consent",
  "status": "GRANTED",
  "typeIdentifier": "marketing",
  "scope": "claude-desktop",
  "metadata": {
    "source": "claude-desktop",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```
get_consent - プロファイルの特定の同意情報を取得します
- 必須パラメーターとして consentId を指定します
- ステータス、タイムスタンプ、メタデータなどの同意の詳細を返します
- デフォルトではユーザーのプロファイルを使用します（環境変数またはメールアドレスの検索から取得）
- 例：
```
{
  "consentId": "marketing-consent"
}
```
list_consents - 任意のフィルターを指定して、プロファイルのすべての同意を一覧表示します
- 任意パラメーター：
  - profileId：同意を一覧表示するプロファイル ID（指定しない場合はユーザーのプロファイルを使用します）
  - status：同意ステータス（GRANTED、DENIED、または REVOKED）で絞り込みます
  - scope：スコープで絞り込みます
- メタデータを含む、フィルター済みの同意一覧を返します
- 例：
```
{
  "status": "GRANTED",
  "scope": "claude-desktop"
}
```

スコープ管理

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

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

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

Apache Unomi V2/V3 との互換性

この MCP サーバーは Apache Unomi V2 と V3 の両方をサポートし、バージョンを自動検出して適切な認証方式を使用します。

バージョン検出

サーバーは UNOMI_VERSION 環境変数に基づいて Unomi のバージョンを自動検出します：

UNOMI_VERSION=2 - V2 認証（システム管理者）を使用します
UNOMI_VERSION=3 - V3 認証（テナントベース）を使用します - デフォルト

V2 と V3 の認証

V2（レガシー）：

システム管理者認証を使用します（デフォルトは karaf/karaf）
すべての操作で同じ認証方式を使用します
UNOMI_USERNAME、UNOMI_PASSWORD、UNOMI_KEY が必要です

V3（マルチテナント）：

API キーを使用したテナントベースの認証を使用します
エンドポイントの種類に応じて異なる認証を使用します：
- パブリックエンドポイント（/context.json）：公開キーを含む X-Unomi-Api-Key ヘッダーを使用します
- プライベートエンドポイント（プロファイル、スコープ）：テナント認証（tenantId:privateKey）を使用します
- システム操作：システム管理者認証にフォールバックします
UNOMI_TENANT_ID、UNOMI_PUBLIC_KEY、UNOMI_PRIVATE_KEY が必要です

V2 から V3 への移行

環境変数を更新します：

# Remove V2-specific variables
# UNOMI_KEY (no longer needed)

# Add V3-specific variables
UNOMI_VERSION=3
UNOMI_TENANT_ID=your-tenant-id
UNOMI_PUBLIC_KEY=your-public-key
UNOMI_PRIVATE_KEY=your-private-key

V3 のメリット：
- テナント間のデータを完全に分離できます
- テナント固有の API キーによりセキュリティが強化されます
- マルチテナント環境のスケーラビリティが向上します
- データプライバシー規制への準拠が向上します

概要

この MCP サーバーを使うと、Apache Unomi のプロファイル管理システムを通じて、Claude がユーザーのコンテキストを維持できます。次のことが可能です。

主な機能

ユーザーの識別：
- メールアドレスまたはプロファイル ID を使って、会話をまたいでユーザーを識別します
- セッション間で一貫したユーザーコンテキストを維持します
- ユーザープロファイルを自動的に作成、管理します
コンテキスト管理：
- ユーザーの設定を保存、取得します
- ユーザーの同意設定を管理します
- 同意のステータスと履歴を追跡します
同意管理：
- Apache Unomi の Consent API を使って、ユーザーの同意ステータスを更新します
- 特定の同意情報を取得します
- ステータスとスコープで同意を一覧表示、フィルタリングします
- 同意の有効期限切れを自動的に処理します（GDPR に準拠）
- GDPR およびプライバシー規制への準拠をサポートします
統合機能：
- Claude Desktop とシームレスに統合します
- セッションを自動的に管理します
- スコープベースでコンテキストを分離します

できること

Claude が会話をまたいでユーザーの設定を記憶できるようにします
ユーザー固有の情報を保存、取得します
一貫したユーザーコンテキストを維持します
メールアドレスによる識別で複数のユーザーを管理します
ユーザーの同意設定を追跡、管理します
プライバシー規制（GDPR、CCPA など）に準拠します
同意ステータスをリアルタイムで更新します
同意の履歴とステータスを照会します

前提条件

Apache Unomi サーバーが稼働していること
Claude Desktop がインストールされていること
Unomi サーバーへのネットワークアクセス
適切なセキュリティ設定
必須の環境変数

設定

環境変数

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

UNOMI_BASE_URL=http://your-unomi-server:8181
UNOMI_USERNAME=your-username
UNOMI_PASSWORD=your-password
UNOMI_PROFILE_ID=your-profile-id
UNOMI_SOURCE_ID=your-source-id
UNOMI_KEY=your-unomi-key
UNOMI_EMAIL=your-email

任意：

# Where the server writes its debug log. Defaults to <os-temp-dir>/unomi-mcp-server.log.
UNOMI_LOG_FILE=/path/to/unomi-mcp-server.log

プロファイルの解決

サーバーは、次の2段階の手順でプロファイル ID を解決します。

メールアドレスによる検索（UNOMI_EMAIL が設定されている場合）：
- メールアドレスが一致するプロファイルを検索します
- 見つかった場合、そのプロファイルの ID を使用します
- セッション間で一貫したプロファイルを維持するのに便利です
フォールバックのプロファイル ID：
- メールアドレスによる検索に失敗した場合、または UNOMI_EMAIL が設定されていない場合
- 環境変数の UNOMI_PROFILE_ID を使用します
- 常にプロファイルを利用できるようにします

応答には、source フィールドを通じて使用した方法が示されます。

"email_lookup"：メールアドレスからプロファイルを検出
"environment"：フォールバックのプロファイル ID を使用

Unomi サーバーの設定

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

Unomi サーバーで、etc/org.apache.unomi.cors.cfg に CORS が適切に設定されていることを確認します。
```
# Add your Claude Desktop origin if needed
org.apache.unomi.cors.allowed.origins=http://localhost:*
```
変更を適用するため、Unomi サーバーを再起動します

重要：サーバー設定の Unomi キーと、Claude Desktop の UNOMI_KEY 環境変数の値は完全に一致している必要があります。

設定

環境変数

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

UNOMI_BASE_URL=http://your-unomi-server:8181
UNOMI_USERNAME=your-username
UNOMI_PASSWORD=your-password
UNOMI_PROFILE_ID=your-profile-id
UNOMI_SOURCE_ID=your-source-id
UNOMI_KEY=your-unomi-key
UNOMI_EMAIL=your-email

任意：

# Where the server writes its debug log. Defaults to <os-temp-dir>/unomi-mcp-server.log.
UNOMI_LOG_FILE=/path/to/unomi-mcp-server.log

プロファイルの解決

サーバーは、次の2段階の手順でプロファイル ID を解決します。

メールアドレスによる検索（UNOMI_EMAIL が設定されている場合）：
- メールアドレスが一致するプロファイルを検索します
- 見つかった場合、そのプロファイルの ID を使用します
- セッション間で一貫したプロファイルを維持するのに便利です
フォールバックのプロファイル ID：
- メールアドレスによる検索に失敗した場合、または UNOMI_EMAIL が設定されていない場合
- 環境変数の UNOMI_PROFILE_ID を使用します
- 常にプロファイルを利用できるようにします

応答には、source フィールドを通じて使用した方法が示されます。

"email_lookup"：メールアドレスからプロファイルを検出
"environment"：フォールバックのプロファイル ID を使用

Unomi サーバーの設定

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

Unomi サーバーで、etc/org.apache.unomi.cors.cfg に CORS が適切に設定されていることを確認します。
```
# Add your Claude Desktop origin if needed
org.apache.unomi.cors.allowed.origins=http://localhost:*
```
変更を適用するため、Unomi サーバーを再起動します

重要：サーバー設定の Unomi キーと、Claude Desktop の UNOMI_KEY 環境変数の値は完全に一致している必要があります。

開発

コントリビューションを歓迎します。プルリクエストがマージされる前に、CONTRIBUTING.md を読み、Contributor License Agreement に署名してください。

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

npm install

サーバーをビルドします：

npm run build

自動再ビルドを有効にして開発する場合：

npm run watch

デバッグ

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

npm run inspector

Inspector は、ブラウザーでデバッグツールにアクセスするための URL を表示します。

Claude Desktop のログを tail して、MCP のリクエストとレスポンスを確認することもできます：

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

セッション ID の形式

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

[profileId]-YYYYMMDD

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

user123-20240315

トラブルシューティング

よくある問題

保護対象イベントの失敗
- 両方の設定で Unomi キーが完全に一致していることを確認します
- IP アドレスが正しくホワイトリストに登録されていることを確認します
- プロパティを更新する前にスコープが存在することを確認します
- 必要に応じて CORS の設定を確認します
プロフィールが見つからない
- UNOMI_EMAIL が正しく設定されていることを確認します
- メールアドレスの形式が有効であることを確認します
- Unomi にプロフィールが存在することを確認します
- フォールバックの UNOMI_PROFILE_ID が有効か確認します
セッションの問題
- セッションは日付に基づいていることに注意してください
- プロフィールごとに 1 日 1 セッションのみです
- セッション ID の形式が profileId-YYYYMMDD と一致していることを確認します
- セッションにスコープが存在することを確認します
接続の問題
- Unomi サーバーが実行中であることを確認します
- ネットワーク接続を確認します
- UNOMI_BASE_URL が正しいことを確認します
- 認証情報が正しいことを確認します

確認するログ

Claude Desktop のログ：

# MacOS
~/Library/Logs/Claude/mcp*.log

# Windows
%APPDATA%\Claude\mcp*.log

Unomi サーバーのログ：

# Usually in
$UNOMI_HOME/logs/karaf.log

簡単な修正方法

状態をリセット：

# Stop Claude Desktop
# Clear logs
rm ~/Library/Logs/Claude/mcp*.log
# Restart Claude Desktop

設定を確認：

# 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

Claude Desktop の設定オプション

Claude Desktop の設定を作成または編集します：
- MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%/Claude/claude_desktop_config.json

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": "[email protected]",
        "UNOMI_SOURCE_ID": "claude-desktop"
      }
    }
  }
}

注：NPX を使用すると、常に公開済みの最新バージョンのサーバーを実行できます。

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

{
  "mcpServers": {
    "unomi-server": {
      "command": "npx",
      "args": ["@inoyu/[email protected]"],
      "env": {
        // ... environment variables ...
      }
    }
  }
}

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

{
  "mcpServers": {
    "unomi-server": {
      "command": "node",
      "args": ["/path/to/local/mcp-unomi-server/build/index.js"],
      "env": {
        // ... environment variables ...
      }
    }
  }
}

Markdown 対応

ログインしてコメント

基本情報

ライセンス: Apache-2.0
作者: sergehuber
言語: node
トランスポート: stdio
掲載日: 2024年12月13日
最終更新: 3 週間前

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

Inoyu Apache Unomi MCP Server

Inoyu Apache Unomi MCP Server について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

Inoyu Apache Unomi MCP サーバー

現在の対応範囲

デモ

インストール

機能

プロファイルへのアクセス

ツール

同意管理ツール

スコープ管理

Apache Unomi V2/V3 との互換性

バージョン検出

V2 と V3 の認証

V2 から V3 への移行

概要

主な機能

できること

前提条件

設定

環境変数

プロファイルの解決

Unomi サーバーの設定

設定

環境変数

プロファイルの解決

Unomi サーバーの設定

開発

デバッグ

セッション ID の形式

トラブルシューティング

よくある問題

確認するログ

簡単な修正方法

Claude Desktop の設定オプション

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？