wzrdbrain MCP Server

An MCP (Model Context Protocol) server that provides a physics-aware combo generator for wizard-style inline skating, powered by the wzrdbrain Python package.

Unlike random trick generators, this server understands skating physics. It models moves as state transitions (direction, edge, stance, weight point), ensuring that the combinations it generates are actually executable and flow naturally.

Prerequisites

• Python 3.13+
• uv for dependency management
• Node.js (optional, for MCP Inspector)

Installation

git clone https://github.com/your-username/wzrdbrain-mcp.git
cd wzrdbrain-mcp
uv sync

Client Configuration

Claude Desktop

Open the configuration file for your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following, replacing <ABSOLUTE_PATH_TO_PROJECT> with the actual path:

{
  "mcpServers": {
    "wzrdbrain": {
      "command": "uv",
      "args": [
        "--directory",
        "<ABSOLUTE_PATH_TO_PROJECT>",
        "run",
        "mcp-server-wzrdbrain"
      ]
    }
  }
}

Restart Claude Desktop. The wzrdbrain tools will appear via the hammer icon in your chat.

Claude Code

claude mcp add wzrdbrain -- uv --directory <ABSOLUTE_PATH_TO_PROJECT> run mcp-server-wzrdbrain

Gemini CLI

Add to .gemini/settings.json (project-level) or ~/.gemini/settings.json (user-level), replacing <ABSOLUTE_PATH_TO_PROJECT> with the actual path:

{
  "mcpServers": {
    "wzrdbrain": {
      "command": "uv",
      "args": [
        "--directory",
        "<ABSOLUTE_PATH_TO_PROJECT>",
        "run",
        "mcp-server-wzrdbrain"
      ]
    }
  }
}

See the Gemini CLI MCP docs for additional options like timeout and env.

MCP Inspector

Test the tools locally before connecting to a client:

npx @modelcontextprotocol/inspector uv run mcp-server-wzrdbrain

Tools

generate_skating_combo

Generates a physics-aware sequence of inline skating tricks.

Parameter	Type	Default	Range
num_tricks	integer	3	1–20

Each line shows the trick name and its entry/exit state (direction/edge/stance/point):

1. Front Soul Slide: front/outside/open/all → front/outside/open/all
2. Front Mizu Slide: front/inside/open/all → front/inside/open/all
3. Front Fast Slide: front/outside/open/all → front/outside/open/all

list_trick_categories

Returns the available trick categories as a sorted list. No parameters.

['base', 'manual', 'pivot', 'slide', 'swivel', 'transition', 'turn']

get_tricks_by_category

Lists all tricks in a given category. Case-insensitive.

Parameter	Type	Required
category	string	yes

Tricks in category:
- Back Predator (Open)
- Back Predator One
- Front Predator (Open)
- Front Predator One

Invalid categories return an error listing valid options:

Error: Invalid category. Valid categories are: base, manual, pivot, slide, swivel, transition, turn

Prompts

skating_practice_routine

A prompt template that instructs the LLM to generate a 4-trick combo and structure it into a 30-minute practice session:

1. Warm-up (5 minutes)
2. Trick Breakdown & Practice (15 minutes)
3. Combo Execution (5 minutes)
4. Cool-down (5 minutes)

Error Messages

Message	Cause
Error: num_tricks must be an integer.	Passed a string, float, or non-integer type
Error: num_tricks must be between 1 and 20.	Value outside the allowed range
Error: Invalid category. Valid categories are: ...	Unrecognized category name
Error generating combo: An internal error occurred...	Unexpected exception from wzrdbrain

---

Development

Setup

uv sync --extra test

Running Tests

# All tests
uv run pytest -v

# Single test
uv run pytest tests/test_server.py::TestGenerateSkatingComboHappy::test_default_three_tricks

# Coverage (target: 100%)
uv run pytest --cov=wzrdbrain_mcp --cov-report=term-missing

Project Structure

src/wzrdbrain_mcp/server.py   # All MCP tools, prompts, and the entry point
tests/test_server.py           # Full test suite
pyproject.toml                 # Dependencies (pinned with ==) and pytest config

Architecture

• FastMCP decorated functions are plain callables — tests call them directly without an MCP client.
• wzrdbrain library provides two touchpoints: wzrdbrain.generate_combo() for combo generation and MOVES dict for the trick catalog.
• State transitions are modeled as direction/edge/stance/point.
• Input validation returns error strings, not exceptions. Maintain this pattern for new tools.
• Output sanitization validates the structure of wzrdbrain responses before formatting.
• Logging goes to stderr only. User input is sanitized via _sanitize_for_log() before logging to prevent log injection.
• Dependencies are pinned with exact versions (==) in pyproject.toml and locked via uv.lock.

Adding a New Tool

1. Add a @mcp.tool() function in server.py
2. Validate all inputs (type checks, range bounds) — return error strings for invalid input
3. Sanitize outputs from wzrdbrain before returning
4. Log user-supplied values through _sanitize_for_log() only
5. Add tests in tests/test_server.py — direct calls for happy paths, unittest.mock.patch for error paths
6. Verify coverage stays at 100%: uv run pytest --cov=wzrdbrain_mcp --cov-report=term-missing
7. Update this README with the new tool's documentation