Murder Mystery MCP Server for Puch AI

This project is an interactive, conversational detective game built to run with Puch AI, a WhatsApp-only AI agent.

Players step into the role of a detective to solve the murder of Lord Alistair Blackwood. By investigating rooms, examining clues, and interrogating suspects, you can piece together the motive, the weapon, and the killer's identity, all through natural language commands in your WhatsApp chat.

This server was built for the Puch AI hackathon using Python, FastMCP, and is deployed on Render.

Play the Live Game: https://puch.ai/mcp/u7kVc1s1wY

Features

• Conversational Gameplay: Uses natural language to interact with the game world.
• Interactive Story: A branching narrative with puzzles, clues, and red herrings.
• Stateful Game Engine: The MCP server manages the player's location, inventory, and the state of the mystery.
• Puch AI Integration: Includes a validate tool for seamless connection with the Puch AI platform.
• Multiple Tools: The game is powered by a suite of MCP tools, including go, examine, collect, interrogate, and accuse.

Deployment

This server is designed for easy deployment on a platform like Render.

1. Project Structure

The repository contains two main Python files:

• main.py: Contains all the game logic, including the world map, clues, and the definitions for all the MCP tools.
• server.py: A simple runner script that imports the application from main.py and starts the server.

2. Requirements

• fastmcp>=2.0
• pydantic>=2.0.0
• uvicorn>=0.29.0

3. Setting Up ngrok

ngrok is used to create a secure, public URL to your local machine, allowing you to test your server with the Puch AI platform before deploying.

1. Sign Up for ngrok: Go to the ngrok dashboard and create a free account.

2. Download ngrok: Download the ngrok executable for your operating system from the download page. Unzip the file to a location you can easily access.

3. Connect Your Account: To connect your account, you'll need your authtoken. Find it on your ngrok dashboard. Then, run the following command in your terminal, replacing YOUR_AUTHTOKEN with the token you copied:

ngrok config add-authtoken YOUR_AUTHTOKEN

---

4. Local Setup

To run this project on your local machine, follow these steps:

1. Clone the repository:

git clone https://github.com/NarainBK/Murder_Mystery_MCP.git
cd Murder_Mystery_MCP

2. Create a .env file:

TOKEN="YOUR-SECRET-TOKEN"
MY_NUMBER="YOUR_MOBILE_NUMBER_HERE_WITH_COUNTRY_CODE"

3. Install dependencies:

# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install required packages
pip install -r requirements.txt

4. Run the server:

python server.py

5. Connect to ngrok: Open a second, separate terminal window and run the following command. This starts the tunnel to your local server.

ngrok http 8000

6. Connect to Puch AI

• Open Puch AI in WhatsApp
• Use the connect command:

/mcp connect https://your-domain.ngrok.app/mcp your_secret_token_here

• Debug Mode: To get more detailed error messages:

/mcp diagnostics-level debug