feat: add MCP tools and complete product feed spec

packages/sdk/package.json

@@ -21,6 +21,8 @@
 		"commerce",
 		"checkout",
 		"product-feed",
+		"mcp",
+		"model-context-protocol",
 		"ai",
 		"chatgpt",
 		"openai",
@@ -49,6 +51,10 @@
 			"types": "./dist/feed/next/index.d.ts",
 			"import": "./dist/feed/next/index.js"
 		},
+		"./mcp": {
+			"types": "./dist/mcp/index.d.ts",
+			"import": "./dist/mcp/index.js"
+		},
 		"./test": {
 			"types": "./dist/test/index.d.ts",
 			"import": "./dist/test/index.js"

packages/sdk/src/feed/types.ts

@@ -179,7 +179,9 @@ export const ProductFeedItemSchema = z.object({
 	// Availability & Inventory
 	availability_date: z.string().datetime().optional(),
 	expiration_date: z.string().datetime().optional(),
-	pickup_method: z.enum(["buy_online_pickup_in_store", "curbside", "in_store"]).optional(),
+	pickup_method: z
+		.enum(["buy_online_pickup_in_store", "curbside", "in_store"])
+		.optional(),
 	pickup_sla: z.string().optional(), // e.g., "1 hour", "same day"
 
 	// Variants & Item Groups
@@ -232,7 +234,12 @@ export const ProductFeedItemSchema = z.object({
 	// Related Products
 	related_product_ids: z.array(z.string()).optional(),
 	relationship_type: z
-		.enum(["often_bought_with", "similar_to", "accessories_for", "alternative_to"])
+		.enum([
+			"often_bought_with",
+			"similar_to",
+			"accessories_for",
+			"alternative_to",
+		])
 		.optional(),
 
 	// Reviews & Q&A

packages/sdk/src/mcp/handlers.ts

@@ -0,0 +1,184 @@
+/**
+ * Configuration for creating MCP handlers
+ */
+export interface HandlerConfig {
+	/**
+	 * Base URL of your store's API (e.g., 'https://mystore.com')
+	 */
+	baseUrl: string;
+
+	/**
+	 * Optional headers to include in all requests (e.g., auth tokens)
+	 */
+	headers?: Record<string, string>;
+
+	/**
+	 * Optional fetch implementation (useful for testing or custom logic)
+	 */
+	fetch?: typeof fetch;
+
+	/**
+	 * Function to generate checkout URL for a session.
+	 * Used when completeCheckout is called without a payment token (MCP context).
+	 * Defaults to `${baseUrl}/checkout/${sessionId}` if not provided.
+	 *
+	 * @example
+	 * ```typescript
+	 * getCheckoutUrl: (sessionId) => `https://mystore.com/checkout/${sessionId}`
+	 * ```
+	 */
+	getCheckoutUrl?: (sessionId: string) => string;
+}
+
+/**
+ * Create handlers that call your acp-handler API endpoints
+ *
+ * @example
+ * ```typescript
+ * const handlers = createHandlers({
+ *   baseUrl: 'https://mystore.com',
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * server.registerTool(
+ *   'search_products',
+ *   tools.searchProducts,
+ *   handlers.searchProducts
+ * );
+ * ```
+ */
+export function createHandlers(config: HandlerConfig) {
+	const { baseUrl, headers = {}, fetch: customFetch = fetch } = config;
+
+	const request = async (
+		path: string,
+		options: RequestInit = {},
+	): Promise<unknown> => {
+		const url = `${baseUrl}${path}`;
+		const response = await customFetch(url, {
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...headers,
+				...options.headers,
+			},
+		});
+
+		if (!response.ok) {
+			const error = await response.json().catch(() => ({
+				message: response.statusText,
+			}));
+			throw new Error(
+				`API request failed: ${error.message || response.statusText}`,
+			);
+		}
+
+		return response.json();
+	};
+
+	return {
+		/**
+		 * Search for products in the catalog
+		 */
+		searchProducts: async (input: {
+			query: string;
+			category?: string;
+			limit?: number;
+		}): Promise<unknown> => {
+			const params = new URLSearchParams({
+				q: input.query,
+			});
+
+			if (input.category) {
+				params.set("category", input.category);
+			}
+
+			if (input.limit) {
+				params.set("limit", String(input.limit));
+			}
+
+			return request(`/api/products/search?${params}`);
+		},
+
+		/**
+		 * Get detailed information about a specific product
+		 */
+		getProduct: async (input: { product_id: string }): Promise<unknown> => {
+			return request(`/api/products/${input.product_id}`);
+		},
+
+		/**
+		 * Create a new checkout session
+		 */
+		createCheckout: async (input: any): Promise<unknown> => {
+			return request("/api/checkout", {
+				method: "POST",
+				body: JSON.stringify(input),
+			});
+		},
+
+		/**
+		 * Update an existing checkout session
+		 */
+		updateCheckout: async (input: any): Promise<unknown> => {
+			const { session_id, ...body } = input;
+			return request(`/api/checkout/${session_id}`, {
+				method: "POST",
+				body: JSON.stringify(body),
+			});
+		},
+
+		/**
+		 * Complete a checkout session and process payment.
+		 * In MCP context (no payment token), returns checkout URL for user to complete payment.
+		 * In ACP context (with payment token), processes payment directly.
+		 */
+		completeCheckout: async (input: any): Promise<unknown> => {
+			const { session_id, customer, payment } = input;
+
+			// MCP context: no payment token provided
+			// Return checkout URL for user to complete payment on merchant site
+			if (!payment?.token) {
+				const checkoutUrl = config.getCheckoutUrl
+					? config.getCheckoutUrl(session_id)
+					: `${config.baseUrl}/checkout/${session_id}`;
+
+				return {
+					checkout_url: checkoutUrl,
+					session_id,
+					status: "pending_payment",
+					message: "Complete your purchase at the checkout link",
+				};
+			}
+
+			// ACP context: payment token provided
+			// Process payment through ACP complete endpoint
+			return request(`/api/checkout/${session_id}/complete`, {
+				method: "POST",
+				body: JSON.stringify({ customer, payment }),
+			});
+		},
+
+		/**
+		 * Cancel a checkout session
+		 */
+		cancelCheckout: async (input: { session_id: string }): Promise<unknown> => {
+			const { session_id } = input;
+			return request(`/api/checkout/${session_id}/cancel`, {
+				method: "POST",
+			});
+		},
+
+		/**
+		 * Get the current state of a checkout session
+		 */
+		getCheckout: async (input: { session_id: string }): Promise<unknown> => {
+			return request(`/api/checkout/${input.session_id}`);
+		},
+	};
+}
+
+/**
+ * Type for the handlers object returned by createHandlers
+ */
+export type Handlers = ReturnType<typeof createHandlers>;

packages/sdk/src/mcp/index.ts

@@ -0,0 +1,91 @@
+/**
+ * MCP (Model Context Protocol) tools for acp-handler
+ *
+ * This module provides tool definitions and handlers to expose your acp-handler
+ * checkout API as MCP tools for ChatGPT Apps. This allows merchants to sell
+ * products through ChatGPT without waiting for ACP approval.
+ *
+ * ## Payment Handling
+ *
+ * MCP tools follow the same ACP protocol as the full ACP implementation, but with
+ * a key difference: ChatGPT Apps don't provide delegated payment tokens. When
+ * `completeCheckout` is called without a payment token, it returns a checkout URL
+ * for the user to complete payment on your site (which can be loaded in the ChatGPT
+ * iframe if desired).
+ *
+ * @example Basic usage (default checkout URL)
+ * ```typescript
+ * import { McpServer } from 'mcp-handler';
+ * import { tools, createHandlers } from 'acp-handler/mcp';
+ *
+ * const server = new McpServer({ name: 'my-store' });
+ * const handlers = createHandlers({
+ *   baseUrl: 'https://mystore.com'
+ *   // Defaults to: https://mystore.com/checkout/:sessionId
+ * });
+ *
+ * // Register all tools
+ * server.registerTool('search_products', tools.searchProducts, handlers.searchProducts);
+ * server.registerTool('create_checkout', tools.createCheckout, handlers.createCheckout);
+ * server.registerTool('complete_checkout', tools.completeCheckout, handlers.completeCheckout);
+ *
+ * server.start();
+ * ```
+ *
+ * @example With custom checkout URL
+ * ```typescript
+ * import { McpServer } from 'mcp-handler';
+ * import { tools, createHandlers } from 'acp-handler/mcp';
+ *
+ * const server = new McpServer({ name: 'my-store' });
+ * const handlers = createHandlers({
+ *   baseUrl: 'https://mystore.com',
+ *   headers: { 'Authorization': 'Bearer secret' },
+ *   getCheckoutUrl: (sessionId) => `https://mystore.com/buy/${sessionId}?source=chatgpt`
+ * });
+ *
+ * // Register tools
+ * server.registerTool('search_products', tools.searchProducts, handlers.searchProducts);
+ * server.registerTool('create_checkout', tools.createCheckout, handlers.createCheckout);
+ * server.registerTool('complete_checkout', tools.completeCheckout, handlers.completeCheckout);
+ * ```
+ *
+ * @example With custom handler logic
+ * ```typescript
+ * import { McpServer } from 'mcp-handler';
+ * import { tools, createHandlers } from 'acp-handler/mcp';
+ *
+ * const server = new McpServer({ name: 'my-store' });
+ * const handlers = createHandlers({
+ *   baseUrl: 'https://mystore.com',
+ *   getCheckoutUrl: (sessionId) => `https://mystore.com/checkout/${sessionId}`
+ * });
+ *
+ * // Customize tool definitions
+ * server.registerTool(
+ *   'search_products',
+ *   {
+ *     ...tools.searchProducts,
+ *     description: 'Search our awesome product catalog!',
+ *   },
+ *   handlers.searchProducts
+ * );
+ *
+ * // Or wrap handlers with custom logic
+ * server.registerTool(
+ *   'create_checkout',
+ *   tools.createCheckout,
+ *   async (input) => {
+ *     console.log('Creating checkout:', input);
+ *     const result = await handlers.createCheckout(input);
+ *     return result;
+ *   }
+ * );
+ * ```
+ *
+ * @module mcp
+ */
+
+export { createHandlers, type HandlerConfig, type Handlers } from "./handlers";
+export type { MCPToolDefinition } from "./tools";
+export { tools } from "./tools";