Skip to main content
Glama
nazroll

wzrdbrain MCP Server

by nazroll
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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)

Related MCP server: MuJoCo MCP Server

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

Available Tools

3 tools
generate_skating_comboA

Generates a physics-aware sequence of wizard-style inline skating tricks.

Args: num_tricks: The number of tricks to chain together in the combo. Must be between 1 and 20. Defaults to 3.

ParametersJSON Schema
NameRequiredDescriptionDefault
num_tricksNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions 'physics-aware' and the parameter range, but does not disclose potential side effects, authorization needs, or output behavior beyond what the output schema might provide. The tool is likely a safe generation, but more detail is needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences covering purpose and parameter details. Every sentence adds value, and the structure is front-loaded with the main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description is fairly complete. It explains the generation logic and parameter constraints. Lacking a bit on what 'physics-aware' entails, but the output schema likely covers return structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining the purpose of the single parameter (num_tricks), its valid range (1–20), and its default value (3). This is complete and adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a physics-aware sequence of wizard-style inline skating tricks. The verb 'Generates' and specific resource 'sequence of wizard-style inline skating tricks' sets it apart from sibling tools that retrieve or list tricks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for creating combos rather than listing tricks, but lacks explicit guidance on when to use this tool versus alternatives like 'get_tricks_by_category' or 'list_trick_categories'. No when-not or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tricks_by_categoryA

Retrieves all tricks that fall under a specific category.

Args: category: The category name (e.g., 'pivot', 'slide'). Validated against known categories.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description states input validation ('Validated against known categories') implying possible error for invalid input. No annotations provided, but description does not mention whether the operation is read-only or any side effects. Could add pagination or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Short and front-loaded: first line states purpose. Two sentences efficiently convey key information. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return format need not be detailed. However, description lacks details on error handling (e.g., invalid category) or expected behavior for edge cases. Adequate for a simple query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema provides only name and type ('string') with 0% schema description coverage. Description adds examples and validation intent, but does not specify allowed values or format beyond the examples. Compensates partially.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it retrieves tricks by category, with concrete examples ('pivot', 'slide'). Distinguishes from sibling 'list_trick_categories' (which lists categories) and 'generate_skating_combo' (which generates combinations).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use. Implied usage: use when you need tricks for a specific category. Sibling tools provide context but description does not exclude alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_trick_categoriesA

Retrieves the available categories of inline skating tricks.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states 'Retrieves...' without disclosing any behavioral traits such as read-only nature, authentication needs, or rate limits. The description is insufficient for a read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the tool's purpose without unnecessary words. It earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, output schema exists), the description is minimally adequate. It does not explain what categories include, but the output schema fills that gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the description does not need to add parameter meaning. Baseline for 0 parameters is 4, and the description is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves categories of inline skating tricks, with a specific verb and resource. It distinguishes itself from siblings like 'get_tricks_by_category' which retrieves tricks, not categories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. It is implied that one would list categories before using get_tricks_by_category, but no direct instruction or exclusion is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.2.0
    • First observedgenerate_skating_combo
    • First observedget_tricks_by_category
    • First observedlist_trick_categories
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct purpose: listing categories, retrieving tricks by category, and generating combos. There is no meaningful overlap or risk of selecting the wrong tool.

Naming Consistency4/5

All names use snake_case and follow a clear verb_noun style, but 'list_trick_categories' and 'get_tricks_by_category' mix two different retrieval verbs (list vs get), which is a minor inconsistency.

Tool Count5/5

Three tools is well-suited to this narrow, focused domain. Each tool serves a distinct and necessary role without unnecessary bloat.

Completeness4/5

The core workflow—discover categories, retrieve tricks by category, and generate combos—is fully covered. Minor gaps like listing all tricks without a category or viewing individual trick details are workable but not essential.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MuJoCo MCP Server

    Rongxuan-Zhou
    A
    license
    Not graded
    quality
    D
    maintenance
    Exposes MuJoCo physics simulation to AI assistants via 65 MCP tools, enabling natural language control of robotics simulation, trajectory optimization, contact analysis, and video export.
    8
    MIT

  • imgui-mcp

    SaloQT
    A
    license
    B
    quality
    A
    maintenance
    Enables AI agents to visually design and iterate on Dear ImGui game UIs in real-time with live preview, input simulation, and a wide range of widgets and tools.
    84
    1
    MIT