Drive Scout SDK APP

This project demonstrates an end-to-end ChatGPT app built with the OpenAI Apps SDK and the Apps SDK quickstart patterns. The app connects ChatGPT to a headless CMS, renders a custom vehicle search experience inside ChatGPT via an iframe widget, and exposes a tool that streams structured inventory results to both the LLM and the user interface.

Features

• Headless CMS integration: Queries vehicle inventory from a headless CMS with optional engine-type filtering.
• Custom UX in ChatGPT: Renders a responsive widget visually inspired by avemo-group.de/fahrzeugsuche inside ChatGPT.
• React-powered widget: Uses a React component (bundled on-demand with esbuild) to manage form state and render the iframe UI.
• Apps SDK + MCP server: Implements an MCP server that exposes the widget resource and a search_inventory tool, keeping UI and structured content in sync through window.openai.
• Local mock data: Provides high-quality fallback inventory data so the widget can be previewed without live CMS credentials.
• 🆕 Lead Capture Form: Users can book test drives directly from vehicle detail pages with a comprehensive contact form.

New: Lead Form Feature 🎉

Users can now contact dealers/companies by clicking the "Book Test Drive" button on any vehicle detail page. The feature includes:

• ✅ Professional contact form with validation
• ✅ Real-time input validation
• ✅ Success confirmation with animation
• ✅ MCP tool for backend integration
• ✅ Ready for CRM integration

Documentation:

• Lead Form Feature Guide - Complete feature overview
• Flow Diagrams - Visual architecture and user journey
• Production Integration - Backend setup guide
• Quick Summary - Implementation summary

Prerequisites

• Node.js 18 or newer.
• A headless CMS with a car content type that includes fields for name, model, engineType, description, heroImage, optional price, ctaUrl, ctaLabel, and statusBadge.
• API access credentials for your headless CMS.

Setup

1. Install dependencies:

   pnpm install

2. Copy the environment template and populate it:

   cp .env.example .env

   Fill in your headless CMS credentials. Adjust the CMS configuration variables based on your CMS provider.
3. Run the MCP server locally (the React widget is bundled automatically on the first request in development):

   pnpm dev

   To work on the iframe UI in isolation, run:

   pnpm run widget:dev

   Then open the printed preview URL (defaults to http://localhost:4173/index.html).
4. (Optional) Test locally with the MCP Inspector:

   npx @modelcontextprotocol/inspector@latest http://localhost:8787/mcp

5. Expose the server to ChatGPT using a tunnel such as ngrok:

   ngrok http 8787

   Use the public URL (e.g. https://your-subdomain.ngrok.app/mcp) when adding the connector in ChatGPT.
6. In ChatGPT:
   • Enable developer mode (Settings → Apps & Connectors → Advanced).
   • Add a new connector pointing to the tunneled /mcp URL.
   • Start a new chat, attach the connector, and ask something like “Find an electric SUV in stock.”

Project Layout

• apps/search-server/src/server.js – MCP server that registers the widget resource and the search_inventory tool.
• apps/search-server/public/ – HTML/CSS shell and static assets served with the widget bundle.
• packages/search-data/src/ – Headless CMS integration and demo data shared across packages.
• packages/search-widget/src/ – React sources compiled on-demand into the widget iframe.
• scripts/widget-dev-server.js – esbuild-powered preview server for developing the widget locally.
• .env.example – Template for required environment variables.

Customization Tips

• Update the widget styling in public/car-widget.html to further match brand guidelines or add additional filters (price range, body style, etc.).
• Extend searchVehicles in packages/search-data/src/data-provider.js to integrate with your CMS and map additional fields such as mileage or availability dates.
• When you change tools or metadata, refresh the connector in ChatGPT (Settings → Connectors → Refresh) so the new schema is picked up.

Deploying

When ready, deploy apps/search-server/src/server.js (or package the @drive-scout/search-server workspace) to a public environment that supports Node.js (e.g., Vercel, Fly.io, Azure). Ensure the /mcp endpoint remains reachable over HTTPS and keep your CMS API credentials secure via environment variables.