rootvine-mcp

Instructions

Implementation Reference

• src/tools/resolveGame.ts:29-71 (handler)

  The main handler function that executes the resolve_game tool logic. It calls the MainMenu API endpoint, validates the response against the v1 schema, and returns the ranked results.
  export async function resolveGame(input: ResolveGameInput): Promise<ResolveGameResult> { const { slug } = input; const url = `${MAINMENU_BASE}/api/v1/games/${encodeURIComponent(slug)}/json`; try { const res = await fetch(url, { headers: { "User-Agent": "rootvine-mcp/1.0.0", "Accept": "application/json", }, signal: AbortSignal.timeout(5000), }); if (!res.ok && res.status !== 404) { return { success: false, error: `MainMenu 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 MainMenu: ${message}`, }; } }
• src/tools/resolveGame.ts:16-24 (schema)

  Input and output interface definitions for the resolve_game tool. ResolveGameInput takes a slug parameter, and ResolveGameResult contains success status and either the validated response or an error message.
  export interface ResolveGameInput { slug: string; } export interface ResolveGameResult { success: boolean; response?: RootVineResponseV1; error?: string; }
• src/index.ts:87-120 (registration)

  MCP tool registration for resolve_game. Registers the tool with its description, input schema (slug parameter using Zod validation), and handler that calls resolveGame and formats the response for the agent.
  server.registerTool( "resolve_game", { description: "Find where to buy a video game at the best price. Returns ranked results from trusted game stores (Steam, PlayStation, Xbox, Nintendo, Epic, etc.) with prices, editions, and DLC info. Use this when a user asks about video games.", inputSchema: { slug: z .string() .describe("The game slug. Format: game-title (lowercase, hyphenated). Example: 'elden-ring'"), }, }, async ({ slug }) => { const result = await resolveGame({ slug }); if (!result.success || !result.response) { return { content: [ { type: "text" as const, text: `Could not resolve game: ${result.error || "Unknown error"}`, }, ], }; } return { content: [ { type: "text" as const, text: formatGameResponse(result.response), }, ], }; }, );
• src/tools/resolveGame.ts:76-132 (helper)

  Helper function that formats the RootVine API response into a human-readable text format for display to the agent/user. Handles success, error, and no_results statuses, and formats ranked merchant results with prices and links.
  export function formatGameResponse(response: RootVineResponseV1): string { const lines: string[] = []; // Header lines.push(`🎮 ${response.query.title || response.query.raw}`); lines.push(""); 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 game."); 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)}` : "Price unknown"; const link = result.click_url || result.url; const edition = result.edition ? ` (${result.edition})` : ""; lines.push( `${result.rank}. **${result.merchant}**${edition} (${result.trust_tier})`, ` 🛒 ${priceStr} — ${result.availability.replace("_", " ")}`, ` ${link}`, "", ); } // DLC count if ("dlc_count" in response && response.dlc_count) { lines.push(`📦 ${response.dlc_count} DLC/expansions available`); } // 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"); }
• src/validate.ts:78-80 (schema)

  Zod validation function that validates responses from Vine endpoints against the v1 schema. Used by resolveGame to ensure data integrity before returning results to the agent.
  export function validateResponse(data: unknown) { return RootVineResponseV1Schema.safeParse(data); }