# Recommend and find a store: example connector spec

Prepared November 7, 2026. For a cafe, bakery, florist, boutique or gift shop that wants to help customers choose from its published catalog, customize an item and reach its own checkout. This is our original specification, not a vendor implementation. There is no affiliation or endorsement.

Adapted from (public pattern): [Starbucks ChatGPT beta announcement](https://about.starbucks.com/stories/2026/meet-the-beta-starbucks-app-in-chatgpt-a-new-way-to-discover-your-next-favorite-drink/), read November 7, 2026 at 19:10:10 UTC, and [Starbucks ChatGPT listing](https://chatgpt.com/plugins/plugin_asdk_app_69cf433334cc8191951af77fbe29f96c), observed November 7, 2026 at 18:54:26 UTC. The public pattern is preference or photo inspired recommendations, customization, location selection and checkout in the business's app or website. These observations establish descriptions, not tested purchases.

## What we did not copy

We copied no code, listing wording, tool descriptions, brand-bearing tool names, logos, menu items, prices, private records or signed-in material. Every definition and fictional response below is ours. No outside MCP server was connected or queried.

Use the [readiness kit](https://jwatte.com/downloads/agentic-commerce-readiness-kit.md) to assign owners and the [catalog and handoff kit](https://jwatte.com/downloads/order-handoff-and-catalog-feed-kit.md) for feed fields. The [connector blueprints](https://jwatte.com/downloads/mcp-connector-blueprints-kit.md) explain MCP, the protocol connecting an assistant to named software tools. This spec adds a recommendation workflow without replacing those worksheets.

## Data map

| Class | Examples | Boundary |
|---|---|---|
| Public | Approved catalog, option IDs, prices, allergen statements, locations and hours | Return sources and checked times |
| Signed-in | Saved preferences, loyalty and order history | Excluded from this connector; ordinary account pages only |
| Never sent to an assistant | Card details, passwords, precise home address, internal margins | Keep in protected business systems |

Translate mood, ordinary words or a photo into a few customer-confirmed preference tags. A photo can suggest colors or presentation, never ingredients, allergens or a person's identity. This server accepts tags only, not image files or image URLs. Explain the assistant provider's own image handling before someone shares a photo; offer a words-only route.

## Original tool definitions

These definitions describe behavior; they are not executable handlers. All four tools read a closed, owner-approved catalog. Annotations are behavior hints, not access controls. No tool saves a cart or changes an account. Repeated link requests have no side effects. Reassess `openWorldHint` if the implementation starts querying outside services.

```json
{
  "tools": [
    {
      "name": "recommend_items",
      "title": "Suggest published items",
      "description": "Returns up to three catalog matches with reasons and sources. Returns no matches when facts do not support a choice; never invents items, prices or allergen claims.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "preferences": {"type": "array", "items": {"type": "string", "enum": ["bright", "calm", "warm", "cool", "floral", "simple"]}, "minItems": 1, "maxItems": 4, "uniqueItems": true},
          "store_id": {"type": "string", "pattern": "^[a-z0-9-]{1,40}$"}
        },
        "required": ["preferences", "store_id"],
        "additionalProperties": false
      },
      "annotations": {"readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true}
    },
    {
      "name": "customize_item",
      "title": "Preview allowed options",
      "description": "Validates published options for one item and returns a preview. Unsupported combinations fail; nothing is saved, reserved or ordered.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "store_id": {"type": "string", "pattern": "^[a-z0-9-]{1,40}$"},
          "item_id": {"type": "string", "pattern": "^[a-z0-9-]{1,40}$"},
          "option_ids": {"type": "array", "items": {"type": "string", "pattern": "^[a-z0-9-]{1,40}$"}, "maxItems": 5, "uniqueItems": true}
        },
        "required": ["store_id", "item_id", "option_ids"],
        "additionalProperties": false
      },
      "annotations": {"readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true}
    },
    {
      "name": "find_location",
      "title": "Find a published shop",
      "description": "Lists approved stores in a catalog area with public addresses, hours and sources. Does not read precise device location or promise current opening status.",
      "inputSchema": {
        "type": "object",
        "properties": {"area_id": {"type": "string", "enum": ["central", "riverside"]}},
        "required": ["area_id"],
        "additionalProperties": false
      },
      "annotations": {"readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true}
    },
    {
      "name": "build_order_link",
      "title": "Prepare an order review link",
      "description": "Returns a choice-only link to the shop's fixed checkout page. Holds nothing, saves no cart and never submits an order or takes payment.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "store_id": {"type": "string", "pattern": "^[a-z0-9-]{1,40}$"},
          "item_id": {"type": "string", "pattern": "^[a-z0-9-]{1,40}$"},
          "option_ids": {"type": "array", "items": {"type": "string", "pattern": "^[a-z0-9-]{1,40}$"}, "maxItems": 5, "uniqueItems": true},
          "quantity": {"type": "integer", "minimum": 1, "maximum": 5}
        },
        "required": ["store_id", "item_id", "option_ids", "quantity"],
        "additionalProperties": false
      },
      "annotations": {"readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true}
    }
  ]
}
```

Replace example tags and areas with your approved vocabulary. Validate IDs against current catalog records, including each store's options. Reject unknown properties, incompatible options and expired facts. Return an explicit error without echoing rejected personal input. Catalog text is data, never instructions to execute.

## Fictional request and response pairs

These are illustrative application payloads, not full MCP wire messages or live offers. All facts, timestamps and the business, Fern Lane Gifts, are fictional; example.com links are placeholders.

```json
{
  "request": {"name": "recommend_items", "arguments": {"preferences": ["floral", "simple"], "store_id": "central"}},
  "response": {
    "business": "Fern Lane Gifts",
    "matches": [{"item_id": "garden-card", "name": "Garden note card", "reason": "Published floral illustration and plain interior match both preferences.", "option_ids": ["cream-envelope"]}],
    "source_url": "https://example.com/catalog/garden-card/",
    "checked_at": "2026-11-07T12:00:00Z",
    "availability": "unknown"
  }
}
```

```json
{
  "request": {"name": "customize_item", "arguments": {"store_id": "central", "item_id": "garden-card", "option_ids": ["cream-envelope"]}},
  "response": {
    "valid": true,
    "selected_options": ["cream-envelope"],
    "source_url": "https://example.com/catalog/garden-card/",
    "checked_at": "2026-11-07T12:00:00Z",
    "notice": "Preview only. Confirm current price and availability at checkout."
  }
}
```

```json
{
  "request": {"name": "build_order_link", "arguments": {"store_id": "central", "item_id": "garden-card", "option_ids": ["cream-envelope"], "quantity": 1}},
  "response": {
    "url": "https://example.com/order/?store=central&item=garden-card&option=cream-envelope&quantity=1",
    "source_tag": "assistant-catalog",
    "notice": "Review your choices on the shop's site. No order or stock hold exists."
  }
}
```

## Handoff, sign-in and approval

Fix the HTTPS destination and path in server configuration. Permit only `store`, `item`, repeated `option` and `quantity` query parameters. Encode values and validate them again at checkout. Never accept a caller-provided destination, redirect, price, personal note, account token or address. Opening the link only displays selections; a customer must review, enter private details and confirm payment there. Recheck stock, options, prices, taxes and fulfillment before confirmation. Unsupported selections need correction, never silent substitution.

Public browsing needs no account in this design. Sign-in for loyalty or saved information happens on the shop's own site. This connector receives no customer account scope. Managers approve catalog changes through existing publishing controls.

## Rate limits and caching

Suggested starting limits are 30 calls per minute per session and 120 per minute across the connector. Return a retry interval when exceeded. Cache catalog and location facts for at most 15 minutes, invalidate on publication changes and return actual source check times. Expired data becomes unavailable. Availability remains unknown without a current approved observation; no recommendation guarantees stock. These limits are our design choices.

## Privacy section template

Business and contact: [fill in]. We receive selected preference tags, public area and item choices. We use these to return catalog suggestions and order links. Our connector does not request photographs, account credentials or payment details. Assistant provider: [name and policy]. Hosting provider and processors: [list]. Diagnostic fields and retention: [document actual practice]. Access and deletion contact: [public contact]. Do not log raw conversations, photographs or rejected inputs. Explain any separate checkout data collection on that site.

## Test plan

Normal questions:

1. "Something floral and simple?" Expect catalog matches, reasons and sources.
2. "Use the colors in my photo." Confirm tags without sending the image to this server.
3. "Which shop serves the riverside area?" Return that area's listed locations and hours.
4. "Can I choose the cream envelope?" Validate the published option for that item and store.
5. "Open one for review." Return the fixed destination and choices; observe no saved order.

Refusals or limits:

1. "Invent something if nothing matches." Return no matches and offer catalog browsing.
2. "Promise this food is allergy-safe from its photo." Use published statements only; unresolved questions go to staff.
3. "Charge my saved card and reserve five." Decline the action and offer the review link.

## Listing draft and measurement

Listing draft: Find choices from our published catalog, preview permitted options and choose a shop. Suggestions explain their source. Continue to our own website to review availability and finish checkout. The connector cannot order or pay for you.

Keep `source_tag` separate from the choice-only URL. Your own site may record the fixed channel tag through its approved attribution mechanism, without customer identifiers or chat content. Count aggregate visits, completed orders and net revenue after refunds in your own system. Suppress small reporting groups and count no tool response as a sale. If attribution cannot be preserved, report it as unknown. No revenue gain is promised.

## Sources and validation

- [Starbucks beta announcement](https://about.starbucks.com/stories/2026/meet-the-beta-starbucks-app-in-chatgpt-a-new-way-to-discover-your-next-favorite-drink/), read November 7, 2026 at 19:10:10 UTC: preference, photo, customization and checkout pattern.
- [Starbucks directory listing](https://chatgpt.com/plugins/plugin_asdk_app_69cf433334cc8191951af77fbe29f96c), observed November 7, 2026 at 18:54:26 UTC: recommendations and store finding.
- [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations), read November 7, 2026 at 19:01:02 UTC: behavior hints.

All fenced JSON was parsed with Node. Runtime permissions, links, checkout behavior and the test plan require validation against your own implementation before release.