# OrignaGTA MCP Server — AI-Readable Documentation

## Overview
OrignaGTA is a Model Context Protocol (MCP) server for a Canadian e-commerce marketplace. AI agents can search products, manage shopping carts, apply coupons, and **purchase items directly using Stripe** with automatic tax calculation and real-time shipping.

**Status**: Production-Ready  
**Version**: 1.0.0  
**Last Updated**: March 2026

---

## Quick Facts

- **14 Tools**: Search, cart, checkout, orders, returns, reviews, analytics
- **Stripe Integration**: Embedded checkout with automatic tax, shipping rates, multiple payment methods
- **Security**: JWT authentication, role-based access (Admin/Seller/Buyer), PII redaction in logs
- **Money**: All values in integer cents (2999 = $29.99 CAD)
- **Region**: Canada (postal code validation, HST/GST/PST)
- **Language**: TypeScript/Node.js

---

## Tool Reference

### Search & Browse Tools

#### search_products
Search the product catalog with filters.

**Input:**
```json
{
  "query": "string (required) — search keywords",
  "category": "string (optional) — filter by category",
  "min_price": "number (optional) — minimum price in cents",
  "max_price": "number (optional) — maximum price in cents",
  "sort": "string (optional) — 'price_asc', 'price_desc', 'newest', 'popular'",
  "limit": "number (optional, 1-100, default 20) — results per page",
  "offset": "number (optional, default 0) — pagination offset"
}
```

**Output:**
```json
{
  "items": [
    {
      "id": "products:abc123",
      "title": "Laptop Pro",
      "priceCents": 129900,
      "imageUrls": ["https://..."],
      "stockQuantity": 25,
      "categoryId": "electronics",
      "rating": 4.8,
      "reviewCount": 156
    }
  ],
  "total": 45,
  "limit": 20,
  "offset": 0
}
```

**Notes:**
- Searches across product title, description, keywords
- Prices returned in integer cents (divide by 100 for display)
- Filters are AND-combined (category AND price range)
- Always paginate; use limit + offset

---

#### get_product
Retrieve detailed product information.

**Input:**
```json
{
  "id": "string (required) — product ID (e.g., 'products:abc123')"
}
```

**Output:**
```json
{
  "id": "products:abc123",
  "title": "Laptop Pro",
  "description": "High-performance laptop with...",
  "priceCents": 129900,
  "imageUrls": ["https://...", "https://..."],
  "stockQuantity": 25,
  "categoryId": "electronics",
  "sellerId": "users:seller456",
  "seller": {
    "name": "TechStore Inc",
    "rating": 4.9,
    "reviewCount": 523
  },
  "rating": 4.8,
  "reviewCount": 156,
  "reviews": [
    {
      "rating": 5,
      "comment": "Excellent quality!",
      "author": "Anonymous",
      "dateCreated": 1710763200
    }
  ],
  "specifications": {
    "processor": "Intel i7",
    "ram": "16GB",
    "storage": "512GB SSD"
  },
  "dateCreated": 1710763200
}
```

---

#### check_inventory
Real-time inventory check.

**Input:**
```json
{
  "product_id": "string (required) — product ID",
  "quantity": "number (optional, default 1) — quantity to check"
}
```

**Output:**
```json
{
  "product_id": "products:abc123",
  "available": true,
  "stock_quantity": 25,
  "requested_quantity": 1,
  "message": "In stock"
}
```

---

### Shopping Cart Tools

#### add_to_cart
Add items to the shopping cart.

**Input:**
```json
{
  "product_id": "string (required) — product ID",
  "quantity": "number (required) — quantity (≥ 1)",
  "variant": "string (optional) — variant/SKU if applicable"
}
```

**Output:**
```json
{
  "product_id": "products:abc123",
  "quantity": 1,
  "added": true,
  "cart": {
    "items": [...],
    "itemCount": 1,
    "subtotalCents": 129900,
    "taxAmountCents": 16887,
    "shippingCostCents": 0,
    "totalAmountCents": 146787
  }
}
```

---

#### remove_from_cart
Remove items from the cart.

**Input:**
```json
{
  "product_id": "string (required) — product ID to remove",
  "quantity": "number (optional, default all) — quantity to remove"
}
```

**Output:**
```json
{
  "removed": true,
  "quantity_removed": 1,
  "cart": {
    "items": [],
    "itemCount": 0,
    "subtotalCents": 0,
    "taxAmountCents": 0,
    "totalAmountCents": 0
  }
}
```

---

#### get_cart
Retrieve the current shopping cart.

**Input:**
```json
{}
```

**Output:**
```json
{
  "items": [
    {
      "product_id": "products:abc123",
      "title": "Laptop Pro",
      "quantity": 1,
      "unit_price_cents": 129900,
      "line_total_cents": 129900,
      "image_url": "https://..."
    }
  ],
  "itemCount": 1,
  "subtotalCents": 129900,
  "taxAmountCents": 16887,
  "shippingCostCents": 0,
  "coupon_applied": null,
  "discount_cents": 0,
  "totalAmountCents": 146787,
  "lastUpdated": 1710763200
}
```

---

### Discounts & Coupons

#### apply_coupon
Apply a discount code to the cart.

**Input:**
```json
{
  "code": "string (required) — coupon code (e.g., 'SAVE15')"
}
```

**Output:**
```json
{
  "applied": true,
  "code": "SAVE15",
  "discount_cents": 19485,
  "discount_percent": 15,
  "new_total_cents": 127302,
  "expiration_date": "2026-12-31",
  "terms": "15% off orders over $50"
}
```

---

### Checkout & Payments

#### create_checkout
**THE PRIMARY TOOL FOR AGENTS TO MAKE PURCHASES** — Creates a Stripe Checkout Session with latest features.

**Input:**
```json
{
  "shipping_address": {
    "street": "string (required) — street address",
    "city": "string (required) — city",
    "province": "string (required) — 2-letter province code (ON, BC, AB, etc.)",
    "postalCode": "string (required) — format: 'A1A 1A1'",
    "country": "string (required) — must be 'CA' for Canada",
    "phone": "string (required) — E.164 format: '+1XXXXXXXXXX'"
  },
  "coupon": "string (optional) — discount code"
}
```

**Output:**
```json
{
  "sessionId": "cs_test_...",
  "sessionUrl": "https://checkout.stripe.com/pay/cs_test_...",
  "clientSecret": "...",
  "publishableKey": "pk_test_...",
  "subtotalCents": 129900,
  "taxAmountCents": 16887,
  "shippingCostCents": 0,
  "discountCents": 0,
  "totalCents": 146787,
  "status": "ready_for_payment",
  "paymentMethods": ["card", "link", "cash_app", "afterpay_clearpay"],
  "expiresAt": 1710776400
}
```

**Features:**
- Embedded checkout (`ui_mode: 'embedded'`)
- Automatic tax (Canadian HST/GST/PST)
- Real-time shipping rate calculation
- Multiple payment methods: Card, Stripe Link, Cash App, Afterpay/Clearpay
- Idempotent requests (safe to retry)
- Webhook confirms payment (order created in backend)

**Key Notes:**
- Address must be valid Canadian postal code format: `M5V 3A8`
- Phone must be E.164: `+14165551234`
- Agent should display `sessionUrl` to user for payment
- Stripe webhook creates order after successful payment
- No order created until webhook confirms `payment_intent.succeeded`

---

### Order Management

#### list_orders
View order history with filtering.

**Input:**
```json
{
  "status": "string (optional) — 'pending', 'confirmed', 'shipped', 'delivered', 'cancelled'",
  "limit": "number (optional, 1-100, default 20)",
  "offset": "number (optional, default 0)",
  "sort": "string (optional, default 'newest') — 'newest' or 'oldest'"
}
```

**Output:**
```json
{
  "orders": [
    {
      "id": "orders:order123",
      "buyerId": "users:buyer456",
      "status": "confirmed",
      "totalAmountCents": 146787,
      "itemCount": 1,
      "createdAt": 1710763200,
      "estimatedDelivery": "2026-03-25"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}
```

---

#### get_order
Retrieve detailed order information.

**Input:**
```json
{
  "id": "string (required) — order ID (e.g., 'orders:abc123')"
}
```

**Output:**
```json
{
  "id": "orders:order123",
  "buyerId": "users:buyer456",
  "sellerId": "users:seller789",
  "status": "confirmed",
  "items": [
    {
      "productId": "products:xyz",
      "name": "Laptop Pro",
      "quantity": 1,
      "unitPriceCents": 129900,
      "imageUrl": "https://..."
    }
  ],
  "subtotalCents": 129900,
  "taxAmountCents": 16887,
  "shippingCostCents": 0,
  "discountCents": 0,
  "platformFeeCents": 6495,
  "totalAmountCents": 146787,
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Toronto",
    "province": "ON",
    "postalCode": "M5V 3A8",
    "country": "CA"
  },
  "trackingNumber": null,
  "createdAt": 1710763200,
  "confirmedAt": 1710763200,
  "shippedAt": null,
  "deliveredAt": null,
  "paymentIntentId": "pi_test_...",
  "refundRequested": false
}
```

---

#### request_return
Initiate a return/refund request.

**Input:**
```json
{
  "order_id": "string (required) — order ID",
  "reason": "string (required) — 'damaged', 'wrong_item', 'not_as_described', 'other'",
  "description": "string (optional) — additional details",
  "items": "array (optional) — specific product IDs to return (if partial return)"
}
```

**Output:**
```json
{
  "return_id": "returns:ret123",
  "order_id": "orders:order123",
  "status": "pending",
  "reason": "damaged",
  "created_at": 1710763200,
  "window_closes_at": 1713441600,
  "estimated_refund_amount_cents": 146787,
  "message": "Return request received. Seller will review within 2 business days."
}
```

---

### Reviews

#### submit_review
Submit a product review.

**Input:**
```json
{
  "product_id": "string (required) — product ID",
  "rating": "number (required) — 1-5 stars",
  "title": "string (optional) — review title",
  "comment": "string (optional) — review text",
  "order_id": "string (optional) — link to order (verified purchase)"
}
```

**Output:**
```json
{
  "review_id": "reviews:rev123",
  "product_id": "products:abc123",
  "rating": 5,
  "title": "Excellent quality!",
  "comment": "Great laptop, highly recommend",
  "verified_purchase": true,
  "published": true,
  "created_at": 1710763200
}
```

---

### Analytics (Admin Only)

#### get_analytics
Sales and performance analytics. **Requires admin role.**

**Input:**
```json
{
  "period": "string (optional) — 'day', 'week', 'month', 'year'",
  "start_date": "string (optional) — ISO date '2026-03-01'",
  "end_date": "string (optional) — ISO date '2026-03-31'"
}
```

**Output:**
```json
{
  "period": "month",
  "total_revenue_cents": 1500000,
  "total_orders": 42,
  "average_order_value_cents": 35714,
  "total_items_sold": 98,
  "top_products": [
    {
      "product_id": "products:abc123",
      "title": "Laptop Pro",
      "units_sold": 15,
      "revenue_cents": 1948500
    }
  ],
  "top_sellers": [
    {
      "seller_id": "users:seller789",
      "name": "TechStore Inc",
      "revenue_cents": 750000,
      "orders": 21
    }
  ],
  "conversion_rate": 3.2,
  "returning_customers": 18,
  "new_customers": 24
}
```

---

## Authentication

All requests require a valid JWT token issued by OrignaBase.

### Get JWT Token

```bash
curl -X POST https://api.dev.orignagta.ca/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'
```

Response:
```json
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "users:abc123",
  "role": "buyer"
}
```

### Using the Token

Include in all MCP tool requests:
```
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Token Details
- **Algorithm**: RS256 (RSA signature verification)
- **Lifetime**: Short-lived (refresh handled by MCP server)
- **Claims**: `sub` (user ID), `role` (admin/seller/buyer), `iat`, `exp`
- **Roles**:
  - `buyer` — search, cart, checkout, order history, reviews
  - `seller` — manage products, view sales, analytics
  - `admin` — all operations, analytics across sellers

---

## Environment URLs

| Environment | API URL |
|---|---|
| **Development** | `https://api.dev.orignagta.ca` |
| **Staging** | `https://api.staging.orignagta.ca` |
| **Production** | `https://api.orignagta.ca` |

Test accounts (dev/staging only):
- Admin: `e2e-admin@test.origna.ca` / `TestPass123!`
- Seller: `e2e-seller@test.origna.ca` / `TestPass123!`
- Buyer: `e2e-buyer@test.origna.ca` / `TestPass123!`

---

## Data Format Reference

### Money & Pricing
All monetary values are **integer cents**:
- `2999` cents = `$29.99` CAD
- `129900` cents = `$1,299.00` CAD
- No floats or decimals — prevents rounding errors
- Display: Divide by 100 and format with 2 decimal places

### Timestamps
Unix timestamps (seconds since epoch):
- `1710763200` = March 18, 2026, 14:00:00 UTC

### Product IDs & References
SurrealDB format: `collection:record_id`
- `products:abc123xyz`
- `users:buyer456def`
- `orders:order789ghi`

### Canadian Postal Code Format
Validation: `[A-Z]\d[A-Z] \d[A-Z]\d`
- Valid: `M5V 3A8`, `V6B 4Z1`, `T2P 1M1`
- Invalid: `m5v 3a8` (must be uppercase), `M5V3A8` (missing space)

### Phone Format (E.164)
- Format: `+1XXXXXXXXXX`
- Examples: `+14165551234` (Canada)
- Must start with `+1` for North America

### Address Fields
- `street` — Street address (required)
- `city` — City name (required)
- `province` — 2-letter code: ON, BC, AB, MB, SK, NS, NB, PE, NL, QC, YT, NT, NU (required)
- `postalCode` — Format `A1A 1A1` (required)
- `country` — Must be `CA` (required)
- `phone` — E.164 format (required)

---

## Error Responses

All errors return JSON with standard fields:

```json
{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "statusCode": 400
}
```

### Common Error Codes

| Code | HTTP | Meaning |
|------|------|---------|
| `VALIDATION_ERROR` | 400 | Invalid input (bad postal code, price range, etc.) |
| `AUTH_ERROR` | 401 | Missing or invalid JWT token |
| `AUTHZ_ERROR` | 403 | Insufficient permissions (e.g., non-admin accessing admin tool) |
| `NOT_FOUND` | 404 | Product/order/user doesn't exist |
| `CONFLICT` | 409 | Business logic violation (e.g., out of stock, return window closed) |
| `RATE_LIMIT` | 429 | Too many requests — wait before retrying |
| `STRIPE_ERROR` | 400 | Stripe API error (payment declined, invalid address, etc.) |
| `INTERNAL_ERROR` | 500 | Server error — report to support |

### Error Handling Best Practices
- Always check `statusCode` for HTTP status
- Retry on `RATE_LIMIT` (429) with exponential backoff
- Do NOT retry on `AUTH_ERROR` — token may be invalid
- For `NOT_FOUND` — verify product/order ID exists
- For `AUTHZ_ERROR` — check user role has permission for this tool

---

## Rate Limits

| Endpoint Category | Limit | Window |
|---|---|---|
| Authentication | 5 requests | 1 minute |
| Search / Browse | 30 requests | 1 minute |
| Cart Operations | 20 requests | 1 minute |
| Checkout | 10 requests | 1 minute |
| Orders | 20 requests | 1 minute |

Exceeding limits returns `429 Too Many Requests` with `Retry-After` header.

---

## Integration Examples

### Example 1: Search and Purchase Flow

```
Agent: "Find a laptop under $2000, add to cart, apply WELCOME20, and checkout to Toronto, ON"

1. search_products(
     query="laptop",
     max_price=200000
   )
   → Returns 5 products

2. get_product(id="products:xyz789")
   → Verify price, stock, reviews

3. add_to_cart(
     product_id="products:xyz789",
     quantity=1
   )
   → Cart: subtotal=$1299, tax=$169, total=$1468

4. apply_coupon(code="WELCOME20")
   → Discount: $260, new total=$1208

5. create_checkout(
     shipping_address={
       street: "456 Yonge St",
       city: "Toronto",
       province: "ON",
       postalCode: "M4Y 1Z5",
       country: "CA",
       phone: "+14165551234"
     },
     coupon: "WELCOME20"
   )
   → Returns Stripe Checkout URL

User visits checkout URL → Payment confirmed → Webhook creates order
```

### Example 2: Order Tracking and Return

```
Agent: "Show me my recent orders and check if I can return the laptop"

1. list_orders(
     status="delivered",
     limit=10
   )
   → Shows 3 delivered orders

2. get_order(id="orders:order123")
   → Laptop order: delivered March 10, eligible for return until April 9

3. request_return(
     order_id="orders:order123",
     reason="damaged",
     description: "Screen has dead pixels"
   )
   → Return request created, waiting seller review
```

---

## Discovery & Integration

### .well-known/mcp.json
Machine-readable discovery manifest at `/.well-known/mcp.json`

### llms.txt Standard
This file follows the [llms.txt specification](https://llmstxt.org) for AI-readable documentation. AI agents can discover and parse this document to understand available tools.

### MCP Configuration
For Claude Desktop, Claude Web, and other MCP-compatible clients:
```json
{
  "mcpServers": {
    "orignagta": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "ORIGNABASE_URL": "https://api.dev.orignagta.ca",
        "ORIGNABASE_JWT_TOKEN": "your-token"
      }
    }
  }
}
```

---

## Security & Privacy

- **PII Protection**: No email addresses, phone numbers, or addresses logged in plaintext
- **HTTPS Only**: All API calls encrypted in transit
- **JWT Verification**: RS256 signature verified on every request
- **Rate Limiting**: Protects against abuse and DDoS
- **Input Validation**: All parameters sanitized before processing
- **Error Messages**: No internal stack traces or secrets revealed
- **Idempotency**: Retry-safe via `Idempotency-Key` headers (prevents duplicate charges)

---

## Support & Documentation

**Full Technical Documentation**
- [README.md](https://mcp.docs.orignagta.ca) — Complete API reference
- [ARCHITECTURE.md](https://mcp.docs.orignagta.ca/api-reference/architecture) — System design
- [QUICK_START.md](https://mcp.docs.orignagta.ca/getting-started) — 5-minute setup guide

**Source Code**
- [GitHub Repository](https://github.com/yunior123/origna_gta/tree/main/mcp-server)

**Support Contacts**
- Issues: GitHub Issues
- Questions: support@orignagta.ca

---

**Ready to build AI agents that can purchase products!** 🚀  
Last updated: March 2026