resolve_game

Instructions

Implementation Reference

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

  The main resolver function for the resolve_game tool. Fetches game pricing data from MainMenu's /api/v1/games/:slug/json endpoint, validates the response against the v1 schema, and returns ranked results with prices, editions, and DLC info.

  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.2",
                  "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-18 (schema)

  Input schema for the resolve_game tool: expects a slug string identifying the game.

  export interface ResolveGameInput {
      slug: string;
  }

• src/tools/resolveGame.ts:20-24 (schema)

  Output schema for the resolve_game tool: returns success status, optional response data (RootVineResponseV1), and optional error message.

  export interface ResolveGameResult {
      success: boolean;
      response?: RootVineResponseV1;
      error?: string;
  }

• src/index.ts:88-121 (registration)

  Registration of the resolve_game tool with the MCP server. Registers it with name 'resolve_game', slug input schema, and a handler that calls resolveGame() and formats the response using formatGameResponse().

  server.registerTool(
      "resolve_game",
      {
          description: "Find where to buy a video game at the best price across trusted stores (Steam, PlayStation, Xbox, Nintendo, Epic, GOG, Humble, Fanatical). Returns ranked results with prices, editions, and DLC info. Note: the games vertical is launching soon — this tool currently returns a 'coming soon' message. Prefer `resolve_music` or `find_product` for music queries.",
          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)

  Formats a game response (RootVineResponseV1) into a human-readable string for agent display. Handles error, no_results, and success states with ranked merchant results, prices, edition info, DLC count, and warnings.

  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");
  }