neuronsearchlab

@neuronsearchlab/mcp

面向 NeuronSearchLab 的 MCP（Model Context Protocol）服务。让任何兼容 MCP 的 AI 客户端（Claude、Codex、Cursor、Windsurf 等）直接访问 NeuronSearchLab 的推荐、商品／内容搜索、目录操作、分析和平台控制功能。

"Get 5 recommendations for user [email protected]"
"Check my current plan and show which resources are over their limits"
"Create a new context called Twitter Feed"
"Add a pin rule so Nike items always appear in the top 3"
"Why did item prod-456 rank first for bob?"

有两种运行方式：

• 托管（推荐，无需安装）： https://console.neuronsearchlab.com/api/mcp — 通过 OAuth 登录或使用 NSL API 密钥的 Streamable HTTP。已在 MCP Registry 中登记为 com.neuronsearchlab/mcp（在注册表 API 或目录中搜索 neuronsearchlab）。
• 通过 npm 在本地使用 stdio： 使用 npx -y @neuronsearchlab/mcp，支持两种模式 — public（通过 OAuth 客户端凭据访问推荐、事件和目录）或 internal（通过控制台 API 密钥管理平台）。

---

连接到托管服务（无需安装）

托管端点运行的是一个适用于提交审核的客户管理配置。它提供一流工具，用于查看套餐和用量、配置排名、管理实验和训练、进行分析、检查目录、盘点和撤销 API 密钥、管理集成以及查看事件类型。每个托管工具都会声明其 OAuth 要求，并要求经过身份验证的团队具有 admin 作用域。凭据创建、账单变更以及任意平台 API 回退功能仅对可信的本地／内部客户端开放，以免在 ChatGPT 中暴露机密、购买操作和无限制的 API 调用。通过 OAuth 授权创建的密钥会显示在 控制台 → 安全 中，可随时在那里撤销。

claude.ai / Claude Desktop — 设置 → 连接器 → 添加自定义连接器 → 粘贴 https://console.neuronsearchlab.com/api/mcp → 连接，然后登录 NeuronSearchLab 控制台并批准所需作用域。

Claude Code

# OAuth (browser sign-in):
claude mcp add --transport http neuronsearchlab https://console.neuronsearchlab.com/api/mcp
# …or with an API key:
claude mcp add --transport http neuronsearchlab https://console.neuronsearchlab.com/api/mcp \
  --header "Authorization: Bearer nsl_your_key"

OpenAI Codex — 在 ~/.codex/config.toml 中：

[mcp_servers.neuronsearchlab]
url = "https://console.neuronsearchlab.com/api/mcp"
bearer_token_env_var = "NSL_API_KEY"

Cursor / Windsurf / 其他 Streamable HTTP 客户端

{
  "mcpServers": {
    "neuronsearchlab": {
      "url": "https://console.neuronsearchlab.com/api/mcp",
      "headers": { "Authorization": "Bearer nsl_your_key" }
    }
  }
}

---

资源

• 产品网站：https://www.neuronsearchlab.com
• MCP 设置指南：https://docs.neuronsearchlab.com/sdk/mcp
• 用于推荐操作的 AI Agent：https://www.neuronsearchlab.com/blog/ai-agents-for-recommendation-operations
• 推荐系统阅读路径：https://www.neuronsearchlab.com/blog/recommendation-systems

工具

API 工具

工具	描述
get_recommendations	获取用户的个性化推荐
get_auto_recommendations	自动分区并支持分页的内容流（无限滚动）
track_event	记录用户互动（点击、浏览、购买等）
upsert_item	添加或更新目录条目
patch_item	部分更新条目（启用／停用、更改字段）
delete_items	从目录中永久移除条目
search_items	按关键词搜索目录
explain_ranking	说明某个条目为何在用户的排名中位于该位置

模式

公共模式

使用 OAuth 客户端凭据和公共 API。

支持：

• 推荐
• 事件
• 目录操作

内部模式

使用具有 admin 范围的 NeuronSearchLab API 密钥访问控制台 API。

目前支持：

• 账户套餐和限额：get_account_plan 返回生效套餐、已解析限额、当前用量和准确超额情况
• 目录搜索和排序调试：search_items、explain_ranking
• 上下文：list_contexts、create_context、update_context、delete_context、get_context
• 流水线：list_pipelines、create_pipeline、update_pipeline、delete_pipeline、activate_pipeline、deactivate_pipeline、clone_pipeline、get_pipeline
• 规则：list_rules、create_rule、update_rule、delete_rule、toggle_rule、enable_rule、disable_rule、get_rule
• 分群：list_segments、get_segment、create_segment、update_segment、delete_segment
• 实验：list_experiments、get_experiment、create_experiment、update_experiment、start_experiment、stop_experiment、get_experiment_results、refresh_experiment_results
• 训练：list_training_jobs、get_training_job、create_training_job、cancel_training_job
• 分析：get_ranking_metrics、get_user_analytics、get_item_analytics、compare_items、top_items
• 事件类型：list_event_types、create_event_type、update_event_type、delete_event_type
• 凭据和集成：list_api_keys、revoke_api_key、list_integrations（create_api_key 仅限本地／内部使用，因为它会返回凭据材料）
• 仅供可信本地／内部客户端使用的备用 UI 覆盖：list_platform_routes、call_platform_api

---

快速入门（本地 stdio）

1. 获取凭据

从 NeuronSearchLab 控制台生成 SDK 凭据（OAuth 2.0 客户端 ID + 密钥）。

2. 添加到 Claude Desktop

公共模式（推荐、事件、目录）：

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "neuronsearchlab": {
      "command": "npx",
      "args": ["-y", "@neuronsearchlab/mcp"],
      "env": {
        "NSL_CLIENT_ID": "your-client-id",
        "NSL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

内部模式（管理平台 — 上下文、流水线、规则、分析等）：

{
  "mcpServers": {
    "neuronsearchlab": {
      "command": "npx",
      "args": ["-y", "@neuronsearchlab/mcp"],
      "env": {
        "NSL_PLATFORM_MODE": "internal",
        "NSL_API_KEY": "your-admin-api-key"
      }
    }
  }
}

重启 Claude Desktop。连接后，你会在工具栏中看到 🔌 neuronsearchlab 指示标记。

试用：recommendation-ops 演示

连接后，在将服务接入更大的工作流之前，先运行此命名演示路径。它可以验证 AI 客户端能够将推荐系统作为调查界面来操作，而不只是调用推荐端点。

1. 列出上下文，让助手确认即将检查的确切范围。
2. 获取推荐结果，使用已知测试用户和上下文。
3. 搜索目录，输入具体的产品／内容词组，并将返回的项目 ID 与推荐结果集进行比较。
4. 解释一个排序项目：如果推荐或搜索响应中有 request_id，请使用它。
5. **可选，仅限沙盒：**在解释结果显示出预期泄漏后，起草或切换一条规则。除非操作员明确批准写入，否则请将生产环境上下文保持为只读。

Use the NeuronSearchLab MCP server in read-only mode first.
List my recommendation contexts and choose the homepage-feed context.
Get 10 recommendations for user [email protected] using context homepage-feed.
Search the catalogue for waterproof jackets and show the top 5 item ids.
Explain why the first recommended item ranked first, using the request_id from the recommendation response if available.
If you see a relevance leak, draft the smallest rule that would fix it, but do not create or toggle the rule yet.

内部／管理模式还可以在进行更改前检查运行状态：

List ranking rules for the homepage-feed context.
Show the latest ranking metrics for that context.
Compare item jacket-123 with item jacket-456 and explain which rule or signal separates them.

冒烟测试后的后续步骤：

• 为客户端或 MCP 服务创建一个范围受限的 API 密钥
• 连接一个真实的推荐上下文，例如 homepage-feed
• 在评估排序质量之前，为点击／浏览事件添加请求归因

3. Cursor／其他 MCP 客户端

请遵循你的客户端的 MCP 服务指南。命令如下：

npx @neuronsearchlab/mcp

公共模式请设置 NSL_CLIENT_ID + NSL_CLIENT_SECRET，内部模式请设置 NSL_PLATFORM_MODE=internal + NSL_API_KEY。

---

发布

此仓库使用 Changesets 和 GitHub Actions 自动管理版本并发布到 npm。

• 对任何面向用户的包变更，使用 npm run changeset 添加 changeset
• 将该 PR 合并到 main
• release.yml 工作流会创建或更新版本 PR
• 合并版本 PR 后，@neuronsearchlab/mcp 会自动发布到 npm

要启用可信发布，请在 npmjs.com 上配置该包，信任此仓库中的 release.yml 工作流。

---

配置

所有配置均通过环境变量进行：

变量	必需	默认值	描述
NSL_PLATFORM_MODE	否	public	public 或 internal
NSL_CLIENT_ID	公共模式	—	从控制台获取的 OAuth 客户端 ID
NSL_CLIENT_SECRET	公共模式	—	从控制台获取的 OAuth 客户端密钥
NSL_API_KEY	内部模式	—	具有 admin 范围的 API 密钥
NSL_TOKEN_URL	否	https://auth.neuronsearchlab.com/oauth2/token	令牌端点
NSL_API_BASE_URL	否	公共模式下为 https://api.neuronsearchlab.com，内部模式下为 https://console.neuronsearchlab.com	API 基础 URL
NSL_TIMEOUT_MS	否	15000	请求超时时间，单位为毫秒

---

工具参考

get_recommendations

获取面向用户的个性化推荐。返回带有评分的排序条目，以及用于归因的 request_id。

输入

字段	类型	必需	描述
user_id	string	是	用户标识符（UUID、电子邮件或任意稳定字符串）
context_id	正整数	否	在控制台中创建上下文时生成的上下文 ID
limit	整数 1–200	否	返回的条目数量（默认为上下文值，通常为 20）
surface	string	否	重排界面覆盖值（例如 "homepage"、"sidebar"）

示例

Get 10 recommendations for user [email protected] using context 101

---

get_auto_recommendations

获取用户信息流中下一个自动生成的板块。此工具专为无限滚动设计，每次调用都会返回一个精选板块（例如 "本周热门"、"为你推荐的新内容"），以及用于获取下一板块的游标。持续调用，直到 done: true。

输入

字段	类型	必需	描述
user_id	string	是	用户标识符
context_id	正整数	否	可选的控制台生成的上下文 ID
limit	整数 1–200	否	每个板块的条目数
cursor	string	否	上一次响应中的分页游标
window_days	整数	否	回溯查找“新”内容的天数

---

track_event

记录用户互动。务必传入推荐响应中的 request_id，以启用点击归因。

输入

字段	类型	必需	描述
event_id	整数	是	管理控制台中的数字事件类型 ID
user_id	string	是	触发事件的用户
item_id	正整数	是	由 NSL 生成、通过摄取返回的条目 ID
request_id	string	否	推荐响应中的 request_id（用于归因）
session_id	string	否	用于归集一次访问期间事件的会话标识符

---

upsert_item

在目录中添加或更新条目。description 字段用于生成嵌入向量，因此内容应丰富且具有描述性。

输入

字段	类型	必需	描述
name	string	是	显示名称
description	string	是	用于生成嵌入向量的详细描述
metadata	object	否	随推荐一同返回的任意键值对

条目 ID 由 NSL 生成，并在摄取响应中返回；调用方无法自行提供。

---

patch_item

部分更新现有目录条目。

输入

字段	类型	必填	描述
item_id	正整数	是	要更新的 NSL 生成的条目 ID
active	布尔值	否	设为 false 可将条目从推荐中排除，而不删除

---

delete_items

永久移除条目。**此操作无法撤销。**如需临时排除，请使用 patch_item 并将 active 设为 false。

输入

字段	类型	必填	描述
item_ids	正整数数组（最多 100 个）	是	要删除的 NSL 生成的条目 ID

---

search_items

按关键词搜索目录。

输入

字段	类型	必填	描述
query	字符串	是	要搜索的文本
limit	整数 1–100	否	结果数量上限（默认值为 20）

---

explain_ranking

说明特定条目对某位用户排名在指定位置的原因。返回分数细分、应用的规则和流水线跟踪信息。

输入

字段	类型	必填	描述
item_id	正整数	是	要说明排名原因的 NSL 生成的条目 ID
user_id	字符串	否	用于评分的用户（省略则使用中性基准）
context_id	正整数	否	要应用其评分规则的 Console 生成的上下文 ID

---

list_contexts

列出为团队配置的所有推荐上下文（信息流）。

输入 — 无

---

create_context

创建新的推荐上下文。

输入

字段	类型	必填	描述
context_name	字符串	是	显示名称（例如 "Twitter Feed"）
context_key	字符串	否	URL 安全键（根据名称自动生成）
context_type	枚举	否	homepage_feed、you_may_also_like、item_detail_related、search_assist、campaign_merchandising。默认值：homepage_feed
description	字符串	否	可选描述
recommendation_type	枚举	否	item_to_item、item_to_user、user_to_item、user_to_user。默认值：user_to_item

示例

Create a new context called "Twitter Feed" with type homepage_feed

---

update_context

更新现有上下文。

输入

字段	类型	必填	描述
context_id	整数	是	要更新的上下文 ID
context_name	字符串	否	新显示名称
context_type	枚举	否	新上下文类型
description	字符串	否	新描述
recommendation_type	枚举	否	新推荐类型

---

delete_context

永久删除上下文及其关联的流水线、规则和信息流蓝图。

输入

字段	类型	必填	描述
context_id	整数	是	要删除的上下文 ID

---

list_pipelines

列出所有排名流水线。

输入 — 无

---

create_pipeline

创建包含默认阶段的新排名流水线。

输入

字段	类型	必填	描述
name	字符串	是	流水线名称
description	字符串	否	可选描述
context_id	整数	否	要关联此流水线的上下文
is_active	布尔值	否	默认值：true

---

update_pipeline / delete_pipeline

按 pipeline_id 更新或删除流水线。

---

list_rules

列出排名规则；可选择按 context_id 筛选。

create_rule

创建排名规则。规则类型：

类型	效果
boost	提高匹配项的分数（使用 weight 1.0–5.0）
bury	降低匹配项的分数（使用 weight 0.0–1.0）
pin	将匹配项固定在指定位置（使用 pin_position）
filter	从结果中移除匹配项
cap	将匹配项限制为结果的一定比例（使用 cap_fraction）
diversity	按某个字段的值分散展示项目（使用 diversity_field、diversity_max）

输入

字段	类型	必填	描述
name	string	是	规则显示名称
rule_type	enum	是	boost、bury、pin、filter、cap、diversity
conditions	array	是	[{ field, operator, value }] — 项目必须匹配所有条件
actions	object	是	{ type, weight?, pin_position?, cap_fraction?, ... }
context_id	integer	否	将规则限定到特定上下文
description	string	否	可选描述
priority	integer 0–1000	否	数值越高，越先评估。默认值：100

示例

Create a pin rule called "Pin Nike" that pins items where brand equals "Nike" to position 3, scoped to context 1

---

update_rule / delete_rule / toggle_rule / enable_rule / disable_rule

通过 rule_id 更新、删除或启用／停用规则。

---

get_user_analytics

获取特定用户的展示次数、事件细分、独立项目活动和点击率。

输入

字段	类型	必填	描述
user_id	string	是	要检查的用户 ID 或电子邮件地址
context_id	positive integer	否	限定到控制台生成的上下文
window	1d | 7d | 30d | 90d	否	时间范围（默认值 7d）

---

get_item_analytics

获取特定项目的展示次数、事件细分、观看／点击次数和点击率。

输入

字段	类型	必填	描述
item_id	positive integer	是	要检查的 NSL 生成的项目 ID
context_id	positive integer	否	限定到控制台生成的上下文
window	1d | 7d | 30d | 90d	否	时间范围（默认值 7d）

---

compare_items

在相同时间范围内，比较两个项目的展示次数、事件、点击次数和点击率。

输入

字段	类型	必填	描述
item_a_id	positive integer	是	第一个 NSL 生成的项目 ID
item_b_id	positive integer	是	第二个 NSL 生成的项目 ID
context_id	positive integer	否	限定到控制台生成的上下文
window	1d | 7d | 30d | 90d	否	时间范围（默认值 7d）

---

top_items

按展示次数或指定时间范围内匹配的事件活动列出排名靠前的项目。对于泛指“热门项目”或“表现最佳”的问题，请使用 metric="served"。当用户明确指定互动信号（例如观看、点击、购买）时，请使用 metric="events"。

输入

字段	类型	必填	描述
metric	served | events	否	按展示次数或事件次数排名（默认值 served）
event_name	string	否	当 metric=events 时的事件名称筛选条件（例如 "watch"、"click"）
event_id	integer	否	当 metric=events 时的数值事件 ID 筛选条件
context_id	positive integer	否	限定到控制台生成的上下文
window	1d | 7d | 30d | 90d	否	时间范围（默认值 7d）
limit	integer 1–50	否	最多返回的项目数（默认值 10）

示例

What's the top item served in the last 7 days?
Which items had the most watch events last month?

---

身份验证

公共模式使用 OAuth 2.0 Client Credentials。令牌会在启动时获取、缓存于内存中，并在过期前 60 秒自动刷新。

内部模式使用具有 admin 范围的 NeuronSearchLab API 密钥。设置 NSL_API_KEY 和 NSL_PLATFORM_MODE=internal。

---

开发

git clone https://github.com/NeuronSearchLab/mcp
cd mcp
npm install
export NSL_CLIENT_ID=your-client-id
export NSL_CLIENT_SECRET=your-client-secret
npm run dev           # dev mode (tsx, no build)
npm run build         # compile to dist/

---

许可证

MIT