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:

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.