# 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`.

```bash
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:

```bash
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:

```bash
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 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](.github/workflows/deploy-functions.yml). 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](docs/GITHUB_DEPLOYMENT.md)
for the configured identity and the automated setup script.

Build a deployment package and install its production dependencies:

```powershell
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:

```powershell
./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:

| 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](https://developers.openai.com/apps-sdk/quickstart/)
- [Build an MCP server](https://developers.openai.com/apps-sdk/build/mcp-server/)
- [Build the ChatGPT UI](https://developers.openai.com/apps-sdk/build/chatgpt-ui/)
- [Apps SDK examples](https://developers.openai.com/apps-sdk/build/examples/)
- [Design tools](https://developers.openai.com/apps-sdk/plan/tools/)
- [Apps SDK reference](https://developers.openai.com/apps-sdk/reference/)
- [Managing state](https://developers.openai.com/apps-sdk/build/state-management/)
- [OpenAI Apps SDK UI](https://github.com/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.