mcp-meilisearch

MCP 美丽搜索 API 服务器

模型上下文协议 (MCP) 服务器实现，在 AI 模型和 Meilisearch 搜索引擎之间架起桥梁。

概述

• 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)

通过人工智能处理用户查询以确定并执行最合适的工具。

参数：

• query ：String - 要处理的用户查询或请求
• options ：对象（可选）- 配置选项
  • specificTools ：String[] (可选) - 将工具选择限制为此工具名称列表
  • justReasoning ：布尔值（可选） - 设置为true时，仅返回 AI 的推理而不执行所选工具

启动服务器

您可以通过编程方式启动服务器：

工具

MCP 服务器提供了各种工具，方便您与 Meilisearch 功能进行交互。每个工具都对应一个特定的 Meilisearch API 端点，方便您执行搜索、索引和管理文档等操作。

工具类别

1. 系统工具：健康检查、版本信息、服务器统计。
2. 索引工具：管理索引（创建、更新、删除、列出）。
3. 文档工具：添加、更新、删除和检索文档。
4. 搜索工具：高级搜索，包括矢量搜索。
5. 设置工具：配置索引设置。
6. 任务工具：管理异步任务。
7. 矢量工具：实验性的矢量搜索功能。

系统工具

健康

• 描述：检查Meilisearch服务器是否健康。

版本

• 描述：获取美丽搜索服务器的版本信息。

信息

• 描述：获取美丽搜索服务器的系统信息。

统计数据

• 描述：获取有关所有索引或特定索引的统计信息。
• 参数：
  • indexUid （字符串，可选）：索引的唯一标识符。

获取任务

• 描述：通过可选过滤获取有关任务的信息。
• 参数：
  • limit （数字，可选）：要返回的最大任务数。
  • from （数字，可选）：从中开始获取的任务 uid。
  • status （字符串，可选）：要返回的任务状态。
  • type （字符串，可选）：要返回的任务类型。
  • indexUids （string[]，可选）：执行任务的索引的 UID。

删除任务

• 描述：根据提供的过滤器删除任务。
• 参数：
  • statuses （string[]，可选）：要删除的任务的状态。
  • types （string[]，可选）：要删除的任务类型。
  • indexUids （string[]，可选）：执行删除任务的索引的 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 中交换两个或多个索引。
• 参数：
  • 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 （string[]，可选）：要包含在结果中的属性。
  • attributesToCrop （string[]，可选）：要裁剪的属性。
  • cropLength （数字，可选）：裁剪属性的长度。
  • attributesToHighlight （string[]，可选）：要突出显示的属性。
  • highlightPreTag （字符串，可选）：在突出显示的文本之前插入的标签。
  • highlightPostTag （字符串，可选）：在突出显示的文本后插入的标签。
  • showMatchesPosition （布尔值，可选）：是否在结果中包含匹配位置。
  • matchingStrategy （字符串，可选）：匹配策略：“全部”或“最后”。

多重搜索

• 描述：在一次请求中执行多个搜索。
• 参数：
  • queries （字符串，必需）：搜索查询的 JSON 数组，每个查询包含与search工具相同的参数。

全局搜索

• 描述：在所有可用的 Meilisearch 索引中搜索某个术语并返回组合结果。
• 参数：
  • q （字符串，必需）：搜索查询。
  • limit （数字，可选）：每个索引返回的最大结果数（默认值：20）。
  • attributesToRetrieve （string[]，可选）：要包含在结果中的属性。

方面搜索

• 描述：搜索符合特定条件的方面值。
• 参数：
  • 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 （字符串，必需）：具有 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 （string[]，可选）：要取消的任务类型。
  • indexUids （string[]，可选）：执行要取消的任务的索引的 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 （字符串，可选）：要应用的过滤器（例如，“类型 = 恐怖 AND 年份 > 2020”）。
  • embedder （字符串，可选）：要使用的嵌入器的名称（如果省略，则必须提供“向量”）。
  • attributes （string[]，可选）：包含在向量搜索中的属性。
  • query （字符串，可选）：要搜索的文本查询（如果使用“嵌入器”而不是“向量”）。
  • hybrid （布尔值，可选）：是否执行混合搜索（结合向量和文本搜索）。
  • hybridRatio （数字，可选）：混合搜索中向量与文本搜索的比例（0-1，默认值：0.5）。