mcp-meilisearch

MCP Meilisearch API サーバー

AI モデルと Meilisearch 検索エンジン間の橋渡しとなるモデル コンテキスト プロトコル (MCP) サーバー実装。

概要

• MCP サーバー: モデル コンテキスト プロトコルを使用するツールとして Meilisearch API を公開します。
• Web クライアント デモ: 検索機能を紹介するデモ インターフェイス。
• AI 推論: ユーザーのクエリに基づいたインテリジェントなツール選択。

主な特徴

• 複数のトランスポート オプション: STDIO トランスポートと StreamableHTTP トランスポートの両方をサポートします。
• Meilisearch API サポート: Meilisearch 機能へのフルアクセス。
• Web クライアント デモ: 検索機能と特徴を紹介する更新されたインターフェイス。
• AI 推論: OpenAIo HuggingFace などのプロバイダーの LLM を活用して、ユーザーのクエリに最適なツールをインテリジェントに決定して利用します。

はじめる

前提条件

• Node.js v20 以上。
• 実行中の Meilisearch インスタンス (ローカルまたはリモート)。
• Meilisearch の API キー (必要な場合)。
• AI プロバイダー API キー (AI 推論を使用している場合)。

インストール

パッケージをインストールします。

オプション

Meilisearch 接続オプション

• meilisearchHost : MeilisearchインスタンスのURL（デフォルト: " http://localhost:7700 "）
• meilisearchApiKey : Meilisearch で認証するための API キー (デフォルト: "")

MCP サーバー オプション

• transport : MCPサーバーのトランスポートタイプ（"http" | "stdio"）（デフォルト: "http"）
• httpPort : MCP サーバーの HTTP ポート (デフォルト: 4995)
• mcpEndpoint : MCPエンドポイントパス（デフォルト: "/mcp"）

セッションオプション

• sessionTimeout : セッションタイムアウト（ミリ秒）（デフォルト: 3600000）
• sessionCleanupInterval : セッションクリーンアップ間隔（ミリ秒）（デフォルト: 60000）

AI推論オプション

• aiProviderName : AIプロバイダーの名前（"openai" | "huggingface" | "openrouter" | "ollama"）（デフォルト: "openai"）
• aiProviderApiKey : AI推論用のAIプロバイダーAPIキー
• llmModel : 使用するAIモデル（デフォルト: "gpt-3.5-turbo"）

このパッケージで適切なAI推論を行うには関数呼び出しが必要ですが、すべてのモデルが関数呼び出しをサポートしているわけではないことにご注意ください。toolsパラメータをサポートするモデルを選択してください。

サーバー設定例

MCPClientの使用

パッケージは、クライアント側の統合のために MCPClient クラスをエクスポートします。

AI推論クライアントメソッド

callToolWithAI(query, options)

AI を通じてユーザークエリを処理し、最も適切なツールを決定して実行します。

パラメータ:

• query : 文字列 - 処理されるユーザーのクエリまたはリクエスト
• options : オブジェクト（オプション） - 設定オプション
  • specificTools : String[] (オプション) - ツールの選択をこのツール名のリストに制限します
  • justReasoning : ブール値（オプション） - trueに設定すると、選択したツールを実行せずに AI の推論のみを返します。

サーバーの起動

プログラムでサーバーを起動できます:

ツール

MCPサーバーは、Meilisearchの機能と連携するための様々なツールを公開しています。各ツールは特定のMeilisearch APIエンドポイントに対応しており、検索、インデックス作成、ドキュメント管理などの操作を実行できます。

ツールカテゴリ

1. システム ツール: ヘルス チェック、バージョン情報、サーバー統計。
2. インデックス ツール: インデックスを管理します (作成、更新、削除、一覧表示)。
3. ドキュメント ツール: ドキュメントを追加、更新、削除、取得します。
4. 検索ツール: ベクター検索を含む高度な検索。
5. 設定ツール: インデックス設定を構成します。
6. タスク ツール: 非同期タスクを管理します。
7. ベクター ツール: 実験的なベクター検索機能。

システムツール

健康

• 説明: Meilisearch サーバーが正常かどうかを確認します。

バージョン

• 説明: Meilisearch サーバーのバージョン情報を取得します。

情報

• 説明: Meilisearch サーバーのシステム情報を取得します。

統計

• 説明: すべてのインデックスまたは特定のインデックスに関する統計を取得します。
• パラメータ:
  • indexUid (文字列、オプション): インデックスの一意の識別子。

タスクを取得

• 説明: オプションのフィルタリングを使用してタスクに関する情報を取得します。
• パラメータ:
  • limit (数値、オプション): 返されるタスクの最大数。
  • from (数値、オプション): フェッチを開始するタスク UID。
  • status (文字列、オプション): 返されるタスクのステータス。
  • type (文字列、オプション): 返されるタスクのタイプ。
  • indexUids (string[], オプション): タスクが実行されたインデックスのUID。

タスクの削除

• 説明: 指定されたフィルターに基づいてタスクを削除します。
• パラメータ:
  • statuses (string[], オプション): 削除するタスクのステータス。
  • types (文字列[], オプション): 削除するタスクの種類。
  • indexUids (文字列[]、オプション): 削除するタスクが実行されたインデックスのUID。
  • uids (number[], オプション): 削除するタスクのUID。
  • canceledBy (number[], オプション): 削除するタスクをキャンセルしたタスクの UID。
  • beforeUid (数値、オプション): この値より前の uid を持つタスクを削除します。
  • beforeStartedAt (文字列、オプション): この日付より前に処理を開始したタスクを削除します (ISO 8601 形式)。
  • beforeFinishedAt (文字列、オプション): この日付より前に処理が完了したタスクを削除します (ISO 8601 形式)。

インデックスツール

リストインデックス

• 説明: Meilisearch インスタンス内のすべてのインデックスを一覧表示します。
• パラメータ:
  • limit (数値、オプション): 返されるインデックスの最大数。
  • offset (数値、オプション): スキップするインデックスの数。

インデックス取得

• 説明: 特定の Meilisearch インデックスに関する情報を取得します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。

インデックス作成

• 説明: 新しい Meilisearch インデックスを作成します。
• パラメータ:
  • indexUid (文字列、必須): 新しいインデックスの一意の識別子。
  • primaryKey (文字列、オプション): インデックスの主キー。

インデックス更新

• 説明: Meilisearch インデックスを更新します (現在は主キーの更新のみをサポートしています)。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • primaryKey (文字列、必須): インデックスの新しい主キー。

インデックス削除

• 説明: Meilisearch インデックスを削除します。
• パラメータ:
  • indexUid (文字列、必須): 削除するインデックスの一意の識別子。

スワップインデックス

• 説明: Meilisearch 内の 2 つ以上のインデックスを交換します。
• パラメータ:
  • indexes (文字列、必須): 交換するインデックス ペアの JSON 配列 (例: [["movies", "movies_new"]])。

ドキュメントツール

ドキュメントの取得

• 説明: Meilisearch インデックスからドキュメントを取得します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • limit (数値、オプション): 返されるドキュメントの最大数 (デフォルト: 20)。
  • offset (数値、オプション): スキップするドキュメントの数 (デフォルト: 0)。
  • fields (string[], オプション): ドキュメントで返されるフィールド。
  • filter (文字列、オプション): 適用するフィルタークエリ。

ドキュメントの取得

• 説明: Meilisearch インデックスから ID でドキュメントを取得します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • documentId (文字列、必須): 取得するドキュメントの ID。
  • fields (string[], オプション): ドキュメントで返されるフィールド。

ドキュメントの追加

• 説明: Meilisearch インデックスにドキュメントを追加します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • documents (文字列、必須): 追加するドキュメントの JSON 配列。
  • primaryKey (文字列、オプション): ドキュメントの主キー。

ドキュメントの更新

• 説明: Meilisearch インデックス内のドキュメントを更新します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • documents (文字列、必須): 更新するドキュメントの JSON 配列。
  • primaryKey (文字列、オプション): ドキュメントの主キー。

ドキュメントの削除

• 説明: Meilisearch インデックスから ID によってドキュメントを削除します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • documentId (文字列、必須): 削除するドキュメントの ID。

ドキュメントの削除

• 説明: Meilisearch インデックスから ID によって複数のドキュメントを削除します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • documentIds (文字列、必須): 削除するドキュメント ID の JSON 配列。

すべてのドキュメントを削除

• 説明: Meilisearch インデックス内のすべてのドキュメントを削除します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。

検索ツール

検索

• 説明: Meilisearch インデックス内のドキュメントを検索します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • q (文字列、必須): 検索クエリ。
  • limit (数値、オプション): 返される結果の最大数 (デフォルト: 20)。
  • offset (数値、オプション): スキップする結果の数 (デフォルト: 0)。
  • filter (文字列、オプション): 適用するフィルタークエリ。
  • sort (string[], オプション): 並べ替えの基準となる属性。例: ["price"]。
  • facets (string[], オプション): 返されるファセット。
  • attributesToRetrieve (文字列[]、オプション): 結果に含める属性。
  • attributesToCrop (string[], オプション): 切り取る属性。
  • cropLength (数値、オプション): 切り取られた属性を切り取る長さ。
  • attributesToHighlight (string[], オプション): 強調表示する属性。
  • highlightPreTag (文字列、オプション): 強調表示されたテキストの前に挿入するタグ。
  • highlightPostTag (文字列、オプション): 強調表示されたテキストの後に挿入するタグ。
  • showMatchesPosition (ブール値、オプション): 結果に一致位置を含めるかどうか。
  • matchingStrategy (文字列、オプション): マッチング戦略: 'all' または 'last'。

マルチ検索

• 説明: 1 つのリクエストで複数の検索を実行します。
• パラメータ:
  • queries (文字列、必須): 検索クエリの JSON 配列。各クエリにはsearchツールと同じパラメータが含まれます。

グローバル検索

• 説明: 利用可能なすべての Meilisearch インデックスで用語を検索し、結合された結果を返します。
• パラメータ:
  • q (文字列、必須): 検索クエリ。
  • limit (数値、オプション): インデックスごとに返される結果の最大数 (デフォルト: 20)。
  • attributesToRetrieve (文字列[]、オプション): 結果に含める属性。

ファセット検索

• 説明: 特定の条件に一致するファセット値を検索します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • facetName (文字列、必須): 検索するファセットの名前。
  • facetQuery (文字列、オプション): ファセット値と一致するクエリ。
  • filter (文字列、オプション): 基本検索に適用するフィルター。

設定ツール

設定を取得する

• 説明: Meilisearch インデックスのすべての設定を取得します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。

設定の更新

• 説明: Meilisearch インデックスの設定を更新します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • settings (文字列、必須): 更新する設定を含む JSON オブジェクト。

設定をリセットする

• 説明: Meilisearch インデックスのすべての設定をデフォルト値にリセットします。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。

設定ツールを取得する

次のツールは、Meilisearch インデックスの特定の設定を取得します。

• 表示属性を取得する
• 検索可能な属性を取得する
• フィルタ可能な属性を取得する
• ソート可能な属性を取得する
• ランキングルールを取得する
• ストップワードを取得する
• 同義語の取得
• タイプミス許容度を取得する
• ページネーションの取得
• ファセットを取得する
• 辞書を取得
• 近接精度の取得
• 区切りトークンを取得する
• 区切り文字のないトークンを取得する
• 単語辞書を取得する

これらのツールにはすべて同じパラメータがあります。

• indexUid (文字列、必須): インデックスの一意の識別子。

設定ツールの更新

次のツールは、Meilisearch インデックスの特定の設定を更新します。

• 表示属性の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • displayedAttributes (文字列、必須): 表示する属性の JSON 配列 (例: ["title", "description"])。
• 検索可能な属性の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • searchableAttributes (文字列、必須): 検索できる属性の JSON 配列 (例: ["title", "description"])。
• フィルタ可能な属性の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • filterableAttributes (文字列、必須): フィルターとして使用できる属性の JSON 配列 (例: ["genre", "director"])。
• ソート可能な属性の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • sortableAttributes (文字列、必須): 並べ替えに使用できる属性の JSON 配列 (例: ["price", "date"])。
• ランキングルールの更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • rankingRules (文字列、必須): ランキングルールの JSON 配列 (例: ["typo", "words", "proximity", "attribute", "sort", "exactness"])。
• ストップワードの更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • stopWords (文字列、必須): 検索クエリで無視する単語の JSON 配列 (例: ["the", "a", "an"])。
• 同義語の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • synonyms （文字列、必須）：単語を同義語にマッピングする JSON オブジェクト（例：{"movie": ["film"]}）。
• 更新タイプミス許容度
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • typoTolerance (文字列、必須): タイプミス許容設定を含む JSON オブジェクト (例: {"enabled": true, "minWordSizeForTypos": {"oneTypo": 5, "twoTypos": 9}})。
• ページネーションの更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • pagination (文字列、必須): ページネーション設定を含む JSON オブジェクト (例: {"maxTotalHits": 1000})。
• ファセット更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • faceting (文字列、必須): ファセット構成を含む JSON オブジェクト (例: {"maxValuesPerFacet": 100})。
• 辞書の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • dictionary (文字列、必須): 単一の単語として扱う単語の JSON 配列、例: ["San Francisco", "New York"]。
• 近接精度の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • proximityPrecision (文字列、必須): 近接精度値を持つ文字列。'byWord' または 'byAttribute' を指定できます。
• 区切りトークンの更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • separatorTokens (文字列、必須): 単語区切りとして考慮されるトークンの JSON 配列 (例: ["-", "_"])。
• 区切り文字のないトークンの更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • nonSeparatorTokens (文字列、必須): 単語区切りとして考慮されないトークンの JSON 配列 (例: ["@", "."])。
• 単語辞書の更新
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • wordDictionary (文字列、必須): 辞書に追加するカスタム単語の JSON 配列 (例: ["cbuilder", "meilisearch"])。

設定ツールをリセット

次のツールは、Meilisearch インデックスの特定の設定をデフォルト値にリセットします。

• 表示属性をリセットする
• 検索可能な属性をリセットする
• フィルタ可能な属性をリセットする
• ソート可能な属性をリセットする
• ランキングルールのリセット
• ストップワードのリセット
• 同義語のリセット
• タイプミス許容度をリセットする
• ページ区切りのリセット
• リセットファセット
• 辞書をリセットする
• 近接精度のリセット
• 区切りトークンのリセット
• 非区切りトークンのリセット
• 単語辞書をリセットする

これらのリセット ツールにはすべて同じパラメーターがあります。

• indexUid (文字列、必須): インデックスの一意の識別子。

タスクツール

リストタスク

• 説明: オプションのフィルタリングを使用してタスクを一覧表示します。
• パラメータ:
  • limit (数値、オプション): 返されるタスクの最大数。
  • from (数値、オプション): フェッチを開始するタスク UID。
  • statuses (string[], オプション): 返されるタスクのステータス。
  • types (string[], オプション): 返されるタスクの種類。
  • indexUids (string[], オプション): タスクが実行されたインデックスのUID。
  • uids (number[], オプション): 返される特定のタスクのUID。

タスク取得

• 説明: 特定のタスクに関する情報を取得します。
• パラメータ:
  • taskUid (数値、必須): タスクの一意の識別子。

タスクをキャンセル

• 説明: 提供されたフィルターに基づいてタスクをキャンセルします。
• パラメータ:
  • statuses (string[], オプション): キャンセルするタスクのステータス。
  • types (文字列[], オプション): キャンセルするタスクの種類。
  • indexUids (文字列[]、オプション): キャンセルするタスクが実行されたインデックスのUID。
  • uids (number[], オプション): キャンセルするタスクのUID。

タスク待ち

• 説明: 特定のタスクが完了するまで待機します。
• パラメータ:
  • taskUid (数値、必須): 待機するタスクの一意の識別子。
  • timeoutMs (数値、オプション): 待機する最大時間 (ミリ秒) (デフォルト: 5000)。
  • intervalMs (数値、オプション): ポーリング間隔（ミリ秒単位）（デフォルト: 500）。

ベクターツール

ベクトル検索を有効にする

• 説明: Meilisearch のベクトル検索実験機能を有効にします。

実験的な機能を取得する

• 説明: Meilisearch の実験的な機能のステータスを取得します。

アップデート埋め込み

• 説明: ベクトル検索用の埋め込みを設定します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • embedders (文字列、必須): 埋め込み設定を含む JSON オブジェクト。

埋め込みを取得する

• 説明: インデックスの埋め込み構成を取得します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。

リセット埋め込み

• 説明: インデックスの埋め込み設定をリセットします。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。

ベクトル検索

• 説明: Meilisearch インデックスでベクトル検索を実行します。
• パラメータ:
  • indexUid (文字列、必須): インデックスの一意の識別子。
  • vector (文字列、必須): 検索するベクトルを表す JSON 配列。
  • limit (数値、オプション): 返される結果の最大数 (デフォルト: 20)。
  • offset (数値、オプション): スキップする結果の数 (デフォルト: 0)。
  • filter (文字列、オプション): 適用するフィルター (例: 'genre = horror AND year > 2020')。
  • embedder (文字列、オプション): 使用する埋め込み元の名前 (省略する場合は、「ベクトル」を指定する必要があります)。
  • attributes (文字列[]、オプション): ベクトル検索に含める属性。
  • query (文字列、オプション): 検索するテキストクエリ (「vector」ではなく「embedder」を使用する場合)。
  • hybrid (ブール値、オプション): ハイブリッド検索 (ベクター検索とテキスト検索の組み合わせ) を実行するかどうか。
  • hybridRatio (数値、オプション): ハイブリッド検索におけるベクトル検索とテキスト検索の比率 (0-1、デフォルト: 0.5)。