VibeTide MCP Server

Instructions

Implementation Reference

• vibe_tide_mcp_server.py:633-692 (handler)

  The main handler function for the 'edit_level_metadata' tool. Decorated with @mcp.tool() for automatic registration. Decodes the level, updates specified metadata fields, re-encodes, and returns the updated level data.
  @mcp.tool() async def edit_level_metadata( encoded_level: str, new_name: Optional[str] = None, new_description: Optional[str] = None, max_enemies: Optional[int] = None, enemy_spawn_chance: Optional[float] = None, coin_spawn_chance: Optional[float] = None, ) -> Dict[str, Any]: """Edit only the metadata of a VibeTide level without changing the tile layout. This is much more efficient than edit_entire_level when you only want to change game parameters like enemy count, spawn rates, name, or description. Args: encoded_level: The encoded level string to modify new_name: New name for the level (optional) new_description: New description for the level (optional) max_enemies: Maximum enemies parameter (0-10, optional) enemy_spawn_chance: Enemy spawn chance percentage (0-100, optional) coin_spawn_chance: Coin spawn chance percentage (0-100, optional) Returns: The modified level data with new encoded string """ try: # Decode the existing level to get current data level_data = level_encoder.decode(encoded_level) # Update only the specified parameters (keep existing if not specified) if new_name is not None: level_data["name"] = new_name if new_description is not None: level_data["description"] = new_description if max_enemies is not None: level_data["maxEnemies"] = max_enemies if enemy_spawn_chance is not None: level_data["enemySpawnChance"] = enemy_spawn_chance if coin_spawn_chance is not None: level_data["coinSpawnChance"] = coin_spawn_chance # Re-encode with the updated metadata new_encoded_level = level_encoder.encode(level_data) level_url = f"{VIBE_TIDE_CONFIG['web_player_url']}?level={new_encoded_level}" level_data["level_url"] = level_url return { "success": True, "level_data": level_data, "encoded_level": new_encoded_level, "play_url": level_url, "change_summary": "Updated metadata only - tiles unchanged", "message": f"Successfully updated level metadata", } except Exception as e: logger.error(f"Failed to edit level metadata: {e}") return {"success": False, "error": f"Failed to edit level metadata: {str(e)}"}
• vibe_tide_mcp_server.py:647-656 (schema)

  Input schema and output description defined in the function docstring, used by FastMCP to generate JSON schema for the tool.
  Args: encoded_level: The encoded level string to modify new_name: New name for the level (optional) new_description: New description for the level (optional) max_enemies: Maximum enemies parameter (0-10, optional) enemy_spawn_chance: Enemy spawn chance percentage (0-100, optional) coin_spawn_chance: Coin spawn chance percentage (0-100, optional) Returns: The modified level data with new encoded string
• vibe_tide_mcp_server.py:81-323 (helper)

  LevelEncoder class and global instance used by edit_level_metadata for decoding and encoding level data.
  class LevelEncoder: """Fast level encoding/decoding without agent tools""" def __init__(self): # Character mapping for tiles (URL-safe) self.tile_chars = { 0: ".", # Empty - most common 1: "G", # Grass 2: "R", # Rock 3: "Y", # Yellow 4: "I", # Ice 5: "F", # Fire/Red 6: "S", # Spikes 7: "W", # Water } self.char_tiles = {char: tile for tile, char in self.tile_chars.items()} def encode(self, level_data: Dict[str, Any]) -> str: """Encode level data to URL-safe string""" try: tiles = level_data.get("tiles", []) if not tiles: raise ValueError("No tiles found") height = len(tiles) width = len(tiles[0]) if tiles else 0 # Convert 2D array to character string tile_string = "" for row in tiles: for tile in row: tile_string += self.tile_chars.get(tile, ".") # Apply run-length encoding for empty tiles tile_string = self._run_length_encode(tile_string) # Create base format encoded = f"{width}x{height}:{tile_string}" # Add game parameters if provided params = {} for param in ["maxEnemies", "enemySpawnChance", "coinSpawnChance"]: if param in level_data and level_data[param] is not None: params[param] = level_data[param] if params: params_json = json.dumps(params) encoded += f"|{self._base64url_encode(params_json)}" return self._base64url_encode(encoded) except Exception as e: logger.error(f"Failed to encode level: {e}") raise ValueError(f"Level encoding failed: {str(e)}") def decode(self, encoded_string: str) -> Dict[str, Any]: """Decode URL-safe string back to level data""" try: encoded_string = encoded_string.strip() if not encoded_string: raise ValueError("Empty encoded string") # Decode from base64url decoded = self._base64url_decode(encoded_string) # Parse parameters if present main_data = decoded game_params = {} if "|" in decoded: parts = decoded.split("|", 1) if len(parts) == 2: main_data, params_data = parts try: params_json = self._base64url_decode(params_data) game_params = json.loads(params_json) except Exception as e: logger.warning(f"Failed to parse parameters: {e}") # Parse format: widthxheight:encoded_data if ":" not in main_data: raise ValueError("Invalid format: missing colon") dimensions, tile_data = main_data.split(":", 1) if "x" not in dimensions: raise ValueError("Invalid format: missing dimensions") width, height = map(int, dimensions.split("x")) if width < 1 or height < 1: raise ValueError(f"Invalid dimensions: {width}x{height}") # Decode run-length encoding tile_string = self._run_length_decode(tile_data) # Convert back to 2D array tiles = [] index = 0 for y in range(height): tiles.append([]) for x in range(width): char = tile_string[index] if index < len(tile_string) else "." tiles[y].append(self.char_tiles.get(char, 0)) index += 1 result = { "tiles": tiles, "width": width, "height": height, "name": self._generate_level_name(tiles), } # Add game parameters for param in ["maxEnemies", "enemySpawnChance", "coinSpawnChance"]: if param in game_params: result[param] = game_params[param] return result except Exception as e: logger.error(f"Failed to decode level: {e}") raise ValueError(f"Level decoding failed: {str(e)}") def _run_length_encode(self, s: str) -> str: """Run-length encoding for repeated empty tiles""" if not s: return s result = "" count = 1 current = s[0] for i in range(1, len(s)): if s[i] == current and current == ".": count += 1 else: if current == "." and count > 2: result += f".{count}" else: result += current * count current = s[i] count = 1 # Handle final sequence if current == "." and count > 2: result += f".{count}" else: result += current * count return result def _run_length_decode(self, s: str) -> str: """Decode run-length encoding""" result = "" i = 0 while i < len(s): char = s[i] if char == "." and i + 1 < len(s) and s[i + 1].isdigit(): # Extract number num_str = "" j = i + 1 while j < len(s) and s[j].isdigit(): num_str += s[j] j += 1 count = int(num_str) result += "." * count i = j else: result += char i += 1 return result def _base64url_encode(self, s: str) -> str: """URL-safe base64 encoding""" encoded = base64.b64encode(s.encode("utf-8")).decode("ascii") return encoded.replace("+", "-").replace("/", "_").rstrip("=") def _base64url_decode(self, s: str) -> str: """URL-safe base64 decoding""" try: # Add padding if necessary padding = (4 - len(s) % 4) % 4 s += "=" * padding s = s.replace("-", "+").replace("_", "/") decoded_bytes = base64.b64decode(s) return decoded_bytes.decode("utf-8") except Exception as e: logger.error(f"Base64 decode error: {e}") raise ValueError(f"Invalid base64 encoding: {str(e)}") def _generate_level_name(self, tiles: List[List[int]]) -> str: """Generate a name based on level content""" stats = self._analyze_level_content(tiles) name = "" if stats["water"] > 0.3: name += "Aquatic " if stats["spikes"] > 0.1: name += "Dangerous " if stats["ice"] > 0.2: name += "Icy " if stats["platforms"] < 0.1: name += "Minimal " if stats["platforms"] > 0.4: name += "Dense " name += "Adventure" return name.strip() def _analyze_level_content(self, tiles: List[List[int]]) -> Dict[str, float]: """Analyze level content for statistics""" if not tiles: return { "empty": 1.0, "platforms": 0.0, "ice": 0.0, "dangerous": 0.0, "spikes": 0.0, "water": 0.0, } total = len(tiles) * len(tiles[0]) counts = {i: 0 for i in range(8)} for row in tiles: for tile in row: counts[tile] = counts.get(tile, 0) + 1 return { "empty": counts[0] / total, "platforms": (counts[1] + counts[2] + counts[3]) / total, "ice": counts[4] / total, "dangerous": counts[5] / total, "spikes": counts[6] / total, "water": counts[7] / total, }