Word Guesser — ChatGPT word game

Word Guesser is 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:

• docs: http://localhost:8787/

• privacy: http://localhost:8787/privacy

• terms: http://localhost:8787/terms

• 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

Related MCP server: openai-mcp

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 Word Guesser.”

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.

Azure Functions deployment

The app uses Azure Functions' self-hosted MCP custom-handler preview on Linux Flex Consumption, with Node 22 and managed identity storage access. The three top-level app resources are the Function App, Flex Consumption plan and storage account; Application Insights and paid log ingestion are not configured. Infrastructure is in infra/main.bicep; the current target is rg-word-guesser-brazilsouth in Brazil South.

GitHub Actions deploys pushes to main (including merged pull requests) through the deployment workflow. It runs tests, builds the production package, publishes to the existing Function App, and checks the live MCP endpoint. Azure OIDC trust is configured for this repository's main branch, and the workflow includes its public Azure identifiers. No GitHub secrets or variables are required. See GitHub deployment setup for the configured identity and the automated setup script.

Build a deployment package and install its production dependencies:

npm ci
npm run build:azure
npm ci --omit=dev --ignore-scripts --prefix dist/azure

After signing into Azure CLI, validate and provision infra/main.bicep at subscription scope with infra/main.parameters.json, then publish:

./scripts/publish-azure.ps1
node scripts/check-mcp.mjs https://word-guesser.mcp.11feed.com

The publish script creates a Linux-compatible ZIP, preserves the configured WIDGET_DOMAIN, and uses Flex OneDeploy with an Azure CLI bearer token. It performs no remote build. Use -WidgetDomain https://YOUR-BOUND-DOMAIN to change the widget origin; the hostname must already be bound to that Function App. Without an existing setting, its actual Azure hostname is used. Update its subscription, resource group and app parameters when using another target.

The production custom domain is word-guesser.mcp.11feed.com. Its existing Azure DNS zone is 11feed.com in cloud-shell-storage-eastus: CNAME word-guesser.mcp points to func-word-guesser-6e5da.azurewebsites.net, and TXT asuid.word-guesser.mcp holds the app's custom-domain verification ID. The domain binding and free site-scoped managed certificate are configured separately in Azure; infra/main.parameters.json preserves the matching widget origin. For a fresh target, validate domain ownership, add the hostname, issue the certificate and bind SNI HTTPS before using the custom origin. Keep unrelated zone records intact. The existing Azure hostname remains available.

Use https://word-guesser.mcp.11feed.com/mcp in ChatGPT Developer Mode, with no authentication. Public submission still needs domain verification, review assets, dictionary licensing/provenance, and testing inside ChatGPT. Deployment validation and results are recorded in .azure/deployment-plan.md.

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.