# 🐍 Snake MCP App

A fully playable Snake game, built as an [MCP App](https://modelcontextprotocol.io) — play it directly inside ChatGPT, Claude, or any MCP-compatible chat client, no separate browser tab required.

**Live server:** `https://snake-mcp.onrender.com/mcp`

> ⚠️ Hosted on Render's free tier — the first request after ~15 minutes of inactivity can take 30–60 seconds while the instance wakes up. After that, it's instant.

---

## What this is

This project demonstrates how a real game can be embedded directly inside any [MCP](https://modelcontextprotocol.io)-compatible client — ChatGPT, Claude, or anything else that speaks the protocol — turning a chat interface into a place you can actually play, not just talk.

Most MCP tool calls round-trip to the host for every single action, which makes anything real-time (like a game) feel laggy if implemented naively. This project avoids that by exposing just **one MCP tool** (`start_game`) that opens a self-contained, client-side HTML/JS app inside the host's UI. Once launched, the game runs entirely in the browser — movement, collisions, scoring — with zero network calls per frame, so it plays smoothly regardless of which MCP client it's running in.

## Features

- Classic Snake gameplay — arrow keys or WASD, Space to pause
- **Walls** or **No Walls** (wrap-through) modes
- Speed control — Slow / Medium / Fast, adjustable live mid-game
- Pause / Resume
- Bonus food — a pulsing ⭐ worth +50 points, appears randomly and disappears after 5 seconds if not eaten
- Emoji food (🍎🍌🍇🍊🍓🍒🍉🍍) instead of plain shapes
- Rounded, animated snake with a directional face

## How to play

1. Connect the MCP server URL above in your client (ChatGPT Developer Mode / custom app, Claude, or any MCP-compatible host).
2. Ask it to start the game — e.g. *"Start the snake game"*.
3. Play using arrow keys, WASD, or the on-screen controls.

## Architecture

```
ChatGPT / Claude / any MCP host
            │
            ▼
   start_game (MCP tool)
            │
            ▼
   ui://snake/game (MCP App resource)
            │
            ▼
  Self-contained HTML/CSS/JS
  (game logic runs entirely
   client-side after launch)
```

- **`server.py`** — Python MCP server (`mcp` SDK v2) wrapped in a small Starlette app. Exposes the single `start_game` MCP tool (mounted under `/mcp`), plus a `/health` endpoint and a `/` info endpoint.
- **`ui/`** — Vite-built frontend. `game.js` contains the full Snake game logic (movement, collisions, scoring, bonus food) — nothing here calls back to the server during gameplay.
- **`build_ui.py`** — inlines Vite's built CSS/JS into a single self-contained `dist/mcp_app.html`, since MCP App resources work best as one file with no external asset requests.
- **`Dockerfile`** — two-stage build: Node stage builds the UI, Python stage runs the server. Used for deployment on Render.

## Running locally

```bash
npm install
npm run build              # builds ui/ -> dist/mcp_app.html
python -m venv .venv
.venv\Scripts\activate      # Windows; use source .venv/bin/activate on macOS/Linux
pip install -r requirements.txt
python server.py            # runs on http://127.0.0.1:8000/mcp
```

Test it with [MCP Inspector](https://github.com/modelcontextprotocol/inspector) (Streamable HTTP, connect to `http://127.0.0.1:8000/mcp`) before connecting a live host.

## Deployment

Deployed on [Render](https://render.com) as a Docker-based Web Service, built directly from this repo's `Dockerfile`. Any push to `main` triggers a new deploy.

## Tech stack

- [MCP Python SDK v2](https://py.sdk.modelcontextprotocol.io/) — server + Apps extension
- Vite — frontend build
- Vanilla JS/HTML5 Canvas — no frontend framework, kept intentionally lightweight
- Render — hosting