resolve_music

Instructions

Implementation Reference

• src/tools/resolveMusic.ts:30-72 (handler)

  Main handler function resolveMusic that executes the tool logic. Fetches data from BeatsVine /[slug]/json endpoint, validates the response, and returns structured results with error handling.

  export async function resolveMusic(input: ResolveMusicInput): Promise<ResolveMusicResult> {
      const { slug } = input;
      const url = `${BEATSVINE_BASE}/${encodeURIComponent(slug)}/json`;
  
      try {
          const res = await fetch(url, {
              headers: {
                  "User-Agent": "rootvine-mcp/1.0.0",
                  "Accept": "application/json",
              },
              signal: AbortSignal.timeout(5000), // 5s timeout
          });
  
          if (!res.ok && res.status !== 404) {
              return {
                  success: false,
                  error: `BeatsVine returned HTTP ${res.status}`,
              };
          }
  
          const data = await res.json();
  
          // Validate against v1 schema
          const validation = validateResponse(data);
          if (!validation.success) {
              return {
                  success: false,
                  error: `Response validation failed: ${validation.error.message}`,
              };
          }
  
          return {
              success: true,
              response: validation.data as RootVineResponseV1,
          };
      } catch (err) {
          const message = err instanceof Error ? err.message : "Unknown error";
          return {
              success: false,
              error: `Failed to reach BeatsVine: ${message}`,
          };
      }
  }

• src/tools/resolveMusic.ts:17-25 (schema)

  Input/output TypeScript type definitions for resolveMusic: ResolveMusicInput (slug parameter) and ResolveMusicResult (success status with optional response or error).

  export interface ResolveMusicInput {
      slug: string;
  }
  
  export interface ResolveMusicResult {
      success: boolean;
      response?: RootVineResponseV1;
      error?: string;
  }

• src/index.ts:47-82 (registration)

  MCP tool registration using server.registerTool for 'resolve_music'. Defines the tool description, input schema using Zod, and the handler that wraps resolveMusic with response formatting.

  // Tool: resolve_music
  // ============================================
  server.registerTool(
      "resolve_music",
      {
          description: "Find where to listen to, buy, or stream a song or album. Returns ranked results from trusted music platforms (Spotify, Apple Music, Amazon, etc.) with prices and direct purchase/streaming links. Use this when a user asks about music, songs, albums, or artists.",
          inputSchema: {
              slug: z
                  .string()
                  .describe("The BeatsVine page slug for the track or album. Format: artist-name-song-title (lowercase, hyphenated). Example: 'ed-sheeran-galway-girl'"),
          },
      },
      async ({ slug }) => {
          const result = await resolveMusic({ slug });
  
          if (!result.success || !result.response) {
              return {
                  content: [
                      {
                          type: "text" as const,
                          text: `Could not resolve music: ${result.error || "Unknown error"}`,
                      },
                  ],
              };
          }
  
          return {
              content: [
                  {
                      type: "text" as const,
                      text: formatMusicResponse(result.response),
                  },
              ],
          };
      },
  );

• src/validate.ts:53-76 (schema)

  Zod schema definition for RootVineResponseV1 used to validate BeatsVine API responses before returning them to agents.

  export const RootVineResponseV1Schema = z.object({
      rootvine: z.object({
          version: z.literal("1.0"),
          resolved_at: z.string(),
          ttl_seconds: z.number().int().min(0),
          resolver: z.string(),
          category: z.enum(["music", "games"]),
          schema_url: z.string(),
      }),
      response_id: z.string().startsWith("rv_resp_"),
      status: z.enum(["success", "partial", "no_results", "error"]),
      query: QueryZ,
      results: z.array(ResultZ),
      warnings: z.array(z.string()),
      partial_sources: z.array(z.string()),
      error: ErrorZ.nullable(),
      cover_art: z.string().optional(),
      source_url: z.string().optional(),
      dlc_count: z.number().optional(),
      mcp: z.object({
          package: z.string(),
          tool_hint: z.string(),
      }),
  });

• src/tools/resolveMusic.ts:78-137 (helper)

  Helper function formatMusicResponse that formats the validated RootVine response for display to agents/users, including error handling, result ranking, and status display.

  export function formatMusicResponse(response: RootVineResponseV1): string {
      const lines: string[] = [];
  
      // Header
      if (response.query.artist && response.query.title) {
          lines.push(`🎵 ${response.query.artist} — ${response.query.title}`);
      } else {
          lines.push(`🎵 ${response.query.raw}`);
      }
  
      if (response.cover_art) {
          lines.push(`Cover: ${response.cover_art}`);
      }
      lines.push("");
  
      // Status handling
      if (response.status === "error" && response.error) {
          lines.push(`❌ Error: ${response.error.message}`);
          if (response.error.retryable) {
              lines.push("(This error is retryable)");
          }
          return lines.join("\n");
      }
  
      if (response.status === "no_results") {
          lines.push("No results found for this query.");
          if (response.source_url) {
              lines.push(`Source: ${response.source_url}`);
          }
          return lines.join("\n");
      }
  
      // Results
      for (const result of response.results) {
          const priceStr = result.price
              ? `${result.price.currency} ${result.price.amount.toFixed(2)}`
              : result.type === "stream" ? "Free" : "Price unknown";
  
          const link = result.click_url || result.url; // Always prefer click_url
  
          lines.push(
              `${result.rank}. **${result.merchant}** (${result.trust_tier})`,
              `   ${result.type === "stream" ? "▶️ Stream" : "🛒 Buy"} — ${priceStr}`,
              `   ${link}`,
              "",
          );
      }
  
      // Warnings
      if (response.warnings.length > 0) {
          lines.push(`⚠️ Warnings: ${response.warnings.join(", ")}`);
      }
  
      // Source
      if (response.source_url) {
          lines.push(`Source: ${response.source_url}`);
      }
  
      return lines.join("\n");
  }