bow-products-mcp

MCP server + CLI for Bow Beauty admins (and Claude) to populate, enrich and validate the products catalog without leaving the editor.

The MCP exposes the four admin-only endpoints introduced in the products module overhaul (/enrich, /bulk, /import-from-url, /test-recommendations) plus the regular product CRUD endpoints. Authentication is the same Bow Beauty JWT used by the bow-admin dashboard — your account must have role Admin.

Requirements

• Node.js ≥ 20.

• An Admin account on a Bow Beauty API.

Related MCP server: MCP Shopify

Install

git clone https://github.com/<org>/bow-products-mcp.git
cd bow-products-mcp
npm install
npm run build
npm link        # makes the `bow-products-mcp` bin available globally

The bin can also be invoked directly via node /path/to/bow-products-mcp/dist/cli.js ….

Commands

Pointing at a different backend

The default API URL is the Bow Beauty dev backend. Override with the BOW_API_BASE_URL env var or --api-base-url=<url> flag when logging in:

BOW_API_BASE_URL=https://my-api.example.com bow-products-mcp login

Wiring into Claude Code

After running bow-products-mcp login once, add the server to Claude Code:

claude mcp add bow-products bow-products-mcp run

Then in any Claude Code session you can ask Claude to:

• "Search the catalog for niacinamide serums under $30."

• "Enrich this draft product with brand X."

• "Import this product URL and test how it would rank for an oily-skin profile."

• "Bulk ingest these 12 products."

MCP tools exposed

Catalog read

• search_products({ searchTerm?, category?, brand?, minPrice?, maxPrice?, inStock?, isFeatured?, page?, pageSize? })

• get_product({ id })

Catalog write (Admin)

• create_product({ reference, name, description, price, brand, category, ... })

• update_product({ id, patch }) — partial update; only the fields in patch change.

• delete_product({ id })

AI ingestion (Admin)

• enrich_product_draft({ name, brand, category, ...hints }) — Gemini-enriched draft, not persisted.

• bulk_ingest({ mode: 'Create' | 'Upsert' | 'EnrichAndCreate', products: [...] }) — max 50 items per call.

• import_from_url({ url, dryRun }) — fetch + Gemini extract + enrich; persists as IsActive=false when dryRun=false.

Test recommendations

• test_recommendations({ profile, limit?, includeScoreBreakdown? }) — runs the engine against a synthetic user. profile accepts skinType, concerns, hairTypes, colorSeason, undertone, preferredRoutineStep, categories, priceRange, ethical. The breakdown surfaces every signal that fired and the points it added.

Enum surfacing

The list_* tools return the valid string values for each enum, so Claude can construct correct inputs without a round-trip:

list_categories, list_concerns, list_skin_types, list_hair_types, list_routine_steps, list_formulations, list_finishes, list_color_seasons, list_undertones, list_bulk_modes.

Auth and refresh

Login decodes the JWT locally just to short-circuit non-admin accounts (rejected with a clear message). The backend remains the authoritative role check on every request.

The HTTP client transparently refreshes the JWT on any 401 (using the persisted refresh token) and retries the request once. If the refresh itself fails, all subsequent tool calls return an error asking you to run bow-products-mcp login again.

Security notes

• The config file is written with chmod 600 so it is only readable by your user.

• Tokens are never sent to anywhere other than the configured API base URL.

• This is v1: the JWT is stored on disk in plain JSON. If you'd rather use the OS keychain, open an issue.

• Never commit ~/.bow-mcp/config.json — it's a per-user secret.

Development

npm run watch   # tsc --watch
npm start       # node dist/cli.js help

Lint and tests are pending in v1; this package targets a small operational footprint.

License

MIT