# wordlebot

An [MCP](https://modelcontextprotocol.io) server that helps solve Wordle. You tell it which
letters were hits, misses, or in the wrong spot; it returns five-letter words consistent with
every clue, best guesses first.

## What it does

- **`suggest_words`** — give it your guess history (each word + the tile colors) and it returns
  every accepted word still consistent with the clues, ranked by a letter-frequency heuristic.
- **`starting_words`** — strong opening guesses.
- **`validate_word`** — is a word accepted by Wordle?
- **`wordle://wordlist/metadata`** (resource) — provenance of the bundled word list.

## The word list (data source & honesty caveat)

The bundled list is **14,855** five-letter words: the set of *accepted guesses*, sourced from the
public [`tabatkins/wordle-list`](https://github.com/tabatkins/wordle-list) repository, which
extracts them straight from Wordle's own source code. It's normalized (lowercased, de-duplicated,
sorted, every entry validated as exactly five ASCII letters) and shipped as a static file with a
SHA-256 checksum and retrieval date in `src/wordle_mcp/data/words.meta.json`.

**Caveat, stated plainly:** since the NYT acquisition, the *daily-answer* subset has drifted —
words are played out of original order, some have repeated, and some new answers were never on the
original list. So no static list perfectly mirrors NYT's live answer set. For a constraint solver
this is fine: we filter *accepted* words against your clues. But the ranking is a heuristic for a
strong guess, **not** a probability of being today's answer.

To refresh the list from source at any time:

```bash
python scripts/refresh_wordlist.py
```

## Install

Requires Python 3.10+.

```bash
git clone https://github.com/skeeved/wordlebot && cd wordlebot
python -m venv .venv && source .venv/bin/activate
pip install -e .
```

(Or, with [`uv`](https://docs.astral.sh/uv/): `uv sync`.)

## Connect it to Claude Desktop

The server is a local stdio MCP server, so Claude Desktop can launch it directly. The simplest
setup is to install the package into a virtual environment and point Claude at the generated
console script.

### 1. Install the package

From the repository root:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 2. Add the server to Claude Desktop

Open Claude Desktop Settings → Developer → Edit Config and add or update
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) with an absolute path:

```json
{
  "mcpServers": {
    "wordlebot": {
      "command": "/<path>/wordlebot/.venv/bin/wordlebot"
    }
  }
}
```

If you prefer not to activate the virtual environment, run it through `uv` instead:

```json
{
  "mcpServers": {
    "wordlebot": {
      "command": "uv",
      "args": ["--directory", "/<path>/wordlebot", "run", "wordlebot"]
    }
  }
}
```

Then fully quit and relaunch Claude Desktop. If the connection is successful, Claude should show
an MCP server indicator and expose the server's tools.

### 3. Test it interactively

To try the server outside of a host app, use the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector wordlebot
```

## Connect it to VS Code

VS Code can also use this server through its MCP configuration file. The easiest approach is to
create or edit `.vscode/mcp.json` in your workspace (or use the Command Palette command
`MCP: Open User Configuration`).

Example workspace configuration:

```json
{
  "servers": {
    "wordlebot": {
      "type": "stdio",
      "command": "/<path>/wordlebot/.venv/bin/wordlebot"
    }
  }
}
```

Or, if you want VS Code to launch it through `uv`:

```json
{
  "servers": {
    "wordle-solver": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/<path>/wordlebot/.venv/bin", "run", "wordlebot"]
    }
  }
}
```

After saving the file, VS Code will usually prompt you to trust and start the server. Once it is
running, the tools should appear in chat and agent workflows.

## How to describe feedback

Each guess is a word plus a 5-character pattern, left to right:

| Symbol | Meaning                                   |
|--------|-------------------------------------------|
| `G`    | green — correct letter, correct spot      |
| `Y`    | yellow — letter is in the word, wrong spot|
| `B`    | gray/black — letter not in the word       |

(`2/1/0` and `.` `x` `_` are also accepted as `G/Y/B`.)

**Example call** to `suggest_words`:

```json
{
  "guesses": [
    { "word": "crane", "feedback": "BGGGB" },
    { "word": "trail", "feedback": "BGGBB" }
  ],
  "max_results": 10
}
```

→ returns `{ "total_matches": 18, "words": ["grans", "brank", ... , "prank", ...], ... }`

In practice you just talk to your MCP host: *"I played CRANE and got gray-green-green-green-gray,
then TRAIL and got gray-green-green-gray-gray. What should I try?"* — the host fills in the tool call.

## The one subtle rule: duplicate letters

A gray tile does **not** always mean "letter absent." If you guess a word with two of a letter but
the answer has only one, one copy comes back colored and the other gray — the gray means *"no more
copies,"* not *"none at all."*

Analogy: requesting two ocean-view rooms at a hotel with only one. The desk confirms one and
declines the other; the decline doesn't mean zero ocean-view rooms exist — just none beyond the one
you got.

The solver implements this exactly: green + yellow tiles set a **minimum** count for a letter; any
gray tile for that same letter turns the minimum into an **exact** count. This is verified by a
property test (`tests/test_solver.py::test_matches_equals_reference`) that checks the matcher
against a from-scratch implementation of Wordle's real feedback rule across hundreds of thousands of
answer/guess/candidate combinations.

## Development

```bash
pip install -e ".[dev]"
pytest -q
```

## Notes on the MCP SDK

Built on the **v1.x** MCP Python SDK (`mcp[cli]`, `FastMCP`), which is the stable,
production-recommended line. It is pinned `>=1.27,<2`: SDK v2 (targeting the 2026-07-28 spec)
renames `FastMCP` to `MCPServer` and moves to a stateless request/response protocol. When you
migrate, the tool functions here carry over unchanged; only the server bootstrap in
`src/wordle_mcp/server.py` needs updating per the SDK migration guide.

## License

GPL-3.0-only.