Omi MCP Server

Omi MCP サーバー

このプロジェクトは、Omi API と連携するための Model Context Protocol（MCP）サーバーを提供します。このサーバーには、会話やメモリーを読み取るツールに加え、新しい会話やメモリーを作成するツールが用意されています。

セットアップ

1. リポジトリをクローンします
2. npm install で依存関係をインストールします
3. 次の変数を含む .env ファイルを作成します：

   API_KEY=your_api_key
   APP_ID=your_app_id
   

使用方法

Smithery 経由でインストールする

Smithery 経由で Claude Desktop 用 Omi MCP Server を自動的にインストールするには：

npx -y @smithery/cli install @fourcolors/omi-mcp --client claude

サーバーをビルドする

npm run build

サーバーを実行する

npm run start

開発モード

ホットリロードを有効にして開発するには：

npm run dev

サーバーをテストする

MCP サーバーとやり取りするためのシンプルなテストクライアントが含まれています。プロジェクトをビルドした後、次を実行します：

npm run test

または、直接実行します：

./test-mcp-client.js

これにより MCP サーバーが起動し、利用可能なツールをテストするための対話型メニューが表示されます。テストクライアントは、すべての操作でデフォルトのテストユーザー ID（test-user-123）を使用します。

クリーンアップと再ビルド

ビルドディレクトリをクリーンアップして、最初からビルドし直すには：

npm run rebuild

Claude と Cursor の設定

Claude の設定

Anthropic Console または API 経由でこの MCP サーバーを Claude と使用するには：

1. MCP サーバーをローカルで起動します：

   npm run start
   

2. Claude との会話を設定する際に、MCP 接続を設定します：

   {
   	"mcp_config": {
   		"transports": [
   			{
   				"type": "stdio",
   				"executable": {
   					"path": "/path/to/your/omi-mcp-local/dist/index.js",
   					"args": []
   				}
   			}
   		]
   	}
   }
   

3. Claude へのプロンプトの例：

   Please fetch the latest 5 conversations for user "user123" using the Omi API.
   

4. Claude は MCP を使用して read_omi_conversations ツールを実行します：

   {
   	"id": "req-1",
   	"type": "request",
   	"method": "tools.read_omi_conversations",
   	"params": {
   		"user_id": "user123",
   		"limit": 5
   	}
   }
   

Cursor の設定

Cursor でこの MCP サーバーを使用するには：

1. ターミナルで MCP サーバーを起動します：

   npm run start
   

2. Cursor で Settings > Extensions > MCP Servers に移動します

3. 次の設定で新しい MCP サーバーを追加します：

   • 名前：Omi API
   • URL：stdio:/path/to/your/omi-mcp-local/dist/index.js
   • サーバーを有効にする

4. これで Cursor 内で Omi ツールを直接使用できます。たとえば：

   @Omi API Please fetch memories for user "user123" and summarize them.
   

5. Cursor は MCP サーバーと通信して、必要な API 呼び出しを実行します。

利用可能なツール

MCP サーバーでは次のツールを利用できます：

read_omi_conversations

指定したユーザーの Omi の会話を取得します。フィルターは任意で指定できます。

パラメーター：

• user_id（string）：会話を取得するユーザー ID
• limit（number、任意）：返す会話の最大数
• offset（number、任意）：ページネーションでスキップする会話数
• include_discarded（boolean、任意）：破棄された会話を含めるかどうか
• statuses（string、任意）：会話を絞り込むステータスのカンマ区切りリスト

read_omi_memories

指定したユーザーの Omi のメモリーを取得します。

パラメーター：

• user_id（string）：メモリーを取得するユーザー ID
• limit（number、任意）：返すメモリーの最大数
• offset（number、任意）：ページネーションでスキップするメモリー数

create_omi_conversation

指定したユーザーの Omi に新しい会話を作成します。

パラメーター：

• text（string）：会話の全文
• user_id（string）：会話を作成するユーザー ID
• text_source（string）：テキストのソース（選択肢："audio_transcript"、"message"、"other_text"）
• started_at（string、任意）：会話／イベントの開始日時（ISO 8601 形式）
• finished_at（string、任意）：会話／イベントの終了日時（ISO 8601 形式）
• language（string、任意）：言語コード（デフォルト："en"）
• geolocation（object、任意）：会話の位置情報
  • latitude（number）：緯度座標
  • longitude（number）：経度座標
• text_source_spec（string、任意）：ソースに関する追加情報

create_omi_memories

特定のユーザーのために、Omi に新しいメモリーを作成します。

Parameters:

• user_id (string): メモリーを作成するユーザーの ID
• text (string, optional): メモリーの抽出元となるテキストコンテンツ
• memories (array, optional): 直接作成する明示的なメモリーオブジェクトの配列
  • content (string): メモリーの内容
  • tags (array of strings, optional): メモリーのタグ
• text_source (string, optional): テキストコンテンツのソース
• text_source_spec (string, optional): ソースに関する追加の指定

テスト

MCP サーバーをテストするには、付属のテストクライアントを使用できます。

node test-mcp-client.js

これにより、次の操作ができる対話型テストクライアントが起動します。

1. 会話を取得する
2. メモリーを取得する
3. 会話を作成する
4. 終了する

テストクライアントは、すべての操作にデフォルトのテストユーザー ID（test-user-123）を使用します。

ロギング

MCP サーバーには、コンソールとログファイルの両方に書き込む組み込みのロギング機能が含まれています。これは、サーバーの動作のデバッグや監視に役立ちます。

ログファイルの場所

ログは、プロジェクトディレクトリ内の logs/mcp-server.log に書き込まれます。ログファイルには、タイムスタンプと次の詳細情報が含まれます。

• サーバーの起動とシャットダウン
• すべての API リクエストとレスポンス
• エラーメッセージとスタックトレース
• Omi への API 呼び出し
• リクエストパラメーターとレスポンスデータ

ログの表示

tail コマンドを使用すると、ログをリアルタイムで表示できます。

tail -f logs/mcp-server.log

サーバーがリクエストを処理して Omi API とやり取りする際の更新をリアルタイムで確認できます。

ログ形式

各ログエントリーは次の形式に従います。

[2024-03-21T12:34:56.789Z] Log message here

タイムスタンプは ISO 8601 形式なので、イベントの関連付けや問題のデバッグが容易です。