🧭 wheriflo

# Describe it. AI builds it.
Go play it.

MCP Server & CLI for Wherigo

Build GPS-based interactive adventures with plain English. wheriflo is an MCP server and CLI that lets AI create, test, and compile Wherigo geocaching cartridges for you.

Get Started View on GitHub
Copilot Chat
You: Create a mystery cartridge about Pioneer Square
AI: wheriflo_init scaffolding project… ✓
AI: wheriflo_lint checking for mistakes… ✓ clean
AI: wheriflo_build compiling… ✓ PioneerSquare.gwc
AI: wheriflo_play starting player… localhost:8000
AI: wheriflo_teleport "Smith Tower" ✓ OnEnter fired
AI: All 5 zones tested. Ready to upload!

What is Wherigo? — A GPS-based interactive game. Players walk to real-world locations with their phone, and the app tells a story, asks questions, and reveals secrets as they explore. Think of it as a location-based choose-your-own-adventure.

How It Works

## From idea to adventure in four steps

You don't need to write code. Just describe what you want.

1

### Describe It

Tell the AI what kind of adventure you want—a mystery, a history walk, a scavenger hunt. Give it GPS coordinates from Google Maps.

→
2

### AI Builds It

The AI scaffolds the project, writes all the Lua code, lints for mistakes, and compiles it—automatically.

→
3

### Play-Test & Refine

Test in the browser, then ask for changes. “Make the puzzle harder.” “Add a hint at stop 3.” The AI rebuilds and retests after every tweak.

→
4

### Go Play It

Upload the finished cartridge to wherigo.com, open the Wherigo app on your phone, and walk the real-world route.

Works with any MCP client

GitHub Copilot Claude Desktop Claude Code Cursor OpenAI Codex Zed
Features

## Everything you need to build Wherigo cartridges

From scaffolding to publishing—wheriflo handles the entire creation workflow.

🏗️

### Project Scaffolding

One command creates a complete cartridge project with a starter Lua template, all required metadata fields, and GPS coordinates ready to customize.

🔍

### Smart Linting

Catches Wherigo-specific mistakes that crash players—like iOS-breaking nil assignments, wrong enums, and Groundspeak compiler bugs—before you build.

⚙️

### Local & Cloud Compile

Build locally to .gwc/.gwz for instant testing, or validate through the official Groundspeak compiler API to guarantee compatibility with all Wherigo players.

🎮

### Browser Play-Testing

A built-in web player lets you (and the AI) walk through every zone, message, and choice in your browser. Auto-reloads on file changes.

🔒

### Sandboxed Lua Engine

A secure Lua 5.1 runtime with the Wherigo API shimmed in. Dangerous modules (io, os, debug) are removed. Safe for AI-driven play-testing.

🖼️

### Image & Media Support

Embed JPG, PNG, GIF, BMP images and MP3, WAV, OGG audio. The packager discovers media declarations and bundles them into the cartridge automatically.

📚

### Built-in Documentation

API reference, design guide, and starter template are available as MCP resources. The AI reads them automatically to write correct code.

🚀

### Publish Workflow

When you're ready, wheriflo opens wherigo.com and copies the file path to your clipboard. Tracks your cartridge GUID for seamless updates.

🔑

### Secure Credentials

Wherigo.com credentials stored in your OS keyring (Windows Credential Manager, macOS Keychain, Linux Secret Service). Never logged or exposed.

MCP Server

## 16 tools, 3 resources, 2 prompts

The AI uses these tools behind the scenes. You just talk in plain English.

`wheriflo_init` Scaffold project
`wheriflo_build` Compile locally
`wheriflo_compile` Groundspeak API
`wheriflo_lint` Check for mistakes
`wheriflo_play` Start web player
`wheriflo_teleport` Enter a zone
`wheriflo_leave_zone` Exit a zone
`wheriflo_set_position` Set GPS coords
`wheriflo_respond` Answer prompts
`wheriflo_autoplay` Batch play-test
`wheriflo_get_state` Inspect game state
`wheriflo_get_resource` Read docs
`wheriflo_validate` Validate .gwc
`wheriflo_publish` Upload to wherigo.com
`wheriflo_reset` Full state wipe
`wheriflo_stop` Stop web player

### Resources

`api-reference` `design-guide` `lua-template`

### Prompts

`design-cartridge` `review-cartridge`
Command Line

## Or use the CLI directly

Every MCP tool is also available as a CLI command. No AI editor required.

# Scaffold a new cartridge
wheriflo init "My Adventure" --author "Jane" --location 47.6,-122.3
# Test in browser (auto-reloads on save)
wheriflo play MyAdventure.lua --watch
# Build for release
wheriflo build MyAdventure.lua
# Compile via official Groundspeak API
wheriflo compile MyAdventure.lua
# Publish to wherigo.com
wheriflo publish MyAdventure.lua
AI Workflow

## What happens when you ask AI to create a cartridge

The AI handles every step automatically. You just describe what you want.

💬

### You describe your idea

"Create a mystery about the history of Pioneer Square with 5 stops"

📍

### AI asks for GPS coordinates

Right-click any location on Google Maps to copy coordinates

🏗️

### AI scaffolds the project

Creates the directory, starter file, and all required metadata

✍️

### AI writes the Lua code

Zones, messages, items, puzzles, branching storylines—all generated

🔍

### AI lints and fixes mistakes

Catches iOS crashes, compiler bugs, and Wherigo-specific pitfalls

⚙️

### AI builds and compiles

Produces the .gwc file and validates with the Groundspeak compiler

🎮

### AI play-tests every path

Enters every zone, answers every question, verifies the ending

✅

### Ready to upload

You get a finished .gwc file to publish on wherigo.com and play on your phone

Get Started

## Set up in under 2 minutes

Install Python and uv, add one config snippet, and you're ready to go.

### Prerequisites

🐍
Python 3.10+ — python.org/downloads
📦
uv (recommended) — astral.sh/uv

### Connect to your AI editor

Create `.vscode/mcp.json` in your project:

.vscode/mcp.json

    {
        "servers": {
            "wherigo": {
                "command": "uvx",
                "args": ["wheriflo", "mcp"]
            }
        }
    }

Restart VS Code, open Copilot Chat, and ask it to create a Wherigo cartridge.

Add to `claude_desktop_config.json`:

claude_desktop_config.json

    {
        "mcpServers": {
            "wherigo": {
                "command": "uvx",
                "args": ["wheriflo", "mcp"]
            }
        }
    }

On Windows, use `"command": "cmd"` and `"args": ["/c", "uvx", "wheriflo", "mcp"]`.

Run one command:

Terminal

    claude mcp add wherigo -- uvx wheriflo mcp

Run one command:

Terminal

    codex mcp add -- uvx wheriflo mcp

Add to Cursor Settings → MCP Servers:

Cursor MCP Config

    {
        "mcpServers": {
            "wherigo": {
                "command": "uvx",
                "args": ["wheriflo", "mcp"]
            }
        }
    }

Install permanently instead of using `uvx`:

Terminal

    pip install wheriflo

Then replace `"command": "uvx", "args": ["wheriflo", "mcp"]` with `"command": "wheriflo", "args": ["mcp"]` in any config above.

Try It

## Your first cartridge

After setup, open your AI chat and paste this prompt. Replace the location with somewhere near you.

    Create a Wherigo cartridge about the history of Pioneer Square
    in Seattle. Start at Smith Tower (47.6019, -122.3317) and
    include 4 stops within walking distance. Make it a mystery
    with multiple choice questions at each stop.

The AI will scaffold the project, write the story, lint it, build it, play-test every path, and give you a finished `.gwc` file ready to upload.

## Ready to build your first adventure?

Open source. Free to use. Works with any MCP-compatible AI assistant.

Get Started View on GitHub →
$ pip install wheriflo