ChatGPT Apps on TanStack and Railway

Key Concepts

• TanStack: A framework for building applications, used here for a guitar inventory e-commerce site.
• MCP (Meta-Channel Protocol): A protocol for integrating applications, specifically adapted by OpenAI for ChatGPT.
• ChatGPT App Functionality: A feature within ChatGPT that allows for interactive cards and integrations.
• Railway: A cloud hosting platform used for deploying applications.
• Developer Mode (ChatGPT): A setting in ChatGPT that enables app integrations.
• Enrock: A tool for creating secure tunnels to expose local applications to the internet.
• GitHub Repository: Used for version control and connecting to Railway for deployments.
• MCP Endpoint: A specific URL on an application that ChatGPT can communicate with.
• Server Handlers (TanStack Start): Functions that define how an application responds to GET, POST, and other HTTP requests.
• CORS (Cross-Origin Resource Sharing): A mechanism that allows web pages to request resources from a different domain.
• Metadata: Information about an application, including its description, tools, and resources, required by ChatGPT.
• Tools (ChatGPT): Functions or capabilities that ChatGPT can call to perform actions or retrieve data.
• Resources (ChatGPT): Files or assets that ChatGPT can access, such as HTML templates.
• Widgets (OpenAI): Interactive UI elements generated by OpenAI based on tool output and templates.
• Tool Output: Data returned by a tool that can be used to populate widgets.
• UI Widget Template: An HTML file that defines the structure of a widget.
• useChatGPToolOutput Hook: A React hook to access tool output within a widget.
• window.openai Object: A JavaScript object injected into the iframe shell, providing access to tool output and functions like openExternal.
• Vite: A build tool used for compiling JavaScript modules and assets.
• vite.config.ts: Configuration file for Vite.
• build widget Script: A package.json script to build the widget using Vite.

TanStack Guitar Inventory Integration with ChatGPT

This document details the process of integrating a TanStack-based guitar inventory application with ChatGPT's new app functionality, enabling interactive cards and enhanced user experiences. The integration leverages the MCP UI spec tailored for ChatGPT and utilizes Railway for seamless deployment.

1. Project Setup and Deployment

• TanStack Application: The foundation is a TanStack start application, specifically a "TAN chat boilerplate," demonstrating e-commerce integration with AI using a guitar inventory as an example.
• Developer Mode: To enable ChatGPT integration, the ChatGPT instance must be in developer mode. This is accessible via Apps and Connectors > Advanced Settings > Developer Mode.
• Deployment Requirement: For ChatGPT to connect to the TanStack application, it must be live on the internet.
  • Option 1 (Development): Use Enrock to create a tunnel from localhost to the internet.
  • Option 2 (Recommended): Deploy the application to a hosting service.
• Railway Hosting: The video sponsors Railway, a platform for easily shipping TanStack applications.
  • Process:
    1. Log in to Railway via GitHub.
    2. Connect to a GitHub repository containing the TanStack app.
    3. Add the GitHub repository as a remote origin to the local project.
    4. Commit and push changes to the repository.
    5. Create a new project on Railway, selecting the GitHub repository.
  • Railway Features:
    • Supports various databases (Postgres, Redis, MongoDB, MySQL).
    • Allows integration of arbitrary Docker images.
    • Offers persistent volumes for data storage.
    • Enables creation of server functions.
    • Supports templating for architecture specification.
  • Deployment Success: After a quick build and deployment, the application becomes active and accessible via a generated domain (e.g., ts-chatgpt-app.production.railway.app).

2. Creating the MCP Endpoint

• MCP Route Definition: A new MCP route is created within the TanStack application's code (src/routes/mcp.ts).
• createFileRoute: This TanStack function is used to define the route.
• Server Handlers: The route is configured with server handlers for different HTTP methods.
  • GET Handler:
    • Responds to pre-flight CORS requests (OPTIONS).
    • Returns application metadata to ChatGPT.
    • Metadata: Includes chatgptApp type, description ("MCP server chat integration"), name ("guitar app"), and specifies it's an "e-commerce MCP server" with "tools and resources."
  • POST Handler:
    • Handles incoming MCP requests using an MCP request handler.
    • Takes an HTTP request and an MCP server object.
• Defining the MCP Server:
  • An MCP server object is defined, named "guitar app."
  • getGuitars Tool:
    • A simple tool is created to return a list of all available guitars.
    • It takes no input parameters.
    • It retrieves guitar data from data/exampleGuitars.ts.
• Build and Push:
  • The application is built (npm run build) to ensure the new route is included.
  • Changes are committed with a description ("adding an MCP endpoint") and pushed to the GitHub repository.
  • Railway automatically triggers a new deployment due to the repository integration.
• Railway Build Configuration:
  • Defaults are used for the builder (Railpack) and build command, simplifying setup.
  • Railway automatically detects the Vite app and start command.
  • Options for custom start commands, resource limits, cron jobs, health checks, serverless functions, and configuration as code are available.

3. Connecting to ChatGPT and Initial Interaction

• ChatGPT App Creation:
  1. Navigate to Settings > Enabled Apps and Connectors.
  2. Click Create.
  3. Name the app "guitar store."
  4. Provide the MCP endpoint URL (e.g., https://ts-chatgpt-app.production.railway.app/mcp).
  5. Authentication is skipped for simplicity.
  6. Click Create.
• Initial Test:
  • The connection to "Guitar Store" in dev mode is confirmed.
  • A prompt is given: "Recommend a good acoustic guitar from the get guitars tool and make sure that we have guitar store connected."
  • ChatGPT calls the getGuitars tool.
  • The response includes all guitar data.
  • ChatGPT recommends "flowery love guitar" or "traveling man guitar."

4. Implementing Interactive Widgets

• showGuitar Tool:
  • A new tool is added to display a specific guitar.
  • It takes a guitar ID as input.
  • OpenAI Specific Metadata: This is crucial for turning the tool into a widget.
    • template: Specifies the UI widget template file (ui/widgets/showGuitar.html).
    • invoking and invoked text: For user feedback during tool execution.
  • Functionality: The function finds the guitar by ID and returns its data.
  • Tool Output: The guitar data is sent as tool output, which will be passed as props to the HTML template.
• Resource Definition (ui/widgets/showGuitar.html):
  • This HTML file defines the widget's appearance.
  • It has a widgetURI that matches the output template defined in the tool.
  • Initially, it contains a simple placeholder: <h1>Hello from a guitar app</h1>.
• Deployment and Refresh:
  • The code is built and pushed, triggering a Railway deployment.
  • The ChatGPT app's "guitar store" connection is refreshed to recognize the new showGuitar tool and its associated widget.
• Second Test:
  • The same prompt is used: "Recommend a good acoustic guitar from the get guitars tool and make sure that we have guitar store connected."
  • The response now includes an iframe displaying "Hello from guitar app." This confirms the widget is being rendered.

5. Creating a Full React Widget

• Goal: Replace the placeholder HTML with a dynamic React application.
• src/chatgpt/components/GuitarRecommendation.tsx:
  • A React component that displays a guitar card with an image, description, and price.
  • Includes a "View Details" button.
• src/chatgpt/widgetEntry.tsx:
  • A new entry point for Vite to build the widget as a JavaScript module.
  • Uses ReactDOM.render to mount the GuitarRecommendation component.
  • useChatGPToolOutput Hook: This custom hook (defined in src/chatgpt/integration.ts) retrieves tool output.
    • It uses a context to provide the tool output to the component.
    • It checks for window.openai for the shell integration object.
    • It uses an interval to poll for tool output as it might not be immediately available.
  • window.openai Object: This object, injected into the iframe, provides:
    • Access to tool output.
    • Functions like openExternal to open URLs in a new browser tab.
  • "View Details" Button Logic: When clicked, it calls window.openai.openExternal with the guitar's URL.
• Vite Configuration (vite.config.widget.ts):
  • Configures Vite to build the widget.
  • Specifies tailwind and react plugins.
  • Sets the entry point (widgetEntry.tsx).
  • Defines the output directory (widget/dist).
• Build Script (package.json):
  • A build:widget script is added to run vite build using the widget configuration.
  • This script then moves the generated widget.js and widget.css from widget/dist to the public directory.
• MCP File Update (mcp.ts):
  • The GET handler is updated to include the widget.css stylesheet and a div to mount the widget.js script.
• Final Deployment and Test:
  • The code is built and pushed.
  • The application is refreshed in ChatGPT.
  • The prompt is given again.
  • The response now displays an interactive guitar card with an image, description, and price.
  • Clicking "View Details" successfully opens the guitar's page in a new browser tab.

6. Conclusion and Acknowledgements

• Cutting-Edge Technology: The integration is described as technically challenging and cutting-edge, with less-than-ideal documentation. The success of the implementation is a significant achievement.
• Sponsorship: The video is sponsored by Railway, which provided financial support and a robust platform for deploying TanStack applications with necessary infrastructure and logging.
• Call to Action: Viewers are encouraged to ask questions in the comments, like the video, and subscribe to the channel for future content.

This comprehensive summary outlines the technical steps, key concepts, and practical implementation of integrating a TanStack application with ChatGPT's app functionality, highlighting the use of Railway for deployment and the creation of interactive widgets.