pier39-merchant-server 0.1.1

Drop-in negotiate.v1 backend for any storefront. Ships the chat agent, discovery files, and rate limiting; you bring the catalog.

pier39-merchant-server

Drop-in negotiate.v1 backend for any storefront. You bring a catalog.json. The library brings the chat agent, the discovery files, and the rate limiting. Six lines and your store is negotiable by any AI shopper that speaks the protocol.

Install

pip install pier39-merchant-server

You also need pier39-merchant skill installed somewhere the library can find it:

git clone https://github.com/sanjana-pier39/pier39-skills
mkdir -p ~/.claude/skills
cp -R pier39-skills/plugins/pier39/skills/pier39-merchant ~/.claude/skills/

(The library auto-discovers the skill at ~/.claude/skills/pier39-merchant/. Override with PIER39_MERCHANT_SKILL_PATH env var or pass skill_path= directly.)

Use

Six lines, including the import:

from pier39_merchant_server import serve

serve(catalog_path="catalog.json", host="0.0.0.0", port=8000)

That gives you, on http://0.0.0.0:8000:

Path	Method	Purpose
/negotiate.json + /.well-known/negotiate.json	GET	negotiate.v1 protocol descriptor
/llms.txt	GET	AI-readable site index
/api/store/catalog	GET	Public product catalog (hidden fields stripped)
/api/store/chat/start?product_id=<id>	GET	Open chat session
/api/store/chat/<sid>/say?message=<urlencoded>	GET	Send shopper turn
/api/store/chat/<sid>	GET	Read running history
/api/store/chat/start	POST	Same as GET, for browser widgets
/api/store/chat/<sid>/message	POST	Same as GET, for browser widgets
/api/health	GET	Liveness check

All public, all CORS-permissive (Access-Control-Allow-Origin: *).

Catalog format

A catalog.json looks like this — see examples/tiny_store/catalog.json for a working minimal example:

{
  "store": {
    "name": "Your Store",
    "city": "City, ST",
    "rep_name": "Casey",
    "tagline": "...",
    "policy_default": "Free shipping. 30-day return. ..."
  },
  "products": [
    {
      "id": "widget-pro",
      "kind": "widget",
      "name": "Widget Pro",
      "subtitle": "Short product line",
      "description": "Long description (model, accessories, etc.)",
      "year_made": 2024,
      "condition": "Brand new",
      "list_price": 199,

      "floor": 165,
      "levers": [
        "Free expedited shipping (~$15 retail value)",
        "Bonus accessory kit ($29 retail)",
        "Extended warranty (12 → 24 months)"
      ],
      "inventory_note": "..."
    }
  ]
}

The floor, levers, and inventory_note fields are hidden — they appear only in the merchant agent's private system prompt, never in any GET response. The library's /api/store/catalog endpoint strips them automatically.

Deeper control

If you need to customize, instantiate MerchantApp directly:

from pier39_merchant_server import MerchantApp

app = MerchantApp(
    catalog_path="catalog.json",
    skill_path="/custom/path/to/pier39-merchant",
    model="claude-opus-4-6",                    # default: claude-sonnet-4-6
    max_chat_starts_per_hour_per_ip=20,         # default: 8
    max_messages_per_chat=50,                   # default: 30
    max_message_length=3000,                    # default: 2000
    session_idle_ttl_seconds=7200,              # default: 3600 (1h)
)
app.run(host="0.0.0.0", port=8000)

You can also pull app.make_handler_class() and mount it under your own ThreadingHTTPServer / nginx / wsgi setup if you have an existing stack.

Required env vars

• ANTHROPIC_API_KEY — for the merchant chat agent
• PIER39_MERCHANT_SKILL_PATH (optional) — override skill auto-discovery

What you get for free

Any AI shopper agent that speaks negotiate.v1 can now negotiate at your store with no further coordination. The Pier39 MCP connector is one such shopper — install it in Claude Desktop and you can immediately negotiate at any negotiate.v1 storefront.

See also

• PROTOCOL.md — the formal protocol spec
• pier39-skills — the merchant + shopper Claude Agent Skills
• Atlas demo — full reference implementation

License

MIT.