ClueKeeper

An interactive museum mystery where every clue has a traceable source. Explore, question characters, and solve the case in a persistent Alexa+ web simulation powered by real MCP tools.

Comment

ClueKeeper — The Tideglass Transfer

A museum mystery where every answer needs evidence.

What if solving a mystery wasn't just about guessing the right answer, but proving how you reached it?

ClueKeeper is an interactive investigation experience where players explore a museum, question characters, uncover hidden evidence, and piece together a mystery. Every discovered clue is preserved with its source, and the story cannot be resolved through unsupported guesses.

Built for the Alexa+ track, ClueKeeper combines a working Model Context Protocol (MCP) server with a browser-based simulation of an Alexa+ experience.

Inspiration

Traditional mystery games often expect players to remember everything themselves. Lose your place, miss a detail, or return after an interruption, and the investigation becomes frustrating.

AI-driven storytelling introduces another problem: an explanation can sound convincing even when the evidence does not support it.

ClueKeeper explores a different approach: What if an interactive mystery could remember everything you discovered, preserve where each clue came from, and require an evidence-backed conclusion?

The goal was to make investigation feel rewarding without sacrificing consistency, continuity, or player control.

What it does

In The Tideglass Transfer, players investigate an original, nonviolent museum mystery involving three interconnected rooms, four fictional adults, and six evidence records.

Players can:

  • Explore: Inspect museum objects and discover clues through contextual actions.
  • Investigate: Question characters and unlock additional information as the case progresses.
  • Track evidence: Collect records that preserve the source of each discovery.
  • Test theories: Submit an explanation and see whether the necessary evidence supports it.
  • Resume investigations: Pause, reload, and continue without losing discovered clues or progress.
  • Control their data: Export the investigation or delete it and begin again.

The defining feature is the evidence ledger. ClueKeeper doesn't simply accept a plausible explanation. Its investigation engine checks whether the necessary clues have been revealed and explicitly cited.

A correct-looking answer without sufficient evidence is rejected.

How we built it

ClueKeeper uses a deterministic TypeScript investigation engine responsible for story state, action availability, clue provenance, and resolution requirements.

The architecture has four main components.

1. Investigation engine

The authored mystery defines available locations, characters, objects, clues, and action prerequisites. The engine evaluates each action against the current investigation state, keeping story progression reproducible.

2. Real MCP integration

A self-hosted MCP server exposes the get_game and perform_action tools over Streamable HTTP.

The browser experience uses these MCP tools to retrieve investigation state and execute actions. This demonstrates a working MCP-backed interaction model through a clearly labelled Alexa+ web simulation.

3. Persistent investigation state

The application runs on Google Cloud Run, with private Google Cloud Storage maintaining deployed investigation state.

Revision checks, idempotent action identities, and storage generation preconditions protect against stale actions, duplicate requests, and concurrent updates. SQLite supports local development.

4. Interactive browser experience

A Vite-based frontend provides an investigation interface with rooms, available actions, clues, and case controls. The application is packaged with Docker and tested using Playwright.

The story and canonical evidence are authored rather than generated at runtime. An optional Amazon Bedrock action-selection adapter exists but is disabled; this submission does not claim live Bedrock inference or native Alexa device integration.

Challenges we addressed

Keeping the mystery logically consistent

The biggest design challenge was ensuring that every action respected the investigation's existing facts. We addressed this through explicit prerequisites, evidence dependencies, and a deterministic resolution process.

Preserving progress across interruptions

Refreshing the browser or replacing a cloud deployment should not erase an investigation. We implemented persistent state with session isolation and concurrency protections, then verified that progress survived an actual Cloud Run revision replacement.

Making MCP useful beyond a demonstration

Instead of exposing a disconnected example tool, we connected MCP actions to a complete investigation workflow. Tool calls operate against server-owned story state.

Balancing mystery and transparency

The player should be challenged to discover the solution, but the system should never invent evidence or quietly accept an unsupported conclusion. Explicit citations make the final resolution explainable.

Testing and results

The project completed the following reported verification:

  • 53 Node.js tests covering application behavior.
  • 24 Chromium desktop and mobile scenarios validating browser interactions.
  • 300 investigation states and 1,516 transitions checked through bounded puzzle verification.
  • Live MCP initialization, tool discovery, and action execution against the deployed service.
  • Browser session isolation, export, deletion, and stale-session rejection checks.
  • Persistence verification across a real Cloud Run revision replacement.
  • A complete six-clue investigation ending in an evidence-backed resolution.

The bounded verification established a solution path from each reachable state in its tested model. Synthetic action fixtures were also checked, but these are not presented as live AI-model accuracy or human usability results.

What we learned

The central engineering lesson is that stateful interactive experiences benefit from keeping narrative facts separate from action selection.

A tool can suggest or execute an available action, but the underlying application must remain responsible for validating facts, tracking provenance, and protecting state.

MCP also provides a practical interface for exposing those actions independently of the browser frontend, creating a foundation for future agent-driven experiences.

What's next

Future development could extend ClueKeeper with additional cases, optional guided voice interactions, more accessibility features, and user testing to evaluate investigation difficulty and clarity.

A future Alexa integration would depend on access to the relevant development capabilities.

The current release deliberately prioritizes a complete, testable mystery over speculative integrations.

Try ClueKeeper

Live application: https://cluekeeper-kc4mxxrtbq-uc.a.run.app

Source repository: https://github.com/GameDevKaran/cluekeeper

ClueKeeper is an independently developed entertainment application distributed under the MIT license. AI coding tools assisted substantially with design, implementation, testing, and documentation. The original mystery, application behavior, and verification materials are documented in the repository.

Built With

Share this project:

Updates

Submission history