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?"

実行方法は 2 つあります。

• ホスト型（推奨、インストール不要）： https://console.neuronsearchlab.com/api/mcp — Streamable HTTP を使用し、OAuth サインインまたは NSL API キーで認証します。MCP Registry には com.neuronsearchlab/mcp として登録されています（レジストリの API またはディレクトリで neuronsearchlab を検索してください）。
• npm 経由のローカル stdio： npx -y @neuronsearchlab/mcp を 2 つのモードで実行できます。public（OAuth クライアント認証情報によるレコメンデーション、イベント、カタログ）または internal（コンソール API キーによる管理プラットフォーム）です。

---

ホスト型サーバーに接続する（インストール不要）

ホスト型エンドポイントは、提出に適した顧客管理プロファイルで実行されます。プランと使用状況の確認、ランキング設定、実験、トレーニング、分析、カタログの調査、API キーの一覧表示と失効、インテグレーション、イベントタイプに対応する専用ツールを備えています。ホスト型の各ツールは OAuth の要件を明示し、認証済みチームの admin スコープを必要とします。ChatGPT でシークレット、購入、制限のない API 呼び出しが公開されないように、認証情報の作成、課金に関する変更、任意のプラットフォーム API へのフォールバックは、信頼されたローカル／内部クライアントのみで利用できます。OAuth の同意を通じて発行されたキーは、console → Security に表示され、いつでもそこで失効できます。

claude.ai / Claude Desktop — Settings → Connectors → Add custom connector → https://console.neuronsearchlab.com/api/mcp を貼り付け → Connect を選択し、NeutronSearchLab コンソールにサインインしてスコープを承認します。

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 エージェント：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	ユーザーに対して項目がその順位になった理由を説明します

モード

Public モード

OAuth クライアント認証情報と公開 API を使用します。

対応内容：

• レコメンデーション
• イベント
• カタログ操作

Internal モード

コンソール API に対して、admin スコープの NeuronSearchLab 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 に追加する

Public モード（レコメンデーション、イベント、カタログ）：

~/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"
      }
    }
  }
}

Internal モード（管理プラットフォーム — コンテキスト、パイプライン、ルール、分析など）：

{
  "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 がある場合は、それを使ってランキングされた項目を 1 つ説明します。
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.

Internal／管理モードでは、変更を加える前に運用状態を確認することもできます。

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

Public モードでは NSL_CLIENT_ID + NSL_CLIENT_SECRET を設定し、Internal モードでは 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	positive integer	いいえ	コンソールでコンテキストを作成したときに生成されたコンテキスト ID
limit	integer 1–200	いいえ	返すアイテム数（デフォルトはコンテキストの値で、通常は 20）
surface	string	いいえ	再ランキング対象のサーフェスの上書き値（例："homepage"、"sidebar"）

例

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

---

get_auto_recommendations

ユーザーのフィード向けに自動生成された次のセクションを取得します。無限スクロール用に設計されており、呼び出すたびに、次のセクション用のカーソルとともに、キュレーションされたセクション（例：「今週のトレンド」、「あなたへの新着」）を 1 つ返します。done: true になるまで呼び出します。

入力

フィールド	型	必須	説明
user_id	string	はい	ユーザー識別子
context_id	positive integer	いいえ	任意の、コンソールで生成されたコンテキスト ID
limit	integer 1–200	いいえ	セクションあたりのアイテム数
cursor	string	いいえ	前回のレスポンスで返されたページネーションカーソル
window_days	integer	いいえ	「新着」コンテンツを検索する過去の日数

---

track_event

ユーザーの操作を記録します。クリックアトリビューションを有効にするため、おすすめのレスポンスから取得した request_id を必ず渡してください。

入力

フィールド	型	必須	説明
event_id	integer	はい	管理コンソールで指定された数値のイベントタイプ ID
user_id	string	はい	イベントを発生させたユーザー
item_id	positive integer	はい	取り込み処理で返された NSL 生成のアイテム ID
request_id	string	いいえ	おすすめのレスポンスから取得した request_id（アトリビューション用）
session_id	string	いいえ	1 回の訪問内のイベントをグループ化するためのセッション識別子

---

upsert_item

カタログにアイテムを追加または更新します。description フィールドは埋め込みの生成に使用されるため、情報豊かで詳しい内容にしてください。

入力

フィールド	型	必須	説明
name	string	はい	表示名
description	string	はい	埋め込み生成用の詳細な説明
metadata	object	いいえ	おすすめとともに返される任意のキーと値のペア

アイテム ID は NSL によって生成され、取り込みレスポンスで返されます。呼び出し側から指定することはできません。

---

patch_item

既存のカタログアイテムを部分的に更新します。

入力

フィールド	型	必須	説明
item_id	正の整数	はい	更新する NSL 生成のアイテム ID
active	ブール値	いいえ	削除せずにおすすめから除外するには false を指定します

---

delete_items

アイテムを完全に削除します。元に戻すことはできません。 一時的に除外するには、active: false を指定して patch_item を使用してください。

入力

フィールド	型	必須	説明
item_ids	正の整数[]（最大 100）	はい	削除する NSL 生成のアイテム ID

---

search_items

キーワードでカタログを検索します。

入力

フィールド	型	必須	説明
query	文字列	はい	検索するテキスト
limit	整数 1～100	いいえ	結果の最大数（デフォルトは 20）

---

explain_ranking

特定のアイテムが、あるユーザーに対して指定された順位になった理由を説明します。スコアの内訳、適用されたルール、パイプラインのトレースを返します。

入力

フィールド	型	必須	説明
item_id	正の整数	はい	説明する NSL 生成のアイテム ID
user_id	文字列	いいえ	スコアを算出する対象のユーザー（中立的なベースラインを使用する場合は省略）
context_id	正の整数	いいえ	スコアリングルールの適用元となるコンソール生成のコンテキスト 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

ランキングルールを作成します。ルールの種類は次のとおりです。

Type	Effect
boost	条件に一致するアイテムのスコアを上げます（weight に 1.0～5.0 を指定）
bury	条件に一致するアイテムのスコアを下げます（weight に 0.0～1.0 を指定）
pin	条件に一致するアイテムを特定の位置に固定します（pin_position を使用）
filter	条件に一致するアイテムを結果から除外します
cap	条件に一致するアイテムの割合を結果内で制限します（cap_fraction を使用）
diversity	フィールドの値ごとにアイテムを分散させます（diversity_field、diversity_max を使用）

入力

Field	Type	Required	Description
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

特定のユーザーについて、配信数、イベントの内訳、ユニークアイテムのアクティビティ、クリック率を取得します。

入力

Field	Type	Required	Description
user_id	string	はい	調査するユーザー ID またはメールアドレス
context_id	positive integer	いいえ	コンソールで生成されたコンテキストに範囲を限定します
window	1d | 7d | 30d | 90d	いいえ	期間（デフォルトは 7d）

---

get_item_analytics

特定のアイテムについて、配信数、イベントの内訳、視聴数／クリック数、クリック率を取得します。

入力

Field	Type	Required	Description
item_id	positive integer	はい	調査する NSL 生成アイテム ID
context_id	positive integer	いいえ	コンソールで生成されたコンテキストに範囲を限定します
window	1d | 7d | 30d | 90d	いいえ	期間（デフォルトは 7d）

---

compare_items

同じ期間における配信数、イベント、クリック数、クリック率を使って、2 つのアイテムを直接比較します。

入力

Field	Type	Required	Description
item_a_id	positive integer	はい	1 つ目の NSL 生成アイテム ID
item_b_id	positive integer	はい	2 つ目の NSL 生成アイテム ID
context_id	positive integer	いいえ	コンソールで生成されたコンテキストに範囲を限定します
window	1d | 7d | 30d | 90d	いいえ	期間（デフォルトは 7d）

---

top_items

期間内の配信数、または条件に一致するイベントのアクティビティに基づいて、上位のアイテムを一覧表示します。一般的な「上位アイテム」や「最も成果の高いアイテム」に関する質問には、metric="served" を使用します。ユーザーが視聴やクリック、購入などのエンゲージメント指標を明示した場合は、metric="events" を使用します。

入力

Field	Type	Required	Description
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