Ladder Pick — ChatGPT App Development Plan#
- Project name:
ted-mcp-servers - App name (App Directory display): Ladder Pick
- App language: English first (UI / tool description / privacy policy all in English; only the plan document is in Korean)
Official Developer Documentation Reference Links#
Core Documents (Must-Read)#
- Apps SDK Home: https://developers.openai.com/apps-sdk
- Quickstart (includes Todo example): https://developers.openai.com/apps-sdk/quickstart
- MCP Server Concepts: https://developers.openai.com/apps-sdk/concepts/mcp-server
- MCP Apps in ChatGPT: https://developers.openai.com/apps-sdk/mcp-apps-in-chatgpt
Design#
- UX Principles: https://developers.openai.com/apps-sdk/concepts/ux-principles
- UI Guidelines: https://developers.openai.com/apps-sdk/concepts/ui-guidelines
- Design Components: https://developers.openai.com/apps-sdk/plan/components
- Tool Definitions: https://developers.openai.com/apps-sdk/plan/tools
- Use Case Research: https://developers.openai.com/apps-sdk/plan/use-case
Build#
- MCP Server Setup: https://developers.openai.com/apps-sdk/build/mcp-server
- ChatGPT UI Build: https://developers.openai.com/apps-sdk/build/chatgpt-ui
- State Management: https://developers.openai.com/apps-sdk/build/state-management
- Authentication: https://developers.openai.com/apps-sdk/build/auth
- Example Apps (GitHub): https://github.com/openai/openai-apps-sdk-examples
- UI Library (GitHub): https://github.com/openai/apps-sdk-ui
Deployment / Testing / Submission#
- Deployment Guide: https://developers.openai.com/apps-sdk/deploy
- Testing Guide: https://developers.openai.com/apps-sdk/deploy/testing
- ChatGPT Connection: https://developers.openai.com/apps-sdk/deploy/connect-chatgpt
- App Submission & Maintenance: https://developers.openai.com/apps-sdk/deploy/submission
- App Submission Guidelines (Policies / Rules): https://developers.openai.com/apps-sdk/app-submission-guidelines
- Developer Mode Setup: https://platform.openai.com/docs/guides/developer-mode
Guides / References#
- Security & Privacy: https://developers.openai.com/apps-sdk/guides/security-privacy
- Metadata Optimization: https://developers.openai.com/apps-sdk/guides/optimize-metadata
- Troubleshooting: https://developers.openai.com/apps-sdk/deploy/troubleshooting
- API Reference: https://developers.openai.com/apps-sdk/reference
- Changelog: https://developers.openai.com/apps-sdk/changelog
General References#
- Apps in ChatGPT (Help Center): https://help.openai.com/en/articles/12503483-apps-in-chatgpt-and-the-apps-sdk
- App Directory Submission (Help Center): https://help.openai.com/en/articles/20001040
- App Directory Browsing: https://chatgpt.com/apps
Goals#
- Build a “Ladder Pick” app that can be listed on the ChatGPT App Directory.
- Enable the complete flow — entering participants / items → generating a ladder (random matching) → revealing results — through an interactive widget (iframe) within a chat.
- After testing with ChatGPT Developer Mode, the ultimate goal is App Directory submission / approval / Publish.
Assumptions / Scope#
- MVP: Interactive widget (iframe UI) + MCP tool-based. The widget provides core interactions such as entering participants / items, displaying results, and reshuffling.
- Out of scope (initial): Login / payments, real-time multiplayer, complex animations, external data integration.
- No authentication required: Since there is no external service integration, we start without OAuth / authentication flows.
- Safety / Policy: No write operations to external systems. Tool hint annotations:
readOnlyHint: false— Not true because internal state is created / modifieddestructiveHint: false— No irreversible external impactopenWorldHint: false— No public internet state changes
User Experience (UX) Scenarios#
Basic Flow (Interactive Widget)#
- The user types
@Ladder Pickor something like “play a ladder game.” - ChatGPT calls the
create_gametool, and the Ladder Pick widget is displayed in an iframe. - Within the widget:
- Players list: Add / remove participant names (default 4)
- Items list: Add / remove result items (prizes / roles)
- Options: Reveal mode (All at once / One by one), Seed (auto / custom)
- Click the “Pick!” button → Generate matching results
- Results area:
- All at once: Display the full matching table immediately
- One by one: Reveal one person at a time with the “Reveal Next” button
- “Reshuffle” button: Reshuffle with a new seed
- “Export” button: Copy results as text
Text Fallback#
- Even without the widget, ChatGPT can display tool call results as text (table).
- Example: “Ladder Pick, match A,B,C,D with 1st,2nd,3rd,4th” → Text table response
Error Cases#
- Fewer than 2 participants → Error message: “At least 2 players are required.”
- Item count ≠ participant count → Error message: “Number of items must match number of players. You have {n} players and {m} items.”
- Items list empty → Error message: “Items list cannot be empty.”
Functional Requirements#
Input#
- Participant list (Players): 2–20 people
- Result items (Items): Must be exactly the same count as participants (error returned on mismatch)
- Options
- Reveal mode:
all|one-by-one - Seed: Auto-generated or user-specified (for reproducibility)
- Reveal mode:
Output#
- Matching results: Player ↔ Item 1:1 mapping
- Ladder visualization: Canvas-based visual ladder (vertical lines + horizontal rungs + color-coded path animations)
State / Storage#
- Module-level
Map<gameId, GameState>for in-process in-memory management - Unique ID issued on game creation; subsequent reshuffle / reveal_next lookups use that ID
- No persistent storage (resets on server restart; this is sufficient for the initial version)
Technical Design#
Architecture (Based on Official Structure)#
ChatGPT Apps consist of two components:
