algolia-mcp

Algolia 搜索与分析

**需要写入或修改数据？**请改用 algolia-cli——它可以处理导入、导出、备份、设置更改、同义词、规则、API 密钥以及所有管理操作。

连接设置

使用 /algolia-mcp:mcp-connect 配置 MCP 客户端，以连接 Algolia MCP 服务。 如需手动设置客户端，请参阅 connection-setup。

工具选择

搜索

任务	工具
搜索索引	algolia_search_index
列出可用索引	algolia_search_list_indices
探索 facet 值	algolia_search_for_facet_values

分析

任务	工具
热门搜索	algolia_analytics_top_searches
无结果的搜索	algolia_analytics_searches_no_results
无结果率	algolia_analytics_no_results_rate
点击位置	algolia_analytics_click_positions
无点击率	algolia_analytics_no_click_rate
无点击的搜索	algolia_analytics_top_searches_without_clicks
搜索量	algolia_analytics_number_of_searches
热门搜索结果	algolia_analytics_top_search_results
独立用户数	algolia_analytics_number_of_users
热门筛选器	algolia_analytics_top_filters
无结果的筛选器	algolia_analytics_top_filters_no_results
热门国家	algolia_analytics_top_countries

推荐

任务	工具	model 参数
经常一起购买	algolia_recommendations	bought-together
相关产品	algolia_recommendations	related-products
趋势商品	algolia_recommendations	trending-items
趋势 facet	algolia_recommendations	trending-facets
外观相似商品	algolia_recommendations	looking-similar

搜索筛选语法

筛选条件与 query 一起传入 algolia_search_index 调用：

facetFilters（基于数组）：

[["color:red", "color:blue"]]              → OR (red OR blue)
[["brand:Nike"], ["category:running"]]     → AND (Nike AND running)
[["size:10"], ["color:red", "color:blue"]] → mixed (size 10 AND (red OR blue))

每个内部数组中的条件按 OR 组合；外层数组按 AND 组合。

numericFilters（基于字符串）：

["price < 100"]                    → single condition
["price >= 50", "price <= 200"]    → range (AND'd)

日期筛选：日期必须以 Unix 时间戳存储。使用 numericFilters: ["timestamp >= 1704067200"]。

属性选择：使用 attributesToRetrieve: ["name", "price"] 限制响应大小。

分析关键说明

• clickAnalytics: true：在 algolia_analytics_top_searches 或 algolia_analytics_top_search_results 上设置此项，以包含点击率、转化率和点击次数。只有这两个工具支持此项。
• revenueAnalytics: true：在相同工具上设置此项，还可包含加购率、购买率和收入。
• 数据延迟：近期数据的处理延迟为 1–4 小时。为获得完整数据，请使用结束时间至少早于当前时间 4 小时的日期范围。

结果解读

无结果率	评估
< 5%	极佳
5–10%	良好
10–20%	需要改进
> 20%	较差

点击位置：健康情况 = 30–40% 的点击发生在位置 1，之后逐步下降至位置 10。分布均匀 = 相关性较差。点击集中在位置 5–10 = 排名存在问题。

点击率低 + 搜索量高 = 搜索结果相关性较差。常见原因：缺少同义词、内容缺失、查询意图不匹配。

推荐阈值

阈值	行为
50	结果更多，相关性较低
60	平衡（良好的默认值）
75	结果更少，相关性较高

模型参数要求：

• bought-together、related-products、looking-similar → 需要 objectID
• trending-items → 不需要 objectID。使用 facetName + facetValue 按类别筛选
• trending-facets → 需要 facetName

必需工作流

1. 先发现：始终先调用 algolia_search_list_indices，再调用其他工具，以获取 applicationId 和 indexName。applicationId 参数是枚举值——请从工具架构中的值中选择，切勿猜测。
2. 索引名称区分大小写：使用 algolia_search_list_indices 返回的准确名称。
3. 日期参数：分析工具接受 YYYY-MM-DD 格式的 startDate 和 endDate。默认时段为最近 8 天。
4. 权限：并非所有用户都能使用所有工具。分析工具需要 Analytics 权限；推荐功能需要 Recommend 功能。

常见工作流

搜索质量审查

1. algolia_search_list_indices → 获取 applicationId 和索引名称
2. algolia_analytics_no_results_rate → 检查整体状况（低于 5% 表示表现出色）
3. algolia_analytics_searches_no_results → 查找具体的失败查询
4. 使用 clickAnalytics: true 调用 algolia_analytics_top_searches → 找出搜索量高但点击率低的查询
5. algolia_analytics_click_positions → 检查点击是否集中在第 1 位（良好），还是分布均匀（相关性较差）
6. 针对每个有问题的查询：使用该查询调用 algolia_search_index，查看返回结果

推荐配置检查

1. algolia_search_list_indices → 获取 applicationId
2. 从 trending-items 开始（所需数据最少），验证 Recommend 是否正常工作
3. 然后使用已知产品的 objectID 尝试 bought-together 或 related-products
4. 如果结果为空，请查看推荐参考文档中的事件量要求

参考文档

• 连接设置 — MCP 服务配置与身份验证
• 搜索 — 搜索参数、筛选语法（facetFilters、numericFilters）、分页
• 分析 — 分析指标解读、日期范围、点击/转化跟踪
• 推荐 — 推荐模型、阈值、基于 facet 的筛选
• 故障排查 — 常见错误及解决步骤