VibeTide MCP Server

Instructions

Implementation Reference

• vibe_tide_mcp_server.py:570-598 (handler)

  The @mcp.tool()-decorated async function implementing the core logic of the 'view_level' tool: decodes the input encoded_level using LevelEncoder, generates an ASCII visualization via visualize_level, constructs a play URL, and returns structured level data.
  @mcp.tool() async def view_level(encoded_level: str) -> Dict[str, Any]: """View a VibeTide level with visual representation. Args: encoded_level: An encoded level string from a URL or sharing link Returns a visual representation of the level. """ try: # Decode level from string level_data = level_encoder.decode(encoded_level) play_url = f"{VIBE_TIDE_CONFIG['web_player_url']}?level={encoded_level}" # Generate visualization visualization = visualize_level(level_data) return { "success": True, "level_data": level_data, "visualization": visualization, "play_url": play_url, "message": "Level visualized successfully", } except Exception as e: logger.error(f"Failed to view level: {e}") return {"success": False, "error": f"Failed to view level: {str(e)}"}
• vibe_tide_mcp_server.py:438-481 (helper)

  Helper function called by view_level to generate an ASCII art visualization of the level layout using tile symbols, including level info, parameters, layout grid, and legend.
  def visualize_level(level_data: Dict[str, Any]) -> str: """Create a visual representation of the level using symbols""" tiles = level_data.get("tiles", []) if not tiles: return "Empty level" visualization = [] visualization.append(f"Level: {level_data.get('name', 'Unnamed')}") visualization.append(f"Size: {len(tiles[0])}x{len(tiles)}") # Add game parameters if present params = [] if "maxEnemies" in level_data: params.append(f"Max Enemies: {level_data['maxEnemies']}") if "enemySpawnChance" in level_data: params.append(f"Enemy Spawn: {level_data['enemySpawnChance']}%") if "coinSpawnChance" in level_data: params.append(f"Coin Spawn: {level_data['coinSpawnChance']}%") if params: visualization.append("Parameters: " + ", ".join(params)) visualization.append("\nLevel Layout:") visualization.append("=" * (len(tiles[0]) + 2)) for row in tiles: row_str = "|" for tile in row: symbol = TILE_TYPES.get(tile, {"symbol": "?"})["symbol"] row_str += symbol row_str += "|" visualization.append(row_str) visualization.append("=" * (len(tiles[0]) + 2)) # Add legend visualization.append("\nTile Legend:") for tile_id, tile_info in TILE_TYPES.items(): visualization.append( f" {tile_info['symbol']} = {tile_info['name']} ({tile_info['description']})" ) return "\n".join(visualization)
• vibe_tide_mcp_server.py:81-323 (helper)

  The LevelEncoder class provides the decode method used in view_level to parse the encoded_level string into structured level data (tiles, dimensions, etc.). Global instance: level_encoder.
  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, }