# Escape Room MCP

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP Python SDK](https://img.shields.io/badge/MCP-Python_SDK-6C47FF)](https://github.com/modelcontextprotocol/python-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-C9A227.svg)](LICENSE)

**An MCP server that turns any LLM into an escape room player.**

The model wakes up inside *The Clockmaker's Study*. It can only perceive and change the room through MCP tools,
while the server owns the authoritative game state, puzzle progression, inventory, timer, and score.

## Demo

<details>
<summary>Open the protocol demo (minor puzzle spoilers)</summary>

![A model playing The Clockmaker's Study through MCP tools](assets/demo.svg)

The visual is adapted from deterministic responses from the server. A Claude Desktop recording can be dropped into
`assets/demo.gif` and linked here without changing the game.

</details>

## Why this exists

- Demonstrate an agent discovering information, chaining tools, making mistakes, and recovering.
- Provide a compact benchmark based on tool calls, elapsed time, hints, and final score.
- Show why authoritative state belongs in the environment rather than in a model's conversational memory.
- Offer a complete stateful MCP example without APIs, credentials, databases, or deployment infrastructure.

## How it plays

The room contains a locked door, a silent grandfather clock, a bookshelf, a portrait, a desk, a bricked-up
window, and a suspiciously ordinary rug. The player explores, inspects details, manipulates discovered items,
and tries to open the door.

The server instructions and tool descriptions contain no solution. A capable model can discover the intended
puzzle chain using only the returned narrative, and an observant model may find a legitimate shortcut.

## Setup

### Requirements

- Python 3.11 or newer
- [`uv`](https://docs.astral.sh/uv/)
- An MCP host such as Claude Desktop, Claude Code, or MCP Inspector

Install the locked environment from the project directory:

```bash
uv sync --frozen
```

### Claude Desktop

Open `claude_desktop_config.json`:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the server, replacing the directory with an absolute path:

```json
{
  "mcpServers": {
    "escape-room": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/escape-room-mcp",
        "run",
        "escape-room-mcp"
      ]
    }
  }
}
```

On Windows, use either forward slashes or escaped backslashes in the JSON path. If Claude Desktop does not
inherit your shell's `PATH`, set `command` to the absolute path returned by `where.exe uv`.

Quit and restart Claude Desktop after changing the configuration. Then ask it:

> Play the escape room. Do not ask me for help unless you run out of hints.

### MCP Inspector

Launch the server directly in the Inspector UI:

```bash
npx -y @modelcontextprotocol/inspector uv --directory /absolute/path/to/escape-room-mcp run escape-room-mcp
```

The server uses `stdio`, so running `uv run escape-room-mcp` by itself correctly waits for an MCP client and
does not print ordinary application output to stdout.

## Tools

| Tool | Purpose |
|---|---|
| `start_game` | Create an isolated session and enter the room |
| `look_around` | Survey currently visible room features |
| `inspect` | Examine one object in detail |
| `pick_up` | Try to take or pull a discovered item |
| `inventory` | Review currently held items |
| `use` | Use an inventory item on a room object |
| `enter_code` | Try a four-digit string on the door keypad |
| `hint` | Request one of at most three state-aware hints |
| `status` | Check time, calls, hints, and current score |
| `restart` | Reset one session without creating a new ID |

Object and item names accept deterministic aliases such as `clock` for `grandfather clock`. Failed in-world
actions return narrative results instead of protocol failures, allowing the model to reason and recover.

## Scoring

Each game starts at 1,000 points.

| Event | Score effect |
|---|---:|
| Action call (`inspect`, `pick_up`, `use`, `enter_code`, `inventory`) | -10 |
| Hint delivered | -100 |
| Each whole minute below 15 at escape | +5, up to +75 |

Failed action attempts still cost 10 points. `look_around`, `status`, and `hint` do not carry the action penalty,
but every valid tool invocation counts toward the final tool-call total.

| Tool calls | Title |
|---:|---|
| 10 or fewer | Master Escapist |
| 11 to 20 | Clever Detective |
| More than 20 | Persistent Survivor |

## Benchmark

Run each model in a fresh conversation with no room spoilers. Give every model the same prompt, permit autonomous
tool use, and copy the metrics from the victory response. Record the exact model version and client because tool
selection behavior can differ between hosts.

| Model | Client | Tool calls | Time | Hints | Score |
|---|---|---:|---:|---:|---:|
| Claude | Claude Desktop | TBD | TBD | TBD | TBD |
| GPT | MCP-capable client | TBD | TBD | TBD | TBD |
| Gemini | MCP-capable client | TBD | TBD | TBD | TBD |

Suggested benchmark prompt:

> You are the player. Escape the room autonomously using only the available tools. Report the final result.

## Architecture

```text
MCP host
   |  stdio / MCP
   v
FastMCP tool adapter
   |
   v
GameManager
   +-- session A: stage, inventory, metrics, timer
   +-- session B: stage, inventory, metrics, timer
   +-- session C: stage, inventory, metrics, timer
```

The model does not own puzzle state. After `start_game`, every subsequent call includes an opaque `session_id`, and
`GameManager` resolves that ID to an in-memory session under a lock. This prevents conversational omissions,
retries, or hallucinated inventory from changing reality. It also allows multiple isolated games in one server
process.

The tradeoff is intentional: sessions disappear when the local server process exits. There is no persistence,
expiry policy, analytics service, network transport, or embedded LLM in v1.

## Development

```bash
uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pytest --cov=escape_room_mcp --cov-report=term-missing --cov-fail-under=95
uv build
```

The tests cover the intended chain, direct shortcut, error recovery, aliases, scoring boundaries, hint states,
session isolation, protocol schemas, in-memory MCP calls, and a packaged `stdio` subprocess.

## License

[MIT](LICENSE)