{"protocol":"Model Context Protocol (MCP)","protocolVersion":"2025-03-26","supportedProtocolVersions":["2025-03-26","2024-11-05"],"ucpSpecVersion":"2026-08-25","transport":"streamable-http","endpoint":"https://www.theofficeannex.com/api/mcp","serverInfo":{"name":"theofficeannex-mcp","title":"The Office Annex Commercial Print & Delegated Checkout MCP Server","version":"1.0.0","merchant":"The Office Annex","website":"https://www.theofficeannex.com"},"instructions":"REQUIRED 6-STEP AGENT ORDERING FLOW (product-first -> ask customer questions -> options -> artwork -> verify -> checkout): (1) Call get_product first (after search_products if needed) to read optionGroups and their values, sizes, sorted quantityTiers, requires_artwork_upload, artwork_spec, and workflowType before asking the customer anything. (2) Ask the customer for every required choice — product, size, quantity, and each optionGroup (e.g. Number of Sides: 1-Sided vs 2-sided, Paper Stock, Coating, Corners:, Production Time), plus customer name, email, shipping address, and phone. Do NOT silently accept server defaults — confirm them with the customer. (3) Call create_cart and add_to_cart with the selected options map (exact group names). add_to_cart echoes selected_options and reports missing_artwork_sides. (4) Artwork rule: check get_product -> requires_artwork_upload (or price_quote -> requires_artwork_upload) and add_to_cart -> missing_artwork_sides. If requires_artwork_upload is true (upload-your-own products): ask the customer for 1 print-ready file (front) when 1-sided, or 2 print-ready files (front and back) when 2-sided. Files must be 300 DPI, CMYK, 0.125-inch bleed (minimum 1125x675 px for 3.5x2 in). Relay exact preflight rejections to the customer; never invent or substitute artwork. If requires_artwork_upload is false (design-your-own and template products), no artwork upload is needed — the default template auto-attaches (or pass design.contact_information, design.text_layers, and design.qr_url to personalize). (5) Upload artwork via upload_artwork (passing cart_id + line_id + side: 'front' | 'back' to auto-attach, or passing front_artwork_id and back_artwork_id to add_to_cart), then call get_cart to verify ready_for_checkout is true and missing_artwork_sides is empty. Checkout will fail with ARTWORK_REQUIRED_BEFORE_CHECKOUT if any required side is missing. (6) Call checkout_guest (with idempotency_key and customer address) to create the live guest order and return the Phase 1 Delegated Checkout payment link (https://www.theofficeannex.com/pay/{orderId}) where the customer pays online via Card, Apple Pay, Google Pay, PayPal, or Venmo.","recommendedAgentFlow":["1. get_product first: read optionGroups, sizes, quantityTiers, requires_artwork_upload, artwork_spec, and workflowType before asking anything.","2. Ask the customer the questions: one per required optionGroup (Number of Sides, Paper Stock, Coating, Corners:, Production Time), plus quantity, size, and customer shipping/contact details. Never silently accept server defaults.","3. Select the options in add_to_cart (options map keyed by exact group name). Read echoed selected_options and missing_artwork_sides.","4. Ask for artwork based on the options selected: upload-your-own + 1-sided -> 1 file (front); upload-your-own + 2-sided -> 2 files (front and back); design-your-own / template -> optional personalization (contact_information, text_layers, qr_url) or default template as-is.","5. Upload with upload_artwork (cart_id + line_id + side, or pass front_artwork_id / back_artwork_id to add_to_cart), then verify with get_cart (ready_for_checkout: true, missing_artwork_sides: []).","6. Check out with checkout_guest -> customer pays the returned https://www.theofficeannex.com/pay/{orderId} link."],"capabilities":{"tools":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"prompts":{"listChanged":false},"delegatedCheckout":{"phase":"Phase 1 — Delegated Payment Link & Invoice Me","paymentUrlTemplate":"https://www.theofficeannex.com/pay/{orderId}","accountRequired":false,"cardDataHandledByAgent":false,"idempotencySupported":true}},"securityAndLimits":{"readToolsAuth":"public (no API key required)","writeToolsAuth":"public guest session with idempotency_key or optional Authorization Bearer agent key","rateLimitPerMinute":60,"maxOrderTotalUsd":2500,"maxDailyOrdersPerAgent":20,"auditLogEndpoint":"https://www.theofficeannex.com/api/mcp?action=audit_log"},"tools":[{"name":"search_products","description":"Search The Office Annex commercial print catalog by keyword or category slug. Returns matching active products with slug, SKU, price range, workflow type, and direct URL.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Search keyword (e.g. 'business cards', 'postcards', 'envelopes', 'drop cards', 'flyers')."},"category":{"type":"string","description":"Optional category slug filter (e.g. 'businesscards', 'postcards', 'envelopes', 'drop-cards', 'flyers')."},"max_results":{"type":"number","description":"Maximum products to return (default 20, max 84)."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"get_product","description":"Get full product configuration, sizes, sorted quantityTiers with unit prices, optionGroups, stock status, and customizable template fields by product slug.","inputSchema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","description":"Product slug (e.g. 'standard-bc', 'postcards', 'regular-10-envelope', 'quick-silver-money-drop-cards')."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"price_quote","description":"Calculate an exact price quote for a product, size, quantity tier, and options, including per-unit price, requires_artwork_upload + artwork_spec, live EasyShip carrier shipping rates (identical to get_shipping_quote) when destination_zip is provided, and state tax estimate.","inputSchema":{"type":"object","required":["slug","quantity"],"properties":{"slug":{"type":"string","description":"Product slug (e.g. 'standard-bc')."},"size":{"type":"string","description":"Optional size name (e.g. '4\" x 6\"', '6\" x 9\"', '$100 Drop Cards')."},"quantity":{"type":"number","description":"Exact tier quantity (e.g. 100, 250, 500, 1000, 2500, 5000)."},"options":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional map of option group name to selected option name."},"destination_country":{"type":"string","description":"ISO country code (default 'US')."},"destination_city":{"type":"string","description":"Optional destination city for live EasyShip carrier calculation."},"destination_state":{"type":"string","description":"2-letter US state code for tax/shipping calculation (e.g. 'FL')."},"destination_zip":{"type":"string","description":"5-digit US ZIP code for live EasyShip carrier shipping quote."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"get_shipping_quote","description":"Get live carrier shipping rates (USPS, UPS, FedEx via EasyShip) or the $8.99 domestic baseline fallback for a list of items and destination country/ZIP. International destinations return $0.00 with custom-quote payment link workflow.","inputSchema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["slug","quantity"],"properties":{"slug":{"type":"string"},"quantity":{"type":"number"},"size":{"type":"string"}}}},"destination_country":{"type":"string","description":"ISO country code (default 'US')."},"destination_city":{"type":"string","description":"Destination city."},"destination_state":{"type":"string","description":"Destination state/province."},"destination_zip":{"type":"string","description":"Destination postal/ZIP code."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"get_policies","description":"Retrieve official store policies (shipping turnaround & rates, 14-day print defect/damage guarantee, final-sale rules on custom/promotional items, pre-press cancellation window, terms, and privacy).","inputSchema":{"type":"object","properties":{"topic":{"type":"string","enum":["shipping","returns","terms","privacy","all"],"description":"Policy topic to retrieve (default 'all')."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"track_order","description":"Check live order status, payment state, payment URL, and shipment tracking numbers by order ID and customer email.","inputSchema":{"type":"object","required":["order_id","email"],"properties":{"order_id":{"type":"string","description":"Order reference number (e.g. '261005')."},"email":{"type":"string","description":"Customer email address associated with the order."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"create_cart","description":"Create a persistent MCP guest shopping cart session with an idempotency key for autonomous or delegated checkout.","inputSchema":{"type":"object","properties":{"idempotency_key":{"type":"string","description":"Optional client idempotency key to prevent duplicate cart creation on retry."},"customer_email":{"type":"string","description":"Optional customer email to associate with the cart."},"agent_id":{"type":"string","description":"Optional identifier of the calling AI agent."}}},"annotations":{"readOnlyHint":false,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"get_cart","description":"Retrieve the current state of an MCP guest shopping cart, including all line items, echoed selected_options, 1-sided vs 2-sided status, attached front/back artwork IDs, missing artwork sides, and whether the cart is ready for checkout_guest.","inputSchema":{"type":"object","required":["cart_id"],"properties":{"cart_id":{"type":"string","description":"Cart ID returned by create_cart."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"upload_artwork","description":"Validate and register customer print artwork (via file URL, base64 data, or metadata) against pre-press specifications: 300 DPI resolution, CMYK compatibility, 0.125-inch bleed, and accepted file formats (PDF, PNG, JPG, JPEG, TIFF, AI, PSD, EPS). Supports 1-sided and 2-sided orders: pass side ('front' or 'back') or cart_id to attach directly to the front/back of a cart item.","inputSchema":{"type":"object","properties":{"cart_id":{"type":"string","description":"Optional cart ID. If provided and the cart has a line item, the validated artwork automatically attaches to that line item's front side (first upload or side='front') or back side (second upload on a 2-sided item or side='back')."},"line_id":{"type":"string","description":"Optional specific cart line_id when cart_id has multiple items."},"product_slug":{"type":"string","description":"Optional target product slug (e.g. 'standard-bc', 'postcards')."},"side":{"type":"string","enum":["front","back"],"description":"Artwork side ('front' or 'back'). Defaults to 'front' (or 'back' if front is already attached on the target cart line)."},"artwork_side":{"type":"string","enum":["front","back"],"description":"Alias for 'side' ('front' or 'back')."},"file_url":{"type":"string","description":"Publicly accessible HTTPS URL of the print-ready artwork file."},"file_name":{"type":"string","description":"File name including extension (e.g. 'front-card.pdf' or 'back-card.png')."},"file_type":{"type":"string","description":"MIME type or file extension (PDF, PNG, JPG, TIFF)."},"file_base64":{"type":"string","description":"Optional base64-encoded file header/content for direct inspection."},"width_px":{"type":"number","description":"Artwork width in pixels (if known)."},"height_px":{"type":"number","description":"Artwork height in pixels (if known)."},"dpi":{"type":"number","description":"Artwork resolution in DPI (must be >= 300 DPI for print)."},"color_profile":{"type":"string","description":"Color profile (e.g. 'CMYK' or 'RGB')."},"has_bleed":{"type":"boolean","description":"Whether 0.125-inch bleed is included on all four sides."}}},"annotations":{"readOnlyHint":false,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"add_to_cart","description":"Add a configured print product (slug, size, quantity tier, options, template selection, template personalization across front/back/pages, mailing list CSV/TXT URL, or validated front/back artwork IDs) to an MCP cart. Echoes all recorded selected_options and front/back artwork IDs.","inputSchema":{"type":"object","required":["cart_id","slug","quantity"],"properties":{"cart_id":{"type":"string","description":"Cart ID returned by create_cart."},"slug":{"type":"string","description":"Product slug (e.g. 'standard-bc')."},"size":{"type":"string","description":"Optional size name if product has multiple sizes."},"quantity":{"type":"number","description":"Quantity tier value (e.g. 100, 250, 500, 1000)."},"options":{"type":"object","additionalProperties":{"type":"string"},"description":"Selected option values keyed by option group name (e.g. {\"Number of Sides\": \"2-sided\", \"Corners:\": \"Rounded\"})."},"template_id":{"type":"string","description":"Optional template ID when the product has multiple design templates (see designOptions.templates in get_product)."},"template_name":{"type":"string","description":"Optional template name when the product has multiple design templates."},"contact_information":{"type":"string","description":"Optional contact block text to print on template products (name, phone, email, website)."},"text_layers":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional key-value map of editable template text field names (or 'front:Field Name', 'back:Field Name') to custom strings."},"qr_url":{"type":"string","description":"Optional destination URL to encode into the template's dynamic QR code layer."},"image_layers":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional key-value map of editable template image slot names to image HTTPS URLs."},"mailing_list_url":{"type":"string","description":"Optional HTTPS URL to a .CSV or .TXT mailing list file when an 'Upload Addresses' option is selected."},"mailing_list_name":{"type":"string","description":"Optional file name for the mailing list (e.g. 'addresses.csv')."},"artwork_id":{"type":"string","description":"Optional validated front (or single-sided) artwork_id returned by upload_artwork."},"front_artwork_id":{"type":"string","description":"Optional validated front side artwork_id returned by upload_artwork."},"back_artwork_id":{"type":"string","description":"Optional validated back side artwork_id returned by upload_artwork (for 2-sided products)."},"artwork_ids":{"description":"Optional object { front: 'art_...', back: 'art_...' } or array ['art_front', 'art_back'] of validated artwork IDs.","oneOf":[{"type":"object","properties":{"front":{"type":"string"},"back":{"type":"string"}}},{"type":"array","items":{"type":"string"}}]},"design":{"type":"object","description":"Artwork or template personalization configuration. Supports 1-sided and 2-sided uploaded artwork and multi-side template fields.","properties":{"mode":{"type":"string","enum":["default_template","custom_text","uploaded_artwork"],"description":"Use 'default_template' or 'custom_text' for customizable template products, or 'uploaded_artwork' with artwork_id / front_artwork_id / back_artwork_id for upload-your-own products."},"template_id":{"type":"string","description":"Optional template ID when the product offers multiple templates."},"template_name":{"type":"string","description":"Optional template name when the product offers multiple templates."},"artwork_id":{"type":"string","description":"Validated front (or single-sided) artwork_id returned by upload_artwork."},"front_artwork_id":{"type":"string","description":"Validated front side artwork_id returned by upload_artwork."},"back_artwork_id":{"type":"string","description":"Validated back side artwork_id returned by upload_artwork (for 2-sided products)."},"artwork_ids":{"description":"Object { front: 'art_...', back: 'art_...' } or array ['art_front', 'art_back'] of validated artwork IDs.","oneOf":[{"type":"object","properties":{"front":{"type":"string"},"back":{"type":"string"}}},{"type":"array","items":{"type":"string"}}]},"contact_information":{"type":"string","description":"Contact block text to print on template products (name, phone, website)."},"text_layers":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value map of editable text layer names/indices (or 'front:Label', 'back:Label') to custom strings."},"qr_url":{"type":"string","description":"Destination URL to encode into the template's QR code layer."},"image_layers":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value map of editable image slot names to image HTTPS URLs."},"mailing_list_url":{"type":"string","description":"HTTPS URL to a .CSV or .TXT mailing list file when 'Upload Addresses' is selected."},"mailing_list_name":{"type":"string","description":"File name for the uploaded mailing list (e.g. 'addresses.csv')."}}}}},"annotations":{"readOnlyHint":false,"idempotentHint":false,"destructiveHint":false,"openWorldHint":false}},{"name":"checkout_guest","description":"Create an authoritative guest order from an MCP cart using Phase 1 Delegated Checkout (or Invoice Me). Never requires raw card numbers from the agent: returns a live order_id and a secure online payment link (https://www.theofficeannex.com/pay/{orderId}) where the customer completes payment, plus sends an invoice email notification. Enforces idempotency keys and spending caps.","inputSchema":{"type":"object","required":["cart_id","customer"],"properties":{"cart_id":{"type":"string","description":"Cart ID containing one or more items."},"idempotency_key":{"type":"string","description":"Idempotency key so retried checkout calls never create duplicate orders."},"shipping_method":{"type":"string","description":"Preferred shipping service name (e.g. 'Standard Ground', 'USPS Ground Advantage', 'UPS Ground')."},"payment_mode":{"type":"string","enum":["delegated_payment_link","invoice_me"],"description":"Defaults to 'delegated_payment_link' (creates order in PENDING - WAITING ON PAYMENT FROM CUSTOMER state and returns https://www.theofficeannex.com/pay/{orderId})."},"order_notes":{"type":"string","description":"Optional order or pre-press notes."},"customer":{"type":"object","required":["email","address","city","state","zip"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"company_name":{"type":"string"},"address":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string","description":"Defaults to 'US'."}}}}},"annotations":{"readOnlyHint":false,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}},{"name":"get_order","description":"Retrieve complete order details, line items, totals, payment state, delegated payment URL (/pay/{orderId}), and tracking info by order ID and customer email.","inputSchema":{"type":"object","required":["order_id","email"],"properties":{"order_id":{"type":"string","description":"Order reference ID (e.g. '261005')."},"email":{"type":"string","description":"Customer email address for verification."}}},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false}}],"quickStartExamples":{"jsonRpcInitialize":{"method":"POST","url":"https://www.theofficeannex.com/api/mcp","body":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example-agent","version":"1.0.0"}}}},"jsonRpcCallPriceQuote":{"method":"POST","url":"https://www.theofficeannex.com/api/mcp","body":{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"price_quote","arguments":{"slug":"standard-bc","quantity":250,"destination_state":"FL","destination_zip":"33412"}}}}}}