@neuronsearchlab/mcp

MCP (Model Context Protocol) server for NeuronSearchLab. Gives any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.) direct access to your recommendation engine — no HTTP wrangling, no token management, just natural language.

"Get 5 recommendations for user alice@example.com"
"Why did item prod-456 rank first for bob?"
"Add a new product to the catalogue — ID: prod-123, name: Running Shoes..."
"Track a click event for alice on item prod-123 from request abc-xyz"

Tools

Quickstart

1. Get credentials

Generate SDK Credentials (OAuth 2.0 client ID + secret) from the NeuronSearchLab console.

2. Add to Claude Desktop

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

Restart Claude Desktop. You'll see a 🔌 neuronsearchlab indicator in the toolbar when it's connected.

3. Cursor / other MCP clients

Follow your client's MCP server guide. The command is:

npx @neuronsearchlab/mcp

Set env vars NSL_CLIENT_ID and NSL_CLIENT_SECRET.

Configuration

All configuration is via environment variables:

Tool reference

get_recommendations

Fetch personalised recommendations for a user. Returns ranked items with scores and a request_id for attribution.

Inputs

Example

Get 10 recommendations for user alice@example.com using context homepage-feed

Response format

✅ 10 recommendation(s) for user:
   request_id: ae5ef21b-077a-416f-96af-55d1f99e0bf0  ← pass to track_event
   processing_time: 220ms

1. [prod-123] Running Shoes (score: 0.8741)
   Lightweight trail running shoes with breathable mesh upper...
   metadata: { category="footwear", price=89.99 }
2. [prod-456] Trail Jacket (score: 0.8612)
   ...

get_auto_recommendations

Fetch the next auto-generated section for a user's feed. Designed for infinite-scroll — each call returns one curated section (e.g. "Trending this week", "New for you") plus a cursor for the next section. Call until done: true.

Inputs

Example

Get the next section of the feed for user bob, continuing from cursor eyJ2IjoxL...

track_event

Record a user interaction. Always pass request_id from the recommendations response to enable click-through attribution — it's what closes the feedback loop and improves personalisation.

Event IDs are configured in the admin console under Events.

Inputs

Example

Track a click event — user alice clicked item prod-123 from recommendation request ae5ef21b-077a

upsert_item

Add or update an item in the catalogue. The description field is used to generate the embedding — write it to be rich and descriptive to improve match quality.

Inputs

Example

Add an item — ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890, name: "Trail Running Shoes",
description: "Lightweight trail running shoes with breathable mesh upper, responsive foam
midsole, and Vibram outsole. Ideal for 5K to marathon distances on technical terrain.",
metadata: { category: "footwear", price: 129.99, brand: "Salomon" }

💡 Tip: The richer the description, the better the embedding — include category, attributes, use-case, and audience alongside the product copy.

patch_item

Partially update an existing catalogue item. Most commonly used to enable or disable items without re-uploading the full entry.

Inputs

Example

Disable item prod-123 — set active to false

delete_items

Permanently remove items from the catalogue. Cannot be undone. To temporarily exclude items, use patch_item with active: false.

Inputs

Example

Delete items prod-999 and prod-998 from the catalogue

search_items

Search the catalogue by keyword. Returns item IDs, names, descriptions, and status.

Inputs

Example

Search the catalogue for "running shoes"

explain_ranking

Explain why a specific item was ranked at a given position for a user. Returns a score breakdown, applied rules, and a pipeline trace.

Inputs

Example

Why did item prod-456 rank first for user bob@example.com?

Response format

📊 Ranking explanation for item: prod-456
   User: bob@example.com

Final score: 0.9124

─── Score breakdown ───
  embedding_similarity: 0.8741
  rule_boost: 0.0383

─── Applied rules ───
  ✅ matched  Category boost (boost)
  ⬜ no match Recent purchase filter (filter)

─── Pipeline trace ───
  ✅ candidate_retrieval: passed
  ✅ embedding_score: passed
  ✅ rule_engine: passed
  ✅ rerank: passed

Authentication

The server uses OAuth 2.0 Client Credentials — no user login required. Tokens are fetched automatically on startup, cached in memory, and refreshed 60 seconds before expiry. Concurrent refresh calls are deduplicated (a single in-flight request is shared).

If authentication fails on startup, the server exits immediately with a clear error message — no silent failures.

Development

git clone https://github.com/NeuronSearchLab/mcp
cd mcp
npm install

Set credentials:

export NSL_CLIENT_ID=your-client-id
export NSL_CLIENT_SECRET=your-client-secret

Run in dev mode (tsx, no build step):

npm run dev

Build:

npm run build          # compiles TypeScript to dist/
node dist/index.js     # run the built server

Test results

See docs/test-results.md for live test output against the production API.

License

MIT