bluestone-pim-ui

Bluestone PIM — Fit-for-purpose UI

Generate a small, single-file HTML demo that talks live to a real Bluestone PIM tenant via the Bluestone MCP server. Every demo built from this skill is one more piece of evidence that fit-for-purpose UIs can be built on top of an event-driven, API-only PIM — the story behind labs.bluestonepim.com.

Quick start — what a good demo looks like

A reader should immediately recognise the artefact as a labs.bluestonepim.com demo:

• •Single self-contained `.html` — opens via double-click. No build step, no framework.
• •One sharp persona, only their controls — the contrast with a generic PIM UI is the point.
• •Live write path to LABS via MCP — at least one button actually creates or updates something in Bluestone.
• •Dark Bluestone Labs theme — Montserrat, --bg #050D1F, green-pulsing "Bluestone PIM LABS" badge.
• •Settings modal (Worker URL + shared secret) persisted to localStorage.

Don't ship a multi-page SPA. Don't introduce React, Tailwind, or a build pipeline.

Architecture

Browser (your demo HTML)  ──►  Cloudflare Worker  ──►  Bluestone PIM MCP server  ──►  Bluestone PIM
        localStorage:               shared secret +              jsonrpc 2.0 tools/call
        Worker URL + secret         3 Bluestone headers          over streamable HTTP/SSE

The browser never sees Bluestone credentials — they live as Wrangler secrets on the Worker. The Worker handles auth and CORS; direct browser→MCP doesn't work today. Protocol detail in references/mcp-protocol.md.

Worker upgrade gate — check this first

Anything beyond create_product needs the generic /api/mcp-call route. Run the starter's Test button — if it reports Generic /api/mcp-call ✗ (Worker is legacy …), drop assets/worker-upgrade.js over worker/worker.js and wrangler deploy before writing persona code.

Workflow

1. Pin the persona before writing code

Get to one sentence: "This is a [role] who needs to [verb] [PIM concept] so they can [outcome]." If the user hasn't been specific, ask. Common shapes (full recipes in references/persona-recipes.md, worth reading first): Merchandiser quick-edit, Supplier portal, Store-associate lookup, Buyer scorecard, Content-enrichment workbench, Agentic command bar.

2. Pick MCP tools from the catalog

references/mcp-tools.md snapshots all 23 Bluestone MCP tools — names, schemas, idempotency, recipe-to-tool mapping. Prefer server-side search_products and list_product_completeness_scores over computing equivalents in JS. The MCP server can drift; verify with /api/mcp-list and update the snapshot when it's stale rather than working around it.

3. Copy the starter, don't rebuild

assets/starter.html is a ~250-line single file with the theme, Settings modal + localStorage, Test button, the mcpCall(tool, args) helper that unwraps the JSON-RPC envelope, and a toast. Copy it, rename (e.g. merchandiser.html), and build inside <main id="app">. Don't rewrite the wiring.

4. Wire only the MCP calls you actually need

Real writes are slow-ish and have real consequences (create_product creates a product on LABS). The pattern:

• •One or two hero write actions that prove the story — always real, verifiable in the live Bluestone UI right after.
• •Reads — live MCP for low-stakes lookups; seeded JS array (see references/persona-recipes.md) for the hero list a demo rests on, when zero-flake matters more than freshness.

5. Bake the narrative in, lightly

Small cues only — the green-pulse "Bluestone PIM LABS" badge (already in the starter), a "Live mode — writes to Bluestone PIM LABS via MCP" banner near the write button, a quiet "Built in one afternoon, on the Bluestone MCP" footer. Drop-in copy in references/narrative.md. The proof is the working demo, not the copy.

6. Test the round-trip before claiming done

1. Settings → Worker URL + secret → Test → green check.
2. Trigger the hero action → toast says success.
3. Open the real Bluestone PIM UI in another tab → confirm the artefact landed.

If you can't run a browser, say so plainly and hand the user the checklist. A demo that fails in front of an analyst is much worse than a demo that took ten extra minutes to verify.

Common pitfalls

• •CORS error. Worker's ALLOWED_ORIGINS is hardcoded — add the new origin and redeploy. Don't switch to *.
• •"Unauthorized" from the Worker. Shared secret in Settings ≠ SHARED_SECRET on the Worker. Whitespace matters.
• •MCP returns text, not JSON. Tool results are { content: [{ type: 'text', text: '…' }] }. IDs are often inside the text — regex the Mongo ObjectId (/\b([0-9a-f]{24})\b/i). Always unwrap with the starter's extractMcpText.
• •Don't embed credentials. Not in HTML, not in a JS const, not in a comment. The Worker pattern exists so the page can be public on GitHub Pages.

References

• •references/mcp-tools.md — All 23 Bluestone MCP tools, schemas, idempotency, recipe mapping. Read first when picking tools.
• •references/mcp-protocol.md — JSON-RPC shapes, Worker routes, the generic /api/mcp-call upgrade, SSE handling.
• •references/persona-recipes.md — 7 fit-for-purpose UI shapes with the tools each needs.
• •references/visual-system.md — Colors, typography, badge and pill primitives.
• •references/narrative.md — The "SaaS as toolbox" story plus drop-in copy.

Assets

• •assets/starter.html — Single-file dark-themed starter. Copy, rename, build inside <main id="app">.
• •assets/worker-upgrade.js — Drop-in worker/worker.js replacement that keeps /api/create-product and adds a generic /api/mcp-call route.