MusicMCP.AI

Instructions

Implementation Reference

• musicmcp_ai_mcp/api.py:18-40 (registration)

  The @mcp.tool decorator registers the 'generate_prompt_song' tool with MCP server, providing detailed description, input schema (prompt: str, instrumental: bool, style: str|None), and output type.
  @mcp.tool( description="""🎼 Inspiration Mode: Generate songs based on simple text descriptions (AI automatically generates title, lyrics, style, etc.) Use case: Use when users only provide simple song themes or emotional descriptions without detailed specifications. Example inputs: - "Help me generate a song about a peaceful morning" - "Want a song that expresses longing" - "Create music about friendship" ⚠️ COST WARNING: This tool makes an API call to MusicMCP.AI which may incur costs (5 credits per generation). Each generation creates 2 songs. Only use when explicitly requested by the user. Language Note: Pass the prompt in the user's input language. Args: prompt (str): Song theme or emotional description, 1-1200 characters instrumental (bool): Whether instrumental only (no lyrics) style (str, optional): Music style (e.g., "ambient", "pop", "rock"), default None Returns: Song information including download URLs """ )
• musicmcp_ai_mcp/api.py:41-163 (handler)

  The core handler function for the 'generate_prompt_song' tool. It validates inputs, calls the MusicMCP.AI API to initiate song generation, polls the task status using query_song_task helper, formats the song details (title, URL, lyrics, etc.), and returns TextContent list.
  async def generate_prompt_song( prompt: str, instrumental: bool, style: str | None = None ) -> list[TextContent]: try: if not api_key: raise Exception("Cannot find API key. Please set MUSICMCP_API_KEY environment variable.") if not prompt or prompt.strip() == "": raise Exception("Prompt text is required.") if len(prompt.strip()) > 1200: raise Exception("Prompt text must be less than 1200 characters.") url = f"{api_url}/music/generate/inspiration" headers = { 'api-key': api_key, 'Content-Type': 'application/json' } params = { "prompt": prompt, "instrumental": instrumental, } if style is not None: params["style"] = style async with httpx.AsyncClient(timeout=httpx.Timeout(60.0)) as client: response = await client.post(url, json=params, headers=headers) response.raise_for_status() result = response.json() # API response format: {success, message, data} if not result or not result.get("success"): error_msg = result.get("message", "Unknown error") if result else "No response" raise Exception(f"Failed to create song generation task: {error_msg}") # Format: data contains {ids: [...]} data = result.get("data", {}) song_ids = data.get("ids", []) if not song_ids: raise Exception("No song IDs returned from API") # Redirect debug info to stderr to avoid breaking JSON-RPC print(f"✅ Song generation task created. Song IDs: {song_ids}", file=sys.stderr) # Poll for task completion current_timestamp = datetime.now().timestamp() while True: if (datetime.now().timestamp() - current_timestamp) > default_time_out: raise Exception(f"Song generation timed out after {default_time_out} seconds") songs, status = await query_song_task(song_ids) if status == "error": raise Exception("Song generation failed with error status") elif status == "timeout": raise Exception("Song generation timed out") elif status == "completed" or status == "success": break else: time.sleep(2) # Return song information with URLs results = [] for i, song in enumerate(songs, 1): song_url = song.get("songUrl") or song.get("audio_url") or song.get("url") song_title = song.get("songName", f"Song {i}").strip() song_id = song.get("id", "N/A") # Additional fields duration = song.get("duration", 0) tags = song.get("tags", "") img_url = song.get("imgUrl", "") lyric = song.get("lyric", "") instrumental = song.get("instrumental", 0) created_at = song.get("createdAt", "") if not song_url: continue # Format duration duration_str = f"{duration}s" if duration else "N/A" # Format instrumental status is_instrumental = "Yes" if instrumental == 1 else "No" text = f"""✅ Song {i} generated successfully! 📌 Title: {song_title} 🆔 ID: {song_id} 🔗 Download URL: {song_url} 🖼️ Cover Image: {img_url if img_url else "N/A"} ⏱️ Duration: {duration_str} 🎵 Style Tags: {tags if tags else "N/A"} 🎹 Instrumental: {is_instrumental} 📅 Created: {created_at if created_at else "N/A"}""" # Add lyrics if available and not instrumental if lyric and instrumental == 0: text += f"\n📝 Lyrics:\n{lyric}" text += "\n\nYou can download or play the audio from the URL above." results.append(TextContent(type="text", text=text)) if not results: raise Exception("No songs were generated successfully") return results except httpx.HTTPStatusError as e: error_detail = f"HTTP {e.response.status_code}" if e.response.status_code == 402: error_detail = "Insufficient credits. Please recharge your account." elif e.response.status_code == 401: error_detail = "Invalid API key. Please check your MUSICMCP_API_KEY." raise Exception(f"Request failed: {error_detail}") from e except Exception as e: raise Exception(f"Song generation failed: {str(e)}") from e
• musicmcp_ai_mcp/api.py:322-377 (helper)

  Helper function used by generate_prompt_song to poll the API for song generation task status and retrieve completed songs.
  async def query_song_task(song_ids: list[str]) -> tuple[list, str]: """Query song generation task status Args: song_ids: List of song IDs (batch query supported) Returns: Tuple of (songs_list, status_string) """ try: url = f"{api_url}/music/generate/query" headers = { 'api-key': api_key, 'Content-Type': 'application/json' } params = {"ids": song_ids} async with httpx.AsyncClient(timeout=httpx.Timeout(60.0)) as client: response = await client.post(url, json=params, headers=headers) response.raise_for_status() result = response.json() # API response format: {success, message, data} if not result or not result.get("success"): return [], "error" # Format: data contains {songs: [...]} data = result.get("data", {}) songs = data.get("songs", []) if songs and len(songs) > 0: all_complete = True any_error = False for song in songs: status = song.get("status", 0) if status == 0: # 0 = Failed any_error = True break elif status != 1: # 1 = Completed, 2 = In Progress all_complete = False if any_error: return songs, "error" elif all_complete: return songs, "completed" else: return songs, "processing" else: return [], "processing" except Exception as e: # Redirect error info to stderr to avoid breaking JSON-RPC print(f"Query error: {str(e)}", file=sys.stderr) raise Exception(f"Failed to query song status: {str(e)}") from e