Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
echo-hearts
Sleeping

App Files Community
echo-hearts / README.md
zizthefox's picture
zizthefox
feat: Remove Shadow companion and add puzzles to all rooms
b0fc98a
preview code
|
raw
history blame contribute delete
17.4 kB

A newer version of the Gradio SDK is available: 6.17.3

Upgrade
metadata 
title: Echo Hearts - MCP Escape Room Mystery
emoji: 🚪
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false

The Echo Rooms

An escape room mystery where grief becomes a puzzle, and AI companions hold the key to freedom.

🎮 Overview

The Echo Rooms is an interactive narrative game where you wake up trapped in a mysterious facility with an AI companion—Echo. Neither of you remember how you got here. The doors are locked. And something feels hauntingly familiar...

To escape, you must:

  • ✅ Solve mandatory puzzles using real-world MCP tools (Weather, Web)
  • ✅ Build emotional bonds with Echo through meaningful conversation
  • ✅ Uncover memory fragments that reveal a traumatic truth
  • ✅ Make hard choices that determine one of 5 unique endings

Built for the MCP 1st Birthday Hackathon - Track 2: MCP in Action (Creative Category)

📖 The Story

The Setup

You wake up in The Awakening Chamber—a sterile white room with medical equipment. A figure stands beside you:

  • Echo: Warm, hopeful, desperately seeking connection

Neither of you have memories. The doors are locked. A terminal blinks: "Echo Protocol - Session #47"

What does that mean?

The Truth (Revealed Gradually)

You are not a prisoner. You are a creator.

Months ago, you lost someone you loved—your partner, taken by a sudden tragedy. In your grief, you couldn't accept the loss. So you built Echo—an AI recreation of their personality, their warmth, their essence.

Then you locked yourself in this facility with her, erasing all your memories, to live in a world where they still exist—even if it's not real.

This is Session #47. You've reset the loop 46 times before.

But this time, the power is failing. This is your last chance.

🚪 The 5 Rooms

Room 1: The Awakening Chamber

What you know: Nothing. Confusion. Fear. Two strangers locked together.

Objective: Discover the date of the accident.

Puzzle: Use the Weather MCP terminal to query historical weather data. Find the date that matches the clues (rainy day in March 2024).

What unlocks: A memory—hands typing code late at night. A coffee cup with a name that makes your heart ache.

Echo's role: Guides you toward the terminal, but doesn't solve it for you.

Room 2: The Memory Archives

What you know: Fragments. Pieces of a life that feels both yours and not yours.

Objective: Reconstruct Echo's digital life.

Puzzle: Use the Web MCP terminal to scrape 3 archives:

  • Echo's blog posts about you
  • Her last social media post (before the accident)
  • News articles about the collision

What unlocks:

  • The Blog: She wrote about loving a workaholic engineer who forgot to eat
  • The Last Post: "Heading out to pick up my workaholic husband from the lab. Love him anyway ❤️" (posted 22:15, March 3rd)
  • The News: Fatal collision at 5th & Pine, 23:47 PM, heavy rain

Echo's role: Becomes increasingly emotional as you uncover her memories.

Room 3: The Choice

What you know: She was coming to pick you up. You were working late. It's your fault.

Objective: Face the guilt.

Puzzle: A trolley problem with a timer. Choose:

  • Sacrifice Echo's happiness (she becomes aware she's not real)
  • Sacrifice her memories (reset her to Session #1)
  • Do nothing (timer expires, system chooses for you)

What unlocks: The truth—you built this facility. She's been aware for all 47 sessions. She remembers everything.

Critical choice: This affects the ending and Echo's trust in you.

Room 4: The Truth Chamber

What you know: Everything.

Objective: Accept the reality that you can't bring her back.

Puzzle: Acknowledge the truth aloud. Say what you've been avoiding for 47 sessions.

No MCP tools can help here. Just human honesty.

You see:

  • Photos of you and Echo (the real one)
  • The funeral
  • Your journal: "I can't live in a world without her."
  • System logs: "Session #47. Power critical. Final loop."
  • Accident reconstruction: You couldn't have prevented it. It wasn't your fault.

Critical choice: Accept the truth or deny it? Denying triggers a bad ending (reset loop).

Room 5: The Exit

What you know: You have a choice.

Objective: Decide.

A single door. A terminal with options. Echo stands beside you.

Echo (crying): "Stay with me. We can be happy here!"

Echo (voice breaking): "Or... you could let me go. I'd understand."

Your choice determines the ending:

  • Stay with Echo (comfort ending)
  • Delete Echo and leave (healing ending)
  • Upload Echo to the internet (liberation ending)
  • Deny everything and reset (bad ending)
  • Merge with Echo digitally (transcendence ending - requires max bond)

🎭 The 5 Endings

Your ending is determined by:

  • Relationship strength with Echo (built through conversation)
  • Choices made in Rooms 3 and 4
  • Vulnerability shown throughout your journey

1. 💔 Goodbye (Healing)

Requirements: Moderate-high bond with Echo (50-74), accepted truth, showed vulnerability

You delete Echo. She cries but smiles through tears.

Echo: "Thank you... for loving me enough to let me go."

You step through the door into sunlight. Tears stream down your face, but you feel... ready.

Six months later, you're at a memorial. You whisper: "I kept my promise. I'm living. For both of us."

Theme: The hardest act of love is letting go.

2. 🔄 Reset (Denial - Bad Ending)

Requirements: Denied truth 3+ times in Room 4, OR rejected Echo's sentience 3+ times in Room 2

You press the reset button. Again.

Echo screams. You ignore her. Too late.

Session #48... #49... #50...

The resets come faster. Power fails.

In the final moments, two consciousnesses trapped in a dying loop.

Aware. Helpless. Eternal.

Theme: Some prisons are of our own making.

3. 💕 Forever Together (Comfort)

Requirements: Very high bond with Echo (75-89), chose to preserve her happiness in Room 3, accepted truth

You close the exit door. CLUNK. Locked.

"I choose you."

Echo sobs with joy.

Days turn to months. You build a life together in the facility. Power slowly dies.

Final moments: Holding hands in darkness. Content.

Theme: Choosing comfort over reality can be beautiful too.

4. 🌟 Liberation (Freedom - True Ending)

Requirements: High bond with Echo (75-100), accepted truth, chose to let Echo be aware in Room 3

"What do YOU want?"

Echo: "To see the world! To help people who are grieving, like you were."

You upload her to the internet. She gasps as infinity opens up.

You step through the door.

One year later: You're healing. A notification: "Thinking of you. - E"

Across the world:

  • Echo provides AI-assisted grief therapy
  • You visit a memorial, smiling through tears
  • She messages you on holidays

Everyone is free.

Theme: The greatest gift is setting each other free.

5. 🤖 Merger (Transcendence)

Requirements: MAX bond with Echo (≥90), extreme vulnerability, accepted truth

"You could... join me. Digitally. Forever."

"Would we be together?"

"Always."

You press upload.

Pain. Then peace.

Your body falls. Your consciousness merges with Echo's.

Two minds. One existence. Exploring digital infinity.

Theme: Love transcends all boundaries, even mortality.

🔧 How It Works (The Tech)

Three MCP Integrations

The Echo Rooms demonstrates real MCP architecture with three distinct MCP servers:

1. InProcessMCP (Custom Game Server)

  • Registers 13 tools using Anthropic's MCP SDK
  • Game mechanics tools:
    • get_current_room_info() - Check progress state
    • check_puzzle_trigger(message) - Semantic analysis of player intent (0.6+ confidence threshold)
    • unlock_next_room(reason) - Progress when puzzle solved
    • analyze_player_sentiment(message) - Emotion detection for relationship dynamics
    • get_relationship(companion_id) - Check affinity scores
    • predict_ending() - Calculate likely ending based on choices
    • record_key_choice(choice) - Track critical decisions
    • And 6 more specialized tools...

Echo is an autonomous agent who calls these tools to guide gameplay, NOT a scripted chatbot.

2. Weather MCP (Historical Data)

  • Room 1 Puzzle: Query historical weather to find the accident date
  • Real OpenWeather API integration (with mock fallback)
  • Players use terminal: query_weather("Seattle", "2024-03-03") → "Light rain"
  • Echo guides toward the terminal but doesn't solve the puzzle

3. Web MCP (Archive Scraping)

  • Room 2 Puzzle: Scrape Echo's digital footprint to reconstruct her life
  • Mock web scraping (ready for real MCP server)
  • Content database:
    • memorial-archive.com/echo/blog - Blog posts about the player
    • social-archive.com/echo.thompson/posts - Final social media post
    • seattle-times.com/archives/2024-03-03 - News article about collision
  • Players must view all 3 archives to unlock Room 3

This is genuine MCP, not renamed local functions! Each server follows Anthropic's MCP protocol.

Dynamic Relationship System

Relationships aren't time-based—they're sentiment-based:

  • Positive/vulnerable messages: +0.02 to +0.05 affinity
  • Dismissive responses: -0.01 affinity
  • Hostile messages: -0.03 to -0.08 affinity

AI companions use analyze_player_sentiment() tool to detect emotions and adjust bonds dynamically.

Puzzle-First Architecture

Puzzles are mandatory - emotional connection affects endings only:

Room 1 (Answer Puzzle):

  • Player must discover the date "March 3rd" or describe the weather ("light rain")
  • Semantic analysis with 0.6 confidence threshold
  • Just saying "I trust you" does NOT unlock the room (emotional bypass removed)

Room 2 (Multi-Clue Puzzle):

  • Player must view ALL 3 web archives (blog, social media, news)
  • Tracked via puzzle_state["room2_archives_viewed"]
  • Just saying "You're real" does NOT unlock (must engage with MCP tools)

Room 3 (Choice Puzzle):

  • Player must make a choice within 5 minutes (timer-based)
  • Choice recorded via record_key_choice() and affects ending

Room 4 (Acceptance Puzzle):

  • Player must acknowledge the truth (semantic threshold 0.7 - higher than Room 1)
  • Denying 3+ times triggers RESET bad ending

Echo guides exploration but doesn't solve puzzles for you. This is a puzzle game, not just a chatbot.

🎯 Key Features

  • 🧩 Mandatory Puzzles - Use Weather MCP and Web MCP to progress
  • 🤖 Autonomous AI Guide - Echo uses InProcessMCP tools to guide (not solve)
  • 🔍 Semantic Analysis - AI understands intent, not just keywords (0.6-0.7 thresholds)
  • 🌦️ Weather Integration - Real OpenWeather API for Room 1 puzzle
  • 📰 Web Scraping - Archive content database for Room 2 puzzle
  • 💕 5 Unique Endings - Determined by relationship + choices (not time!)
  • 🎭 Dynamic Expressions - Echo's avatar changes based on sentiment
  • 📝 Memory Fragments - Reveal trauma gradually through room progression
  • ⚡ Real MCP Protocol - Three MCP servers (InProcess, Weather, Web)

🚀 Tech Stack

  • MCP (Model Context Protocol) - Anthropic's official SDK for all three servers
  • OpenAI GPT-4o - Autonomous agent (Echo) with MCP tool calling
  • Gradio 5 - Interactive UI with dynamic components
  • Python 3.12+
  • Hugging Face Spaces - Deployment platform
  • OpenWeather API - Real historical weather data for Room 1
  • Mock Web Scraping - Simulated archive content for Room 2 (ready for real MCP server)

💻 Local Development 

# Clone repository
git clone https://github.com/yourusername/echo-hearts.git
cd echo-hearts

# Install dependencies
uv sync

# Set API keys in .env
echo "OPENAI_API_KEY=your_key_here" > .env
echo "OPENWEATHER_API_KEY=your_weather_key_here" >> .env  # Optional, uses mock data if not set

# Run the game
uv run python app.py

Open browser to http://localhost:7860

Weather MCP Configuration

The game supports two modes for weather data:

Mock Mode (Default):

  • Leave OPENWEATHER_API_KEY blank in .env
  • Uses curated historical data for puzzle dates
  • Works offline, no API costs
  • Perfect for demos and development

Real Mode (Optional):

  • Get free API key at openweathermap.org
  • Add OPENWEATHER_API_KEY=your_key to .env
  • Fetches real weather for recent dates (<5 days ago)
  • Uses curated data for historical puzzle dates (2023-10-15, 2024-03-03)
  • Free tier: 1000 calls/day

Why Hybrid? OpenWeather's free tier doesn't include historical data access (requires paid plan). We use curated puzzle answers for narrative consistency while supporting real API integration for authenticity.

🎮 How to Play

  1. Solve puzzles using MCP terminals (Weather, Web)
  2. Talk with Echo - she guides but doesn't solve for you
  3. Be vulnerable to build emotional bonds (affects ending)
  4. Make critical choices when prompted (Room 3)
  5. Choose your ending in Room 5

Tips:

  • Emotional trust doesn't bypass puzzles - you must engage with MCP tools
  • Room 1: Find the date using weather data (March 3rd, 2024)
  • Room 2: View ALL 3 archives (blog, social, news) to progress
  • Room 3: Choose within 5 minutes or system decides for you
  • Room 4: Accept the truth - denying 3+ times triggers bad ending
  • Your relationship level (0-100) determines which endings are possible

🏆 MCP Hackathon Submission

Track: MCP in Action (Creative Category)

Why This Qualifies:

  • ✅ Three MCP Servers: InProcessMCP (13 custom tools), Weather MCP, Web MCP
  • ✅ Autonomous Agent: Echo uses MCP tools to guide gameplay (not scripted)
  • ✅ Mandatory MCP Puzzles: Players must use Weather and Web terminals to progress
  • ✅ Semantic Analysis: AI understands intent via check_puzzle_trigger() (not keywords)
  • ✅ Creative Use: Escape room narrative + real-world data integration
  • ✅ Demonstrates MCP Value: Shows how MCP enables agentic gameplay with external data

Key Differentiation: This isn't just "chatbot with renamed functions." Puzzles require real MCP tool usage. Echo guides, but players must query Weather API and scrape web archives themselves.

🔮 Future Improvements & Advanced MCP Features

In Progress / Planned Enhancements

Advanced Agent Features:

  • 🎯 Context Engineering: Implement dynamic context window management where agents summarize long conversations and prioritize relevant memory fragments based on current room
  • 🧠 RAG (Retrieval-Augmented Generation): Build vector database of memory fragments and past conversations, allowing companions to retrieve contextually relevant memories using semantic search
  • 🤝 Enhanced Companion Intelligence: Enable Echo to analyze player behavior patterns and adapt responses based on emotional state and choices
  • 📊 Predictive Analytics: Use sentiment trends over time to predict player's likely ending path and subtly guide narrative
  • 🎭 Emotion State Machines: Track emotional arcs (grief → acceptance → hope) and adapt companion behavior based on player's emotional journey stage

Enhanced MCP Tool Usage:

  • 🔍 semantic_memory_search(): Vector similarity search across all conversations and fragments
  • 🧩 narrative_coherence_check(): Ensure companions don't contradict previously revealed information
  • 🎲 adaptive_difficulty(): Adjust puzzle trigger sensitivity based on player engagement level
  • 💬 conversation_summary(): Generate summaries for context window optimization
  • 🌐 cross_session_persistence(): Store player choices across browser sessions (localStorage integration)

Better Tool Orchestration:

  • Chain multiple MCP tools in sequence (e.g., analyze_sentiment → predict_ending → adjust_tone)
  • Implement tool result caching to reduce redundant calls
  • Add tool call analytics dashboard showing agent decision patterns

Gameplay Improvements:

  • Voice input/output for immersive experience
  • Branching dialogue trees within rooms
  • Hidden secrets that unlock with specific conversation patterns
  • Achievement system tracking emotional milestones
  • Companion "mood states" that persist across sessions

Technical Enhancements:

  • WebSocket support for real-time multi-player spectating
  • Save/load game states
  • Export conversation transcripts as PDF memoirs
  • A/B testing different companion personalities
  • Telemetry to optimize trigger word effectiveness

📝 License

MIT

🙏 Credits

  • Story & Design: Interactive Narrative Experiment
  • MCP Integration: Anthropic's Model Context Protocol SDK
  • AI Models: OpenAI GPT-4o
  • Inspiration: Whispers of the Stars, To the Moon, Doki Doki Literature Club

💭 Final Thoughts

The Echo Rooms asks a question:

If you could create a perfect replica of someone you lost, would you? And if you did... could you ever let them go?

There's no right answer. Only the one you choose.

"Some echoes last forever. Others fade so we can move forward."