Five Letters — ChatGPT word game

An interactive five-letter guessing game for ChatGPT. Players get six attempts, Wordle-style letter feedback, a physical/on-screen keyboard, and local progress persistence. The app defaults to English and selects Brazilian Portuguese when ChatGPT supplies BR in the coarse user-location hint. Players can switch languages at any time.

This is an interactive-decoupled ChatGPT app:

• server/ contains a stateless TypeScript MCP server.
• web/ contains a React widget bundled into one CSP-friendly HTML resource.
• shared/ contains game rules used by the server, widget fallback, and tests.
• docs/APP_REFERENCE.md is the durable implementation/product reference.

Run locally

Requires Node.js ^20.19.0 or >=22.12.0.

npm install
npm run build
npm start

The server exposes:

• health: http://localhost:8787/health
• MCP: http://localhost:8787/mcp

For standalone widget development, run:

npm run dev:web

Then open http://localhost:5173. Standalone mode bundles the same English and Brazilian Portuguese word lists used by the MCP server; ChatGPT mode validates guesses through the MCP tool.

Useful checks:

npm run typecheck
npm test
npm run build:web

Connect to ChatGPT

1. Build and start the server locally.
2. Expose port 8787 through a public HTTPS tunnel, for example ngrok http 8787.
3. In ChatGPT, enable Developer mode under Settings → Security and login.
4. Open Settings → Plugins (or chatgpt.com/plugins), create a developer-mode app, and paste https://YOUR-TUNNEL.example/mcp.
5. Add the app to a new chat and ask: “Let’s play the five-letter word game.”
6. Refresh the app in its ChatGPT settings after changing MCP tools or metadata.

No OpenAI API key is required: ChatGPT is the host and the app only exposes MCP tools plus a widget.

Current package baseline

Versions were resolved from npm on 2026-07-21 and pinned exactly for reproducibility:

Package	Version
@modelcontextprotocol/sdk	1.29.0
@modelcontextprotocol/ext-apps	1.7.4
@openai/apps-sdk-ui	0.2.2
React / React DOM	19.2.8
Vite	8.1.5
TypeScript	7.0.2
Zod	4.4.3
Tailwind CSS	4.3.3

Official references

• Apps SDK quickstart
• Build an MCP server
• Build the ChatGPT UI
• Apps SDK examples
• Design tools
• Apps SDK reference
• Managing state
• OpenAI Apps SDK UI

Security note

npm audit --omit=dev currently reports advisories in the latest pinned MCP/UI dependency trees. The app does not use Hono's affected serve-static path or lodash's affected template/unset APIs, and there is no non-breaking upstream fix available for the Apps SDK UI lodash dependency at this baseline. Re-run the audit when upgrading dependencies and replace the pinned versions only after the build and MCP checks pass.