# ktown agent discovery

ktown is a Vancouver-first group-buy marketplace for Korean sellers in Canada (CAD).

## Group-buy rules (for agents)

1. Sellers set a minimum unit count. Buyers join without being charged until the minimum is reached.
2. When the minimum is met, saved cards are charged. If the minimum is not met by the close date, nobody is charged.
3. Pickup areas are neighbourhood-level in API responses; exact private addresses are never exposed.

## REST public API

- OpenAPI: https://ktown.io/api/v1/public/openapi.json
- Human docs: https://ktown.io/api/v1/public/docs
- Listings: `GET https://ktown.io/api/v1/public/listings`
- One listing: `GET https://ktown.io/api/v1/public/listings/{id}`

## MCP server (read-only)

**URL:** https://ktown.io/api/mcp  
**Transport:** Streamable HTTP (POST for JSON-RPC; GET for SSE-less stateless clients per MCP 2025-03-26)

### Pre-connection discovery (SEP-2127)

| Resource | URL |
|----------|-----|
| AI Catalog | `https://ktown.io/.well-known/ai-catalog.json` |
| MCP Server Card | `https://ktown.io/api/mcp/server-card` |

Clients SHOULD fetch the AI Catalog first, then the Server Card, before opening a Streamable HTTP session.

### Tools

| Tool | Purpose |
|------|---------|
| `search_listings` | Filter/search active group buys (region, closing_soon, fulfillment, cursor pagination) |
| `get_listing` | Full listing detail including `urls.join` checkout link |
| `get_seller` | Storefront by public handle |

### Cursor / Claude Desktop (stdio bridge)

```json
{
  "mcpServers": {
    "ktown": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ktown.io/api/mcp"]
    }
  }
}
```

### Streamable HTTP client

```json
{
  "mcpServers": {
    "ktown": {
      "url": "https://ktown.io/api/mcp"
    }
  }
}
```

Rate limit: shared bucket with the public REST API (per IP). No authentication required for read tools.

## Stripe Agentic Commerce catalog feed

**URL:** `GET https://ktown.io/api/v1/public/catalog-feed.csv`

We export a [Stripe Agentic Commerce product feed](https://docs.stripe.com/agentic-commerce/product-feed) compatible CSV:

- **Format:** Product Master Feed CSV (same columns Stripe documents for SFTP/API ingestion).
- **Discovery-only:** every row includes `disable_checkout=true` so agents link buyers to ktown `link` URLs instead of in-agent checkout (required for CAD platform-charge model today).
- **Group buys:** `availability=preorder` with `availability_date` / `expiration_date` from campaign windows; `inventory_quantity` when a max unit cap exists.
- **Why CSV:** Stripe's Agentic Commerce Suite ingests tabular product master feeds; CSV matches their documented import path and OpenAI's product file spec.

## Machine-readable index

See also `https://ktown.io/llms.txt` and `https://ktown.io/llms-full.txt`.

## Privacy

Never expect buyer emails, exact pickup addresses, or payment identifiers in MCP, REST, or feed responses.