@likyly/mcp-server 0.0.0-stage → 0.4.1

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# @likyly/mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets your AI coding assistant (Claude Code, Cursor, VS Code, Codex, Claude Desktop…) set up
+[LIKYLY](https://likyly.com) recommendations on your site for you.
+
+[LIKYLY](https://likyly.com) shows each visitor the products they are most likely to want ("You may
+also like", "Recommended for you"), learned from what visitors do on your site. With this server, you
+ask your assistant in plain words and it does the work:
+
+- **connect your catalog**: Shopify, a REST API, a CSV, a webhook, or products pushed from your code;
+- **create a placement**: where recommendations appear and how ("4 related products on the product
+  page, exclude out-of-stock");
+- **integrate it into your code** from a recipe written for your stack;
+- **check it works**, from LIKYLY's own data: recommendations served, impressions and clicks received.
+
+The quickest way to install it is the wizard, which also installs the SDK and writes your key:
+
+```sh
+npx @likyly/wizard
+```
+
+## Which key
+
+The API decides what a key can do, not the server:
+
+- **Public key** (`pk_…`): recommendations and events only. Safe anywhere.
+- **Developer key** (`lk_…`, recommended for assistants) or secret key (`sk_…`): also the admin tools
+  (catalog sources, placements, cache). Keep it on your machine or in server-side config, never in
+  browser code.
+
+Without a developer or secret key, the admin tools answer with a clear 401/403; nothing breaks.
+
+## Install
+
+```bash
+npm install -g @likyly/mcp-server
+```
+
+## Configure
+
+**Recommendations/events only** (e.g. Claude Desktop's `claude_desktop_config.json`, or a
+browser-facing use case) - a public key:
+
+```json
+{
+  "mcpServers": {
+    "likyly": {
+      "command": "likyly-mcp-server",
+      "env": {
+        "LIKYLY_API_KEY": "your-restricted-public-key",
+        "LIKYLY_BASE_URL": "https://api.likyly.com",
+        "LIKYLY_PRODUCT_TYPE": "your-catalog-namespace"
+      }
+    }
+  }
+}
+```
+
+**The easy way: `npx @likyly/wizard`** (or `npx @likyly/wizard mcp add`). It signs you in on
+likyly.com, gets a developer key, stores it in `.likyly/credentials.env` (a folder that ignores
+itself in git, readable by you only) and writes `.mcp.json` / `.cursor/mcp.json` /
+`.vscode/mcp.json` **without any key in them**: they reference `LIKYLY_DEVELOPER_KEY`, and when
+that variable is not exported the server reads the key from the credentials file
+(`LIKYLY_ENV_FILE` to point elsewhere; by default `.likyly/credentials.env` in the folder it
+starts in).
+
+**By hand, Claude Code / Codex, with data-source admin tools** - first create a developer key (once,
+from a server-side shell - never from a browser):
+
+```bash
+curl -X POST https://api.likyly.com/clients/me/developer-keys \
+  -H "Authorization: Bearer <your Supabase session JWT>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Claude Code", "scopes": ["sources:read", "sources:write", "placements:read", "placements:write"]}'
+# -> {"key": "...", ...} - copy `key`, it is shown once
+```
+
+Then point `.mcp.json` (or `claude_desktop_config.json`) at it:
+
+```json
+{
+  "mcpServers": {
+    "likyly": {
+      "command": "likyly-mcp-server",
+      "env": {
+        "LIKYLY_API_KEY": "your-developer-key",
+        "LIKYLY_BASE_URL": "https://api.likyly.com"
+      }
+    }
+  }
+}
+```
+
+`LIKYLY_PRODUCT_TYPE` is optional - set it if you only manage one catalog, so prompts don't need
+to repeat it; every recommendation/event tool also accepts `product_type` per-call to override
+it (the admin tools target a data source's own `product_type`, set at `create_data_source`).
+
+## Tools
+
+Recommendations/events - work with the public key:
+
+| Tool | Maps to |
+|---|---|
+| `get_recommendations` | `POST /getRec` - LIKYLY picks the strategy; returns a `recommendation_id` |
+| `get_popular_recommendations` | `GET /getRec/popular/{count}` |
+| `get_cold_start_recommendations` | `GET /getRec/content/{item_id}/{count}` |
+| `get_collaborative_recommendations` | `GET /getRec/collaborative/{user_id}/{count}` |
+| `get_hybrid_recommendations` | `GET /getRec/hybrid/{user_id}/{item_id}/{count}` |
+| `get_session_recommendations` | `GET /getRec/session` |
+| `get_user_session_recommendations` | `GET /getRec/sessionForUser/{user_id}/{count}` |
+| `track_event` | `POST /events/{event_type}` (impression, view, click, add_to_cart, remove_from_cart, purchase, ...) |
+
+Admin - data source integrations - need the secret key or a developer key with `sources:read`/
+`sources:write` (see [`docs/data-sources.md`](https://github.com/Likyly/likyly-recsys/blob/main/docs/data-sources.md) for the full
+architecture, source types and config shapes):
+
+| Tool | Maps to |
+|---|---|
+| `list_source_types` | `GET /data-sources/types` |
+| `create_data_source` | `POST /data-sources` |
+| `test_data_source` | `POST /data-sources/{id}/test` |
+| `preview_data_source` | `POST /data-sources/{id}/preview` |
+| `configure_field_mapping` | `PUT /data-sources/{id}/field-mapping` (or the `/dry-run` variant, with `dry_run: true`) |
+| `sync_data_source` | `POST /data-sources/{id}/sync` |
+| `get_sync_status` | `GET /data-sources/{id}/syncs` |
+| `list_data_sources` | `GET /data-sources` |
+| `get_catalog_stats` | `GET /data-sources/{id}/stats` |
+| `update_data_source` | `PATCH /data-sources/{id}` - fix an outdated source rather than create another (Free: one source) |
+| `delete_data_source` | `DELETE /data-sources/{id}` - items already imported stay |
+| `push_items` | `POST /data-sources/{id}/push` (with the source's `X-Push-Secret`) - load a catalog LIKYLY cannot reach (localhost, VPN): the agent reads the products from the project and pushes them |
+| `rotate_push_secret` | `POST /data-sources/{id}/push-secret/rotate` |
+
+Admin - placements (the recommended way to wire up recommendations - see
+[`docs/placements.md`](https://github.com/Likyly/likyly-recsys/blob/main/docs/placements.md)) - need the secret key or a developer key
+with `placements:read`/`placements:write`:
+
+| Tool | Maps to |
+|---|---|
+| `list_placements` | `GET /placements` |
+| `get_placement` | `GET /placements/{slug}` |
+| `create_placement` | `POST /placements` |
+| `update_placement` | `PATCH /placements/{slug}` |
+| `delete_or_disable_placement` | `POST /placements/{slug}/deactivate` (default) or `DELETE /placements/{slug}` |
+| `preview_placement` | `POST /placements/{slug}/preview` |
+| `get_placement_requirements` | `GET /placements/{slug}/requirements` |
+| `purge_recommendation_cache` | `POST /placements/{slug}/cache/purge`, or `POST /placements/cache/purge` for all - empties the anonymous recommendation cache (see docs/placements.md, "Caching") |
+
+Admin - integration recipe & validator (writing and verifying the client-side integration -
+see [`docs/getting-started.md`](https://github.com/Likyly/likyly-recsys/blob/main/docs/getting-started.md)) - same `placements:read`/
+`placements:write` requirement:
+
+| Tool | Maps to |
+|---|---|
+| `get_integration_recipe` | Composed from `GET /placements/{slug}/requirements` + `.../tracking-requirements` - not a new endpoint |
+| `get_tracking_requirements` | `GET /placements/{slug}/tracking-requirements` |
+| `validate_integration` | `GET /placements/{slug}/health`, rendered as a ✓/⚠/✗ checklist with next steps |
+| `get_placement_health` | `GET /placements/{slug}/health` (structured data, no rendering) |
+| `get_recent_integration_events` | `GET /placements/{slug}/recent-events` |
+| `get_model_overview` | `GET /models/overview` - trained versions (which one is live, precision@10) and production performance per engine; read-only, `placements:read` |
+
+The runtime call, `POST /placements/{slug}/recommend`, is **not an MCP tool** - it's a plain
+HTTP call the site's own code makes, safe with the public key, exactly like `POST /getRec`.
+
+## Hosted service (connect any LLM by URL)
+
+Besides the local stdio server above, the same tools can run as a hosted **Streamable HTTP**
+service, so an MCP-capable LLM client connects with a URL instead of running a local process:
+
+```bash
+npm run build
+PORT=3200 npm run start:http      # POST /mcp, GET /health
+```
+
+Each request carries the caller's own key (public, secret, or developer) - the service stores
+no secrets and forwards it as-is to the LIKYLY API, so it can never do more than the key itself
+allows. Only send a secret or developer key over this path from a trusted server-side caller,
+same as anywhere else - never from browser-facing code:
+
+```
+POST https://mcp.likyly.com/mcp
+Authorization: Bearer <public-secret-or-developer-key>
+X-Likyly-Product-Type: <catalog-namespace>     # optional default catalog, recommendation/event tools only
+```
+
+Deploy on the droplet next to the API (Docker + Caddy):
+
+```bash
+docker build -t likyly-mcp sdk/mcp && docker run -d --restart=always -p 127.0.0.1:3200:3200 likyly-mcp
+```
+
+```caddyfile
+mcp.likyly.com {
+    reverse_proxy 127.0.0.1:3200
+}
+```
+
+Env: `PORT` (default 3200), `LIKYLY_BASE_URL` (default `https://api.likyly.com`). Stateless mode:
+no sessions, `GET /mcp` returns 405.
+
+## Develop locally
+
+```bash
+npm install
+npm run build
+node dist/index.js   # reads LIKYLY_API_KEY / LIKYLY_BASE_URL / LIKYLY_PRODUCT_TYPE from env
+```

package/dist/admin-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LikylyClient } from "./client.js";
+export declare function createLikylyAdminTools(server: McpServer, client: LikylyClient): void;

package/dist/admin-tools.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+// Admin tools: configuring and running data-source integrations (Shopify, a REST API, a
+// CSV, a webhook, ...) - real, tenant-scoped configuration changes, not documentation. They
+// need the secret key or a developer key carrying the matching scope (sources:read /
+// sources:write - see /clients/me/developer-keys in the recsys API), never the restricted
+// public key: whatever LIKYLY_API_KEY this server was started with is forwarded as-is, and
+// the API itself is what enforces the scope - a caller using the wrong key gets a clear
+// 401/403 back through the tool result, exactly like every other tool here.
+//
+// A typical flow: list_source_types -> create_data_source -> test_data_source ->
+// preview_data_source -> configure_field_mapping -> sync_data_source -> get_sync_status /
+// get_catalog_stats. Each tool below states which step(s) of that flow it is.
+export function createLikylyAdminTools(server, client) {
+    function textResult(data) {
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    const dataSourceId = z.number().int().describe("The data source's id, from create_data_source or list_data_sources.");
+    server.tool("list_source_types", "Step 1: every catalog source type LIKYLY can connect to (csv_upload, csv_url, json_url, rest_api, shopify, woocommerce, webhook) - each entry says whether it needs credentials and whether it supports incremental sync. Call this before create_data_source to pick the right `type` and know what `config`/`credentials` it expects (see docs/data-sources.md for each type's exact shape).", {}, async () => textResult(await client.listSourceTypes()));
+    server.tool("create_data_source", "Step 2: register a new catalog integration for this account. Doesn't fetch or write anything yet - it just saves the configuration. `product_type` is the catalog namespace it will write into (an existing one, or a new name to start a new catalog). `config` holds non-secret settings (e.g. {base_url, items_path} for rest_api, {shop_domain} for shopify); `credentials` holds secrets (e.g. {access_token} for shopify) and is encrypted at rest, never returned afterwards. Omit `sync_mode` to get the type's default. For a push-mode type (woocommerce, webhook) the response includes a one-time `push_secret` for the upstream system's webhook - save it, it can't be retrieved again. Call test_data_source next.", {
+        name: z.string().min(1).max(200),
+        type: z.string().describe("One of list_source_types' ids, e.g. 'shopify', 'rest_api', 'csv_url'."),
+        product_type: z.string().min(1).max(64).regex(/^[a-zA-Z0-9_-]+$/).describe("The catalog namespace this source writes into."),
+        config: z.record(z.unknown()).optional(),
+        credentials: z.record(z.unknown()).optional().describe("Secrets - access tokens, API keys. Encrypted at rest."),
+        field_mapping: z.record(z.unknown()).optional().describe("Can be set later via configure_field_mapping instead."),
+        sync_mode: z.enum(["full", "incremental"]).optional(),
+    }, async (input) => textResult(await client.createDataSource(input)));
+    server.tool("update_data_source", "Change an existing data source instead of creating another one (the Free plan allows a single source): its name, `config` (merged shallowly: send only the keys that change, e.g. a new base_url), `credentials` (fully replaced) or `product_type`. Use it when a source points at an old URL or catalog. Run test_data_source afterwards.", {
+        data_source_id: dataSourceId,
+        name: z.string().min(1).max(200).optional(),
+        product_type: z.string().min(1).max(64).regex(/^[a-zA-Z0-9_-]+$/).optional(),
+        config: z.record(z.unknown()).optional(),
+        credentials: z.record(z.unknown()).optional(),
+        sync_mode: z.enum(["full", "incremental"]).optional(),
+    }, async ({ data_source_id, ...input }) => textResult(await client.updateDataSource(data_source_id, input)));
+    server.tool("delete_data_source", "Delete a data source's configuration and sync history - catalog items it already wrote stay in place. Frees the slot on plans limited to one source. Irreversible: confirm with the developer first, and prefer update_data_source when the source only needs a new URL or catalog.", { data_source_id: dataSourceId }, async ({ data_source_id }) => textResult(await client.deleteDataSource(data_source_id)));
+    server.tool("push_items", "Send catalog items to a push-mode source (type 'webhook'), up to 1000 per call. This is the way to load a catalog LIKYLY cannot fetch - a site on localhost, behind a VPN, or data only in the codebase: read the products from the project (API route, JSON, database seed), map them to item objects, push them. `push_secret` comes from create_data_source's response (shown once) or rotate_push_secret. `deleted_ids` removes items.", {
+        data_source_id: dataSourceId,
+        push_secret: z.string().min(1),
+        items: z.array(z.record(z.unknown())).max(1000),
+        deleted_ids: z.array(z.string()).max(1000).optional(),
+    }, async ({ data_source_id, push_secret, items, deleted_ids }) => textResult(await client.pushItems(data_source_id, push_secret, items, deleted_ids)));
+    server.tool("rotate_push_secret", "Issue a new push secret for a push-mode source (the old one stops working) - use it when the secret from create_data_source was lost, then call push_items with the new one.", { data_source_id: dataSourceId }, async ({ data_source_id }) => textResult(await client.rotatePushSecret(data_source_id)));
+    server.tool("test_data_source", "Step 3: validates that this source's credentials/config actually reach it - never writes any catalog data. Always returns ok:true/false with a message (never throws for a bad connection), so you can report exactly why a connection failed.", { data_source_id: dataSourceId }, async ({ data_source_id }) => textResult(await client.testDataSource(data_source_id)));
+    server.tool("preview_data_source", "Step 4: fetches a small sample from the source (never writes to the catalog) and returns detected_fields plus a best-effort suggested_mapping - the starting point for configure_field_mapping. Call this before mapping fields, especially for a source type you haven't configured before.", { data_source_id: dataSourceId, limit: z.number().int().min(1).max(50).default(10) }, async ({ data_source_id, limit }) => textResult(await client.previewDataSource(data_source_id, limit)));
+    server.tool("configure_field_mapping", "Step 5: sets how this source's raw records map to a Likyly item. `mapping.external_id` and `mapping.title` are required; `description`, `category`, `price`, `image`, `url`, `stock`, `updated_at` are optional; `attributes` is itself {name: path} for anything else to keep as free-form properties. Each value is a field name or a dotted/bracket path into a nested record (e.g. 'variants[0].price', 'images[0].src') - start from preview_data_source's suggested_mapping. Pass dry_run:true to see the mapping's effect on a fresh sample WITHOUT saving it (use this to iterate); dry_run:false (the default) persists it for sync_data_source to use.", {
+        data_source_id: dataSourceId,
+        mapping: z.record(z.unknown()).describe("e.g. {external_id: 'id', title: 'name', price: 'variants[0].price', image: 'images[0].src', category: 'product_type', stock: 'variants[0].inventory_quantity'}"),
+        dry_run: z.boolean().default(false).describe("true: preview the effect without saving. false: save it."),
+    }, async ({ data_source_id, mapping, dry_run }) => textResult(dry_run ? await client.dryRunFieldMapping(data_source_id, mapping) : await client.saveFieldMapping(data_source_id, mapping)));
+    server.tool("sync_data_source", "Step 6: runs a sync now (queued as a background job, so this returns almost immediately with the run's status - poll get_sync_status for completion). `mode` defaults to incremental (falls back to full automatically if the source doesn't support incremental); use mode:'full' explicitly for the first sync or to re-baseline. Not applicable to push-mode sources (woocommerce, webhook) - those sync automatically whenever the upstream system pushes; check get_sync_status/get_catalog_stats for their activity instead.", { data_source_id: dataSourceId, mode: z.enum(["full", "incremental"]).default("incremental") }, async ({ data_source_id, mode }) => textResult(await client.syncDataSource(data_source_id, mode)));
+    server.tool("get_sync_status", "Step 7: the most recent sync attempts for this source - status (running/success/partial/failed), items fetched/upserted/deleted/failed, and any error. Poll this right after sync_data_source until status is no longer 'running'. Also the right call to check on a push-mode source's activity.", { data_source_id: dataSourceId, limit: z.number().int().min(1).max(100).default(5) }, async ({ data_source_id, limit }) => textResult(await client.listSyncs(data_source_id, limit)));
+    server.tool("list_data_sources", "Every data source configured for this account, with its type, status, and last sync time - use this to check what already exists before creating a duplicate, or to find a data_source_id by name.", {}, async () => textResult(await client.listDataSources()));
+    server.tool("get_catalog_stats", "Item count and last-write time for a source's target catalog, plus its latest sync run - what you need to report back to the user after a sync (\"X items synced, Y rejected, next sync at ...\").", { data_source_id: dataSourceId }, async ({ data_source_id }) => textResult(await client.getCatalogStats(data_source_id)));
+}

package/dist/client.d.ts

@@ -0,0 +1,74 @@
+export interface LikylyClientOptions {
+    baseUrl: string;
+    apiKey: string;
+}
+export declare class LikylyClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(options: LikylyClientOptions);
+    /** The recommendation call: LIKYLY picks the strategy. */
+    getRecommendations(productType: string, request: {
+        user_id?: string;
+        session_id?: string;
+        item_id?: string;
+        viewed_item_ids?: string[];
+        placement?: string;
+        count?: number;
+    }): Promise<any>;
+    getColdStartRecs(productType: string, itemId: string, count?: number): Promise<any>;
+    getPopularRecs(productType: string, count?: number): Promise<any>;
+    getUserRecs(productType: string, userId: string, count?: number): Promise<any>;
+    getHybridRecs(productType: string, userId: string, itemId: string, count?: number, alpha?: number): Promise<any>;
+    getSessionRecs(productType: string, viewedItemIds: string[], count?: number): Promise<any>;
+    getUserSessionRecs(productType: string, userId: string, count?: number): Promise<any>;
+    listSourceTypes(): Promise<any>;
+    createDataSource(input: {
+        name: string;
+        type: string;
+        product_type: string;
+        config?: Record<string, unknown>;
+        credentials?: Record<string, unknown>;
+        field_mapping?: Record<string, unknown>;
+        sync_mode?: string;
+    }): Promise<any>;
+    listDataSources(): Promise<any>;
+    getDataSource(dataSourceId: number): Promise<any>;
+    updateDataSource(dataSourceId: number, input: Record<string, unknown>): Promise<any>;
+    deleteDataSource(dataSourceId: number): Promise<any>;
+    /** Push-mode sources (webhook, woocommerce): authenticated by the source's push secret. */
+    pushItems(dataSourceId: number, pushSecret: string, items: Record<string, unknown>[], deletedIds?: string[]): Promise<any>;
+    rotatePushSecret(dataSourceId: number): Promise<any>;
+    testDataSource(dataSourceId: number): Promise<any>;
+    previewDataSource(dataSourceId: number, limit?: number): Promise<any>;
+    dryRunFieldMapping(dataSourceId: number, mapping: Record<string, unknown>, limit?: number): Promise<any>;
+    saveFieldMapping(dataSourceId: number, mapping: Record<string, unknown>): Promise<any>;
+    syncDataSource(dataSourceId: number, mode?: string): Promise<any>;
+    listSyncs(dataSourceId: number, limit?: number): Promise<any>;
+    getCatalogStats(dataSourceId: number): Promise<any>;
+    listPlacements(): Promise<any>;
+    createPlacement(input: Record<string, unknown>): Promise<any>;
+    getPlacement(slug: string): Promise<any>;
+    updatePlacement(slug: string, input: Record<string, unknown>): Promise<any>;
+    deactivatePlacement(slug: string): Promise<any>;
+    deletePlacement(slug: string): Promise<any>;
+    purgeRecommendationCache(slug?: string): Promise<any>;
+    getPlacementRequirements(slug: string): Promise<any>;
+    previewPlacement(slug: string, context: Record<string, unknown>, limit?: number): Promise<any>;
+    getTrackingRequirements(slug: string): Promise<any>;
+    getPlacementHealth(slug: string, windowHours?: number): Promise<any>;
+    /** Read-only model report for one catalog: trained versions (which is live) and production performance per engine. */
+    getModelOverview(productType: string, days?: number): Promise<any>;
+    getRecentIntegrationEvents(slug: string, windowHours?: number, limit?: number): Promise<any>;
+    /** impression, view, click, add_to_cart, remove_from_cart, purchase - or any type of your own. */
+    trackEvent(productType: string, eventType: string, event: {
+        item_id: string;
+        user_id?: string;
+        session_id?: string;
+        recommendation_id?: string;
+        placement?: string;
+        quantity?: number;
+        properties?: Record<string, unknown>;
+        event_id?: string;
+    }): Promise<any>;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,189 @@
+// HTTP client for the LIKYLY API surface this MCP server exposes as tools. Two tiers, both
+// just forwarding whatever key the process was started with - this client never decides what
+// it's allowed to do, the API does:
+//  - Recommendations/events (getRecommendations..trackEvent below) - safe with the
+//    restricted public key (see the recsys API's get_current_client_id_public_ok scope).
+//  - Data sources (listSourceTypes..getCatalogStats below) - needs the secret key or a
+//    developer key with the right scope (see /clients/me/developer-keys); a public-key
+//    caller gets a clear 401/403 from the API itself.
+// Deliberately standalone rather than depending on ../../js (not published to npm yet) - same
+// request shape as sdk/js/src/client.ts, trimmed to just this tool surface.
+export class LikylyClient {
+    baseUrl;
+    apiKey;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+    }
+    /** The recommendation call: LIKYLY picks the strategy. */
+    async getRecommendations(productType, request) {
+        return this.request("POST", "/getRec", { query: { data_product_type: productType }, body: request });
+    }
+    async getColdStartRecs(productType, itemId, count = 4) {
+        return this.request("GET", `/getRec/content/${encodeURIComponent(itemId)}/${count}`, {
+            query: { data_product_type: productType, response_format: "object" },
+        });
+    }
+    async getPopularRecs(productType, count = 4) {
+        return this.request("GET", `/getRec/popular/${count}`, {
+            query: { data_product_type: productType, response_format: "object" },
+        });
+    }
+    async getUserRecs(productType, userId, count = 3) {
+        return this.request("GET", `/getRec/collaborative/${encodeURIComponent(userId)}/${count}`, {
+            query: { data_product_type: productType, response_format: "object" },
+        });
+    }
+    async getHybridRecs(productType, userId, itemId, count = 3, alpha = 0.5) {
+        return this.request("GET", `/getRec/hybrid/${encodeURIComponent(userId)}/${encodeURIComponent(itemId)}/${count}`, {
+            query: { data_product_type: productType, alpha, response_format: "object" },
+        });
+    }
+    async getSessionRecs(productType, viewedItemIds, count = 3) {
+        return this.request("GET", "/getRec/session", {
+            query: { data_product_type: productType, viewed_item_ids: viewedItemIds.join(","), count, response_format: "object" },
+        });
+    }
+    async getUserSessionRecs(productType, userId, count = 3) {
+        return this.request("GET", `/getRec/sessionForUser/${encodeURIComponent(userId)}/${count}`, {
+            query: { data_product_type: productType, response_format: "object" },
+        });
+    }
+    // ---------------------------------------------------------------------------------------
+    // Data sources - admin surface, only usable with the secret key or a developer key
+    // carrying the right scope (see /clients/me/developer-keys). Every call below just
+    // forwards to the recsys API's /data-sources* routes; the API is the source of truth for
+    // what's allowed - a public-key caller gets a clear 401/403 from it, same as any other
+    // tool here would.
+    // ---------------------------------------------------------------------------------------
+    async listSourceTypes() {
+        return this.request("GET", "/data-sources/types");
+    }
+    async createDataSource(input) {
+        return this.request("POST", "/data-sources", { body: input });
+    }
+    async listDataSources() {
+        return this.request("GET", "/data-sources");
+    }
+    async getDataSource(dataSourceId) {
+        return this.request("GET", `/data-sources/${dataSourceId}`);
+    }
+    async updateDataSource(dataSourceId, input) {
+        return this.request("PATCH", `/data-sources/${dataSourceId}`, { body: input });
+    }
+    async deleteDataSource(dataSourceId) {
+        return this.request("DELETE", `/data-sources/${dataSourceId}`);
+    }
+    /** Push-mode sources (webhook, woocommerce): authenticated by the source's push secret. */
+    async pushItems(dataSourceId, pushSecret, items, deletedIds = []) {
+        return this.request("POST", `/data-sources/${dataSourceId}/push`, {
+            body: { items, deleted_ids: deletedIds },
+            headers: { "X-Push-Secret": pushSecret },
+        });
+    }
+    async rotatePushSecret(dataSourceId) {
+        return this.request("POST", `/data-sources/${dataSourceId}/push-secret/rotate`);
+    }
+    async testDataSource(dataSourceId) {
+        return this.request("POST", `/data-sources/${dataSourceId}/test`);
+    }
+    async previewDataSource(dataSourceId, limit) {
+        return this.request("POST", `/data-sources/${dataSourceId}/preview`, { query: { limit } });
+    }
+    async dryRunFieldMapping(dataSourceId, mapping, limit) {
+        return this.request("POST", `/data-sources/${dataSourceId}/field-mapping/dry-run`, {
+            query: { limit }, body: { mapping },
+        });
+    }
+    async saveFieldMapping(dataSourceId, mapping) {
+        return this.request("PUT", `/data-sources/${dataSourceId}/field-mapping`, { body: { mapping } });
+    }
+    async syncDataSource(dataSourceId, mode) {
+        return this.request("POST", `/data-sources/${dataSourceId}/sync`, { body: { mode: mode ?? "incremental" } });
+    }
+    async listSyncs(dataSourceId, limit) {
+        return this.request("GET", `/data-sources/${dataSourceId}/syncs`, { query: { limit } });
+    }
+    async getCatalogStats(dataSourceId) {
+        return this.request("GET", `/data-sources/${dataSourceId}/stats`);
+    }
+    // ---------------------------------------------------------------------------------------
+    // Placements - the recommended orchestration abstraction over the strategies above. Admin
+    // calls (all but recommend) need the secret key or a developer key with placements:read/
+    // placements:write; the actual PlacementRecommendResponse/Request shapes are documented in
+    // docs/placements.md, not repeated here.
+    // ---------------------------------------------------------------------------------------
+    async listPlacements() {
+        return this.request("GET", "/placements");
+    }
+    async createPlacement(input) {
+        return this.request("POST", "/placements", { body: input });
+    }
+    async getPlacement(slug) {
+        return this.request("GET", `/placements/${encodeURIComponent(slug)}`);
+    }
+    async updatePlacement(slug, input) {
+        return this.request("PATCH", `/placements/${encodeURIComponent(slug)}`, { body: input });
+    }
+    async deactivatePlacement(slug) {
+        return this.request("POST", `/placements/${encodeURIComponent(slug)}/deactivate`);
+    }
+    async deletePlacement(slug) {
+        return this.request("DELETE", `/placements/${encodeURIComponent(slug)}`);
+    }
+    async purgeRecommendationCache(slug) {
+        return this.request("POST", slug ? `/placements/${encodeURIComponent(slug)}/cache/purge` : "/placements/cache/purge");
+    }
+    async getPlacementRequirements(slug) {
+        return this.request("GET", `/placements/${encodeURIComponent(slug)}/requirements`);
+    }
+    async previewPlacement(slug, context, limit) {
+        return this.request("POST", `/placements/${encodeURIComponent(slug)}/preview`, { body: { context, limit } });
+    }
+    async getTrackingRequirements(slug) {
+        return this.request("GET", `/placements/${encodeURIComponent(slug)}/tracking-requirements`);
+    }
+    async getPlacementHealth(slug, windowHours) {
+        return this.request("GET", `/placements/${encodeURIComponent(slug)}/health`, { query: { window_hours: windowHours } });
+    }
+    /** Read-only model report for one catalog: trained versions (which is live) and production performance per engine. */
+    async getModelOverview(productType, days) {
+        return this.request("GET", "/models/overview", { query: { data_product_type: productType, days } });
+    }
+    async getRecentIntegrationEvents(slug, windowHours, limit) {
+        return this.request("GET", `/placements/${encodeURIComponent(slug)}/recent-events`, { query: { window_hours: windowHours, limit } });
+    }
+    /** impression, view, click, add_to_cart, remove_from_cart, purchase - or any type of your own. */
+    async trackEvent(productType, eventType, event) {
+        return this.request("POST", `/events/${encodeURIComponent(eventType)}`, {
+            query: { data_product_type: productType },
+            body: event,
+        });
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        if (opts.query) {
+            for (const [key, value] of Object.entries(opts.query)) {
+                if (value !== undefined && value !== null)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = { "X-API-Key": this.apiKey, ...opts.headers };
+        if (opts.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const response = await fetch(url.toString(), {
+            method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+        const text = await response.text();
+        const data = text ? JSON.parse(text) : null;
+        if (!response.ok) {
+            const detail = data && typeof data === "object" && "detail" in data
+                ? String(data.detail)
+                : response.statusText;
+            throw new Error(`LIKYLY API error (${response.status}): ${detail}`);
+        }
+        return data;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/http.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Hosted MCP service: the same tools as the local stdio server, exposed over MCP's
+// Streamable HTTP transport so any MCP-capable LLM client can connect by URL
+// (e.g. https://mcp.likyly.com/mcp) instead of running a local process.
+//
+// Stateless and multi-tenant: every request carries the caller's own *restricted public*
+// key (Authorization: Bearer <key>, or X-Likyly-Api-Key). The service stores no secrets and
+// simply forwards that key to the LIKYLY API, so a caller can never do more through MCP
+// than they could with the key directly.
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { LikylyClient } from "./client.js";
+import { createLikylyServer } from "./tools.js";
+const port = Number(process.env.PORT ?? 3200);
+const baseUrl = process.env.LIKYLY_BASE_URL ?? "https://api.likyly.com";
+const MAX_BODY_BYTES = 1_000_000;
+function setCors(res) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, X-Likyly-Api-Key, X-Likyly-Product-Type, Mcp-Session-Id, Mcp-Protocol-Version");
+    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+function jsonRpcError(res, status, code, message) {
+    sendJson(res, status, { jsonrpc: "2.0", error: { code, message }, id: null });
+}
+function extractApiKey(req) {
+    const auth = req.headers.authorization;
+    if (auth?.toLowerCase().startsWith("bearer "))
+        return auth.slice(7).trim() || undefined;
+    const header = req.headers["x-likyly-api-key"];
+    return (Array.isArray(header) ? header[0] : header)?.trim() || undefined;
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error("Request body too large");
+        chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+const server = createServer(async (req, res) => {
+    setCors(res);
+    const path = (req.url ?? "/").split("?")[0];
+    if (req.method === "OPTIONS") {
+        res.writeHead(204).end();
+        return;
+    }
+    if (path === "/health") {
+        sendJson(res, 200, { status: "ok", service: "likyly-mcp" });
+        return;
+    }
+    if (path !== "/mcp") {
+        sendJson(res, 404, { error: "Not found. The MCP endpoint is /mcp." });
+        return;
+    }
+    // Stateless mode: no server-initiated streams or sessions to resume.
+    if (req.method !== "POST") {
+        res.setHeader("Allow", "POST, OPTIONS");
+        jsonRpcError(res, 405, -32000, "Method not allowed - use POST.");
+        return;
+    }
+    const apiKey = extractApiKey(req);
+    if (!apiKey) {
+        res.setHeader("WWW-Authenticate", 'Bearer realm="likyly-mcp"');
+        jsonRpcError(res, 401, -32001, "Missing API key. Send your restricted public key as 'Authorization: Bearer <key>'.");
+        return;
+    }
+    let body;
+    try {
+        body = await readJson(req);
+    }
+    catch {
+        jsonRpcError(res, 400, -32700, "Invalid or oversized JSON body.");
+        return;
+    }
+    const productHeader = req.headers["x-likyly-product-type"];
+    const defaultProductType = (Array.isArray(productHeader) ? productHeader[0] : productHeader)?.trim() || undefined;
+    const mcp = createLikylyServer(new LikylyClient({ baseUrl, apiKey }), defaultProductType);
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        void transport.close();
+        void mcp.close();
+    });
+    try {
+        await mcp.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    catch (err) {
+        console.error("MCP request failed:", err);
+        if (!res.headersSent)
+            jsonRpcError(res, 500, -32603, "Internal server error.");
+    }
+});
+server.listen(port, () => {
+    console.error(`likyly-mcp HTTP service listening on :${port} (POST /mcp) -> ${baseUrl}`);
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { LikylyClient } from "./client.js";
+import { createLikylyServer } from "./tools.js";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * The key, from the environment or else from the project's credentials file written by
+ * `npx @likyly/wizard` (`.likyly/credentials.env`, gitignored): editors expand
+ * `${LIKYLY_DEVELOPER_KEY}` to an empty string when it is not exported, so an empty or
+ * unexpanded value falls through to the file.
+ */
+function resolveApiKey() {
+    const fromEnv = process.env.LIKYLY_API_KEY?.trim();
+    if (fromEnv && !fromEnv.startsWith("${"))
+        return fromEnv;
+    const file = resolve(process.env.LIKYLY_ENV_FILE || ".likyly/credentials.env");
+    try {
+        for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+            const m = line.match(/^\s*(LIKYLY_DEVELOPER_KEY|LIKYLY_API_KEY)\s*=\s*["']?([^"'\s#]+)/);
+            if (m)
+                return m[2];
+        }
+    }
+    catch {
+        // No credentials file: the error below explains how to provide a key.
+    }
+    return undefined;
+}
+const apiKey = resolveApiKey();
+if (!apiKey) {
+    console.error("LIKYLY_API_KEY is not set. For recommendations/event tracking only, use your restricted " +
+        "public key (account page's \"Clé publique\"). Running here in Claude Code, Codex or " +
+        "another coding agent and want the data-source admin tools (create_data_source, " +
+        "sync_data_source, ...) too? Use a developer key instead (create one with " +
+        "POST /clients/me/developer-keys, scopes sources:read + sources:write) - never a secret " +
+        "or developer key in a browser-facing environment, since it may not be a trusted one.");
+    process.exit(1);
+}
+const baseUrl = process.env.LIKYLY_BASE_URL ?? "https://api.likyly.com";
+// Most LIKYLY tenants only ever manage one catalog namespace - this lets a vibe coder
+// configure it once instead of repeating it in every prompt/tool call, while still
+// allowing an override per-call for multi-catalog setups.
+const defaultProductType = process.env.LIKYLY_PRODUCT_TYPE;
+const server = createLikylyServer(new LikylyClient({ baseUrl, apiKey }), defaultProductType);
+await server.connect(new StdioServerTransport());

package/dist/placement-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LikylyClient } from "./client.js";
+export declare function createLikylyPlacementTools(server: McpServer, client: LikylyClient): void;

package/dist/placement-tools.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+// Placement tools: the recommended way to wire LIKYLY recommendations into a site. A
+// Placement is a named, persistent config ("what to recommend, where, with what fallback and
+// filters") - create one, preview it, then the site calls it by slug from
+// POST /placements/{slug}/recommend (not an MCP tool - that's a runtime HTTP call the site's
+// own code makes, safe with the public key). These tools need the secret key or a developer
+// key with placements:read/placements:write - a caller using the wrong key gets a clear
+// 401/403 back through the tool result, same as the data-source admin tools.
+//
+// No LLM call happens in LIKYLY for any of this: turning a developer's natural-language
+// request ("4 related products on a PDP, session-based for anonymous visitors...") into the
+// parameters below is exactly what the coding agent calling these tools already does -
+// that's the point of exposing deterministic primitives instead of another prompt layer.
+export function createLikylyPlacementTools(server, client) {
+    function textResult(data) {
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    const slug = z.string().min(1).max(128).describe("The placement's slug, e.g. 'pdp-related'.");
+    const strategy = z.enum(["auto", "content", "session", "collaborative", "hybrid", "popular"]);
+    const contextType = z.enum([
+        "product_page", "listing_page", "category_page", "homepage", "cart", "account", "content_page", "custom",
+    ]);
+    const signalName = z.enum([
+        "current_item_id", "category_id", "collection_id", "user_id", "anonymous_id",
+        "session_id", "cart_item_ids", "locale", "custom_context",
+    ]);
+    const signals = z.object({
+        required: z.array(signalName).default([]).describe("Context keys this placement can't run without - missing one is a clear error, never a silent guess."),
+        optional: z.array(signalName).default([]).describe("Context keys this placement uses when present, but doesn't need."),
+    }).describe("Every context key is optional to send unless listed in `required`.");
+    const attributeRule = z.object({ attribute: z.string(), values: z.array(z.unknown()).min(1) });
+    const filters = z.object({
+        category_in: z.array(z.string()).optional(),
+        category_not_in: z.array(z.string()).optional(),
+        in_stock_only: z.boolean().optional().describe("Only filters items that actually have a stock/in_stock property - never excludes one for lacking it."),
+        include_attributes: z.array(attributeRule).optional(),
+        exclude_attributes: z.array(attributeRule).optional(),
+    });
+    const businessRules = z.object({
+        exclude_current_item: z.boolean().optional().describe("Default true - never recommend the item the visitor is already looking at back to itself."),
+        exclude_cart_items: z.boolean().optional().describe("Never recommend an item already in the cart - use for a cart cross-sell placement."),
+    });
+    const context = z.record(z.unknown()).describe("Sample context to run the placement against - any of current_item_id, category_id, collection_id, user_id, anonymous_id, session_id, cart_item_ids, locale, custom_context.");
+    server.tool("list_placements", "Every placement configured for this account. Check this before creating a new one, or to find a slug by name.", {}, async () => textResult(await client.listPlacements()));
+    server.tool("get_placement", "One placement's full configuration by slug.", { slug }, async ({ slug }) => textResult(await client.getPlacement(slug)));
+    server.tool("create_placement", "Registers a new named recommendation configuration - the abstraction to reach for instead of picking a raw strategy endpoint. Underneath it always calls one of LIKYLY's existing engines (content/session/collaborative/hybrid/popular) - 'auto' delegates to the same signal-based selection POST /getRec already uses (hybrid when both a user and an item are known, content from just an item, session from recent views, collaborative for a known user with a trained model, popular otherwise) - it is not a new ML model, just an orchestration choice. Set `signals.required` to the context keys this placement can't run without (e.g. current_item_id for a product-page placement) - everything else stays optional. `fallback_strategy` is tried if `strategy` returns nothing; 'popular' is always the final safety net regardless. Call preview_placement right after creating it.", {
+        slug,
+        name: z.string().min(1).max(200),
+        context_type: contextType.default("custom"),
+        product_type: z.string().optional().describe("Catalog namespace to recommend from - omit it when this account has a single catalog."),
+        limit: z.number().int().min(1).max(100).default(10),
+        audience: z.enum(["all", "anonymous", "identified"]).default("all"),
+        strategy: strategy.default("auto"),
+        signals: signals.default({ required: [], optional: [] }),
+        fallback_strategy: strategy.optional().describe("Tried if `strategy` returns no results. 'popular' is always the final safety net regardless."),
+        filters: filters.default({}),
+        business_rules: businessRules.default({}),
+        enabled: z.boolean().default(true),
+    }, async (input) => textResult(await client.createPlacement(input)));
+    server.tool("purge_recommendation_cache", "Empty the cache of anonymous recommendations: one placement's (`slug`) or every placement's (no slug). LIKYLY keeps an anonymous visitor's answer for a product for an hour and empties it on its own when the catalog or the placement changes - call this only when something changed that LIKYLY cannot see (stock managed outside LIKYLY, new product pages deployed) or when the developer asks to see fresh results now.", { slug: slug.optional() }, async ({ slug }) => textResult(await client.purgeRecommendationCache(slug)));
+    server.tool("update_placement", "Partial update of an existing placement - only the fields given are changed. Sending `signals`/`filters`/`business_rules` at all replaces that whole sub-object (not a deep merge). Use this to disable/re-enable too (`enabled: true|false`) - or delete_or_disable_placement's default mode, which is the same thing plus a clearer name for it.", {
+        slug,
+        name: z.string().optional(),
+        context_type: contextType.optional(),
+        product_type: z.string().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        audience: z.enum(["all", "anonymous", "identified"]).optional(),
+        strategy: strategy.optional(),
+        signals: signals.optional(),
+        fallback_strategy: strategy.optional(),
+        filters: filters.optional(),
+        business_rules: businessRules.optional(),
+        enabled: z.boolean().optional(),
+    }, async ({ slug, ...input }) => textResult(await client.updatePlacement(slug, input)));
+    server.tool("delete_or_disable_placement", "mode:'disable' (the default, reversible): POST /placements/{slug}/recommend starts 404ing immediately, nothing is deleted - prefer this. mode:'delete': permanent, only for a configuration that was wrong and shouldn't exist at all.", { slug, mode: z.enum(["disable", "delete"]).default("disable") }, async ({ slug, mode }) => textResult(mode === "delete" ? await client.deletePlacement(slug) : await client.deactivatePlacement(slug)));
+    server.tool("get_placement_requirements", "Static introspection (no engine call) - the required/optional context signals, strategy, fallback_strategy and context_type. Call this before wiring a site to a placement, to know exactly what context (current_item_id, user_id, session_id, ...) to send at recommend time.", { slug }, async ({ slug }) => textResult(await client.getPlacementRequirements(slug)));
+    server.tool("preview_placement", "Runs a placement's full orchestration (strategy selection, fallback, filters) against a sample context - never writes anything, mints no recommendation_id, nothing attributable. Returns strategy_used, items, whether a fallback was used, which strategies were attempted, which context signals were actually present, and warnings/errors (a missing required signal shows up in `errors`, not a thrown error) - use this to validate a placement before wiring it into a site, or to debug one that isn't behaving as expected.", { slug, context: context.default({}), limit: z.number().int().min(1).max(100).optional() }, async ({ slug, context, limit }) => textResult(await client.previewPlacement(slug, context, limit)));
+}

package/dist/recipe-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LikylyClient } from "./client.js";
+export declare function createLikylyRecipeTools(server: McpServer, client: LikylyClient): void;

package/dist/recipe-tools.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+// get_integration_recipe: a structured contract for wiring a placement into a real codebase -
+// packages to install, env vars, the public API to call, the context/events it needs, a short
+// illustrative snippet, and warnings. Deliberately NOT a whole file to paste: `framework` /
+// `renderingMode` / `hasAuthContext` are supplied by the calling agent (it already inspected
+// the repo) - LIKYLY never tries to detect a customer's stack itself, and this tool composes
+// its answer from that input plus the placement's own live requirements (get_placement_requirements),
+// not from guessing.
+export function createLikylyRecipeTools(server, client) {
+    function jsonResult(data) {
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    const framework = z.enum(["react", "nextjs", "vue", "svelte", "vanilla-js", "other"]);
+    server.tool("get_integration_recipe", "Everything needed to wire one placement into a real codebase, as structured data - not a file to copy-paste. Call this after create_placement (and, ideally, after preview_placement/configure_field_mapping have confirmed it produces sane results). Tell it the framework you found in the project (you inspected it - this tool never guesses), and it returns: packages to install, env vars, the public API to call for this framework, the context/events this specific placement needs, a short illustrative snippet, and warnings (e.g. the placement is disabled, or no auth context was given so userId will be omitted).", {
+        placement: z.string().min(1).max(128),
+        framework,
+        rendering_mode: z.enum(["csr", "ssr", "rsc"]).optional().describe("For react/nextjs: whether the integration point is a client component, a server-rendered page, or a React Server Component."),
+        has_auth_context: z.boolean().default(false).describe("Does the project already expose the current user's id at the point this placement will render?"),
+    }, async ({ placement, framework, rendering_mode, has_auth_context }) => {
+        const [requirements, tracking] = await Promise.all([
+            client.getPlacementRequirements(placement),
+            client.getTrackingRequirements(placement),
+        ]);
+        return jsonResult(buildRecipe(requirements, tracking, framework, rendering_mode, has_auth_context));
+    });
+}
+function buildRecipe(requirements, tracking, framework, renderingMode, hasAuthContext) {
+    const isReactFamily = framework === "react" || framework === "nextjs";
+    const packages = isReactFamily ? ["@likyly/sdk", "@likyly/react"] : ["@likyly/sdk"];
+    const env = [
+        {
+            name: framework === "nextjs" ? "NEXT_PUBLIC_LIKYLY_KEY" : framework === "vue" || framework === "svelte" ? "VITE_PUBLIC_LIKYLY_KEY" : "LIKYLY_PUBLIC_KEY",
+            value: "the account's restricted PUBLIC key only - never the secret or a developer key (see docs/placements.md's Security note)",
+        },
+    ];
+    const requiredContext = [
+        ...requirements.signals.required.map((name) => ({ name, required: true })),
+        ...requirements.signals.optional.map((name) => ({ name, required: false })),
+    ];
+    const requiredEvents = tracking.required_events.map((e) => ({ eventType: e.event_type, scope: e.scope, why: e.why }));
+    const publicApi = isReactFamily
+        ? "@likyly/react: <LikylyProvider apiKey> once at the app root, then useRecommendations({placement, context}) or <LikylyRecommendations placement .../> where the placement renders."
+        : "@likyly/sdk: new Likyly({apiKey}) once, then likyly.recommend({placement, context}) where the placement renders, and likyly.events.* for tracking.";
+    const minimalExample = isReactFamily
+        ? [
+            framework === "nextjs" ? '"use client";' : undefined,
+            `import { LikylyRecommendations } from "@likyly/react";`,
+            "",
+            `<LikylyRecommendations placement="${requirements.slug}"`,
+            requirements.signals.required.includes("current_item_id") || requirements.signals.optional.includes("current_item_id") ? "  itemId={product.id}" : undefined,
+            requirements.signals.required.includes("user_id") || requirements.signals.optional.includes("user_id") ? "  userId={user?.id}" : undefined,
+            "/>",
+        ]
+            .filter((line) => line !== undefined)
+            .join("\n")
+        : [
+            `import { Likyly } from "@likyly/sdk";`,
+            `const likyly = new Likyly({ apiKey: /* public key */ });`,
+            "",
+            `const result = await likyly.recommend({ placement: "${requirements.slug}", context: { itemId: product.id, userId: user?.id, sessionId } });`,
+            `// render result.items yourself, then:`,
+            `await likyly.events.recommendationImpression({ itemId: result.items[0].itemId, recommendationId: result.recommendationId, placement: "${requirements.slug}", userId: user?.id, sessionId });`,
+        ].join("\n");
+    const warnings = [];
+    if (!requirements.enabled) {
+        warnings.push(`Placement "${requirements.slug}" is currently disabled (enabled: false) - recommend() will 404 until it's re-enabled (update_placement / delete_or_disable_placement with mode "disable" toggles this).`);
+    }
+    if (!hasAuthContext && (requirements.signals.required.includes("user_id") || requirements.signals.optional.includes("user_id"))) {
+        warnings.push("No auth context given - userId will be omitted at the integration point until the project's own auth state is wired in; this placement will rely on session-based signals alone until then.");
+    }
+    if (isReactFamily && renderingMode === "rsc") {
+        warnings.push('useRecommendations/<LikylyRecommendations> use client-side React state (hooks) - render them from a Client Component ("use client"), not directly inside a React Server Component.');
+    }
+    if (framework === "vue" || framework === "svelte") {
+        warnings.push("No @likyly/vue or @likyly/svelte package exists yet - use @likyly/sdk's likyly.recommend()/likyly.events.* directly and wire the result into this framework's own reactivity (a computed/ref, a store, ...).");
+    }
+    if (requirements.fallback_strategy === null && requirements.strategy !== "auto" && requirements.strategy !== "popular") {
+        warnings.push(`This placement's strategy ("${requirements.strategy}") has no fallback_strategy configured - it still always falls back to "popular" as a last resort, but consider setting one explicitly for a more relevant fallback than pure popularity.`);
+    }
+    return { packages, env, publicApi, requiredContext, requiredEvents, minimalExample, warnings };
+}

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LikylyClient } from "./client.js";
+export declare function createLikylyServer(client: LikylyClient, defaultProductType?: string): McpServer;

package/dist/tools.js

@@ -0,0 +1,75 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createLikylyAdminTools } from "./admin-tools.js";
+import { createLikylyPlacementTools } from "./placement-tools.js";
+import { createLikylyRecipeTools } from "./recipe-tools.js";
+import { createLikylyValidatorTools } from "./validator-tools.js";
+// Shared tool surface: used by the local stdio server (index.ts) and the hosted HTTP
+// service (http.ts). Two tiers of tools, both just forwarding whatever key this server was
+// started with - the recommendation/event tools below work with the restricted public key;
+// the admin tools (list_source_types..get_catalog_stats, in admin-tools.ts) configure and run
+// catalog data-source integrations, and need the secret key or a developer key with the
+// right scope instead (see /clients/me/developer-keys in the recsys API) - a caller using
+// the wrong key gets a clear 401/403 back through the tool result, same as any other error
+// here. Registering both unconditionally (rather than trying to detect the key's own
+// capabilities up front) keeps this server simple and lets the API stay the single source of
+// truth for what a given key can do.
+export function createLikylyServer(client, defaultProductType) {
+    const server = new McpServer({ name: "likyly-recsys", version: "0.4.1" });
+    const productType = defaultProductType
+        ? z.string().optional().describe(`Catalog namespace. Defaults to "${defaultProductType}" if omitted.`)
+        : z.string().describe("Catalog namespace, e.g. \"movies\" or your own product category.");
+    function resolveProductType(value) {
+        const resolved = value ?? defaultProductType;
+        if (!resolved) {
+            throw new Error("No product_type given and LIKYLY_PRODUCT_TYPE is not set in the server's environment.");
+        }
+        return resolved;
+    }
+    function textResult(data) {
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    const id = z.string().min(1).max(255);
+    server.tool("get_recommendations", "The recommendation call to use: send whatever you know (a user_id, an anonymous session_id, the item_id being viewed, viewed_item_ids, a placement label) and LIKYLY picks the best strategy (hybrid, content, collaborative, session or popular) and returns it in `strategy`. Every response has a `recommendation_id` - pass it as recommendation_id to track_event for the impression/click/add_to_cart/purchase events that follow, to attribute them. Ids are YOUR own ids (any string).", {
+        product_type: productType,
+        user_id: id.optional(),
+        session_id: id.optional().describe("Anonymous visitor / browsing session id."),
+        item_id: id.optional().describe("The item being looked at."),
+        viewed_item_ids: z.array(id).max(50).optional().describe("Recently viewed item ids, oldest first."),
+        placement: z.string().max(128).optional().describe("Free-form label of where the recommendations are shown, e.g. homepage."),
+        count: z.number().int().min(1).max(100).default(10),
+    }, async ({ product_type, ...request }) => textResult(await client.getRecommendations(resolveProductType(product_type), request)));
+    server.tool("get_popular_recommendations", "Most popular products (pure popularity ranking) - the right fallback for a visitor with no browsing history and no product to anchor content similarity on.", { product_type: productType, count: z.number().int().min(1).max(50).default(10) }, async ({ product_type, count }) => textResult(await client.getPopularRecs(resolveProductType(product_type), count)));
+    server.tool("get_cold_start_recommendations", "Content-based recommendations similar to one product (synopsis/genre/description similarity + semantic embeddings) - works with zero user history, e.g. on a product page.", { product_type: productType, item_id: id, count: z.number().int().min(1).max(50).default(4) }, async ({ product_type, item_id, count }) => textResult(await client.getColdStartRecs(resolveProductType(product_type), item_id, count)));
+    server.tool("get_collaborative_recommendations", "Collaborative-filtering recommendations (implicit ALS) for a known/logged-in user, learned from cross-user purchase patterns.", { product_type: productType, user_id: id, count: z.number().int().min(1).max(50).default(3) }, async ({ product_type, user_id, count }) => textResult(await client.getUserRecs(resolveProductType(product_type), user_id, count)));
+    server.tool("get_hybrid_recommendations", "Blends content similarity to one product with collaborative filtering for one user. alpha (0-1) weights collaborative vs. content: 0 = pure content, 1 = pure collaborative, 0.5 = balanced.", {
+        product_type: productType,
+        user_id: id,
+        item_id: id,
+        count: z.number().int().min(1).max(50).default(3),
+        alpha: z.number().min(0).max(1).default(0.5),
+    }, async ({ product_type, user_id, item_id, count, alpha }) => textResult(await client.getHybridRecs(resolveProductType(product_type), user_id, item_id, count, alpha)));
+    server.tool("get_session_recommendations", "Recency-weighted recommendations from an explicit list of recently-viewed item ids - no account needed (anonymous session). The last id in the list is weighted the most.", { product_type: productType, viewed_item_ids: z.array(id).min(1).max(50), count: z.number().int().min(1).max(50).default(3) }, async ({ product_type, viewed_item_ids, count }) => textResult(await client.getSessionRecs(resolveProductType(product_type), viewed_item_ids, count)));
+    server.tool("get_user_session_recommendations", "Same recency-weighted logic as get_session_recommendations, but sourced from a logged-in user's persisted view history instead of a client-supplied list - survives across devices/sessions.", { product_type: productType, user_id: id, count: z.number().int().min(1).max(50).default(3) }, async ({ product_type, user_id, count }) => textResult(await client.getUserSessionRecs(resolveProductType(product_type), user_id, count)));
+    server.tool("track_event", "Record an interaction: impression, view, click, add_to_cart, remove_from_cart, purchase - or any event type of your own. Needs item_id and at least one of user_id (logged in) / session_id (anonymous). Pass the recommendation_id of the get_recommendations call that surfaced the item to attribute it. Send event_id (any unique string) on purchases so a retry is not counted twice.", {
+        product_type: productType,
+        event_type: z.string().regex(/^[a-zA-Z0-9_-]+$/).max(64).describe("e.g. view, click, purchase"),
+        item_id: id,
+        user_id: id.optional(),
+        session_id: id.optional(),
+        recommendation_id: z.string().max(128).optional(),
+        placement: z.string().max(128).optional(),
+        quantity: z.number().int().min(0).optional(),
+        properties: z.record(z.unknown()).optional().describe("Free-form JSON: price, currency, order_id, revenue, ..."),
+        event_id: z.string().max(255).optional(),
+    }, async ({ product_type, event_type, ...event }) => {
+        if (!event.user_id && !event.session_id)
+            throw new Error("Provide user_id and/or session_id.");
+        return textResult(await client.trackEvent(resolveProductType(product_type), event_type, event));
+    });
+    createLikylyAdminTools(server, client);
+    createLikylyPlacementTools(server, client);
+    createLikylyRecipeTools(server, client);
+    createLikylyValidatorTools(server, client);
+    return server;
+}

package/dist/validator-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LikylyClient } from "./client.js";
+export declare function createLikylyValidatorTools(server: McpServer, client: LikylyClient): void;

package/dist/validator-tools.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+// The integration validator: real facts from LIKYLY's own data (recent recommend calls,
+// impressions, clicks, product views, add-to-carts, purchases), not a guess from reading the
+// site's source. "Vérifie que mon intégration Likyly est correcte" should be answerable by
+// calling validate_integration, not by Claude Code re-reading its own previous edits.
+export function createLikylyValidatorTools(server, client) {
+    function textResult(text) {
+        return { content: [{ type: "text", text }] };
+    }
+    function jsonResult(data) {
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    const slug = z.string().min(1).max(128).describe("The placement's slug.");
+    const windowHours = z.number().int().min(1).max(24 * 30).default(24).describe("How far back to look, in hours. Default 24.");
+    server.tool("get_tracking_requirements", "Which events this placement needs instrumented, and why - call this before writing tracking code (recommendation_impression/recommendation_click are placement-specific; product_view/add_to_cart/purchase are catalog-wide funnel events every placement benefits from). Follow up with get_placement_health once the site is live to confirm they actually arrived.", { slug }, async ({ slug }) => jsonResult(await client.getTrackingRequirements(slug)));
+    server.tool("get_placement_health", "Structured counts of what actually arrived for this placement in the last window_hours (recommend calls, impressions, clicks, product views, add-to-carts, purchases), each marked ok/warning/missing. The raw data behind validate_integration - use that tool instead for a human-readable checklist; use this one if you need the numbers themselves.", { slug, window_hours: windowHours }, async ({ slug, window_hours }) => jsonResult(await client.getPlacementHealth(slug, window_hours)));
+    server.tool("get_recent_integration_events", "The individual recent recommend calls and tracked events behind get_placement_health's counts - for debugging exactly which item/session/strategy was involved, when the aggregate counts alone don't explain what's wrong (e.g. recommendations were requested but always for the wrong item_id).", { slug, window_hours: windowHours, limit: z.number().int().min(1).max(100).default(20) }, async ({ slug, window_hours, limit }) => jsonResult(await client.getRecentIntegrationEvents(slug, window_hours, limit)));
+    server.tool("get_model_overview", "Read-only report on one catalog's recommendation model - what /likyly-model shows. `versions`: every trained version of the collaborative (ALS) model, newest first, with trained_at, triggered_by (manual or auto), precision_at_k (k = precision_k, measured on a held-out 20% of interactions), and the users/items/interactions it learned from; `is_active` marks the one serving production, the others are history or candidates rejected for scoring lower. `performance`: per engine that actually served this catalog in the last `days` (hybrid, content, collaborative, session, popular - the strategy after any fallback), recommendations served and the impressions, clicks, add-to-carts and purchases attributed to them, with ctr. Only collaborative and hybrid use the trained model; content uses item similarity, session the visitor's recent views, popular the catalog's popularity - none of those three is versioned. Get the catalog name from list_placements (each placement's product_type).", {
+        product_type: z.string().min(1).max(64).describe("The catalog, e.g. a placement's product_type."),
+        days: z.number().int().min(1).max(90).default(7).describe("How many days of production traffic to count. Default 7."),
+    }, async ({ product_type, days }) => jsonResult(await client.getModelOverview(product_type, days)));
+    server.tool("validate_integration", "Step 11 of wiring up a placement: verifies the integration is actually working, from LIKYLY's own data - not a guess from reading the site's source. Call this after rendering the placement and adding tracking, whenever a developer asks to \"check\"/\"verify\" their LIKYLY integration. Renders a checklist (✓ ok, ⚠ received but worth a look, ✗ missing/critical) and, for anything not ok, a concrete next step - loop back to get_integration_recipe or get_tracking_requirements for the ones it names.", { slug, window_hours: windowHours }, async ({ slug, window_hours }) => textResult(await renderValidation(client, slug, window_hours)));
+}
+const CHECK_LABELS = {
+    recommendations_requested: {
+        ok: "recommendations requested",
+        bad: "recommendations not requested yet",
+        nextStep: "Call POST /placements/{slug}/recommend (likyly.recommend(...) in the SDK) from the page - nothing else here can be true until this is.",
+    },
+    current_item_supplied: {
+        ok: "current item supplied",
+        bad: "current item not supplied",
+        nextStep: "Pass context.itemId (the product/article being viewed) to likyly.recommend / useRecommendations - this placement requires it.",
+    },
+    anonymous_session_supplied: {
+        ok: "anonymous session supplied",
+        bad: "anonymous session not supplied",
+        nextStep: "Pass context.sessionId (or anonymousId - see LikylySession) for anonymous visitors - this placement requires one.",
+    },
+    impressions_received: {
+        ok: "impressions received",
+        bad: "impressions not received",
+        nextStep: "Fire recommendationImpression for each rendered item (automatic with <LikylyRecommendations>; call trackImpression yourself with useRecommendations).",
+    },
+    recommendation_clicks_received: {
+        ok: "recommendation clicks received",
+        bad: "recommendation clicks not received",
+        nextStep: "Fire recommendationClick when a recommended item is clicked (automatic with <LikylyRecommendations>; call trackClick yourself with useRecommendations). Can legitimately be zero on low traffic.",
+    },
+    product_views_received: {
+        ok: "product views received",
+        bad: "product views not received",
+        nextStep: "Call likyly.events.productView on your product/article page - this is a catalog-wide event, not specific to this placement.",
+    },
+    add_to_cart_received: {
+        ok: "add_to_cart received",
+        bad: "add_to_cart not received",
+        nextStep: "Call likyly.events.addToCart where the visitor adds an item to their cart - optional but improves ranking quality over time.",
+    },
+    purchases_received: {
+        ok: "purchases received",
+        bad: "purchases not received",
+        nextStep: "Call likyly.events.purchase (with an eventId, so a retry never double-counts a sale) once checkout completes - the strongest training signal, and what attribution ultimately measures.",
+    },
+};
+const SYMBOL = { ok: "✓", warning: "⚠", missing: "✗" };
+async function renderValidation(client, slug, windowHours) {
+    const health = (await client.getPlacementHealth(slug, windowHours));
+    const lines = [`Placement: ${slug}`, ""];
+    const nextSteps = [];
+    for (const check of health.checks) {
+        const labels = CHECK_LABELS[check.name] ?? { ok: check.name, bad: `${check.name} (not received)`, nextStep: "" };
+        const symbol = SYMBOL[check.status] ?? "?";
+        lines.push(`${symbol} ${check.status === "ok" ? labels.ok : labels.bad}`);
+        if (check.status !== "ok" && labels.nextStep)
+            nextSteps.push(`- ${labels.bad}: ${labels.nextStep}`);
+    }
+    if (nextSteps.length > 0) {
+        lines.push("", "Next steps:", ...nextSteps);
+    }
+    else {
+        lines.push("", "Everything this validator checks is flowing - the integration looks correct.");
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@likyly/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "Lets your AI coding assistant (Claude Code, Cursor, VS Code, Codex) set up LIKYLY product recommendations: connect your catalog, create placements, integrate and verify.",
+  "keywords": [
+    "likyly",
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "claude-code",
+    "cursor",
+    "recommendations",
+    "ecommerce"
+  ],
+  "homepage": "https://www.likyly.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Likyly/likyly-recsys.git",
+    "directory": "sdk/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Likyly/likyly-recsys/issues"
+  },
+  "author": "LIKYLY (https://www.likyly.com)",
+  "type": "module",
+  "bin": {
+    "likyly-mcp-server": "./dist/index.js",
+    "likyly-mcp-http": "./dist/http.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "@types/node": "^20"
+  },
+  "license": "MIT"
+}