search_steam_games

Instructions

Implementation Reference

• src/index.ts:478-503 (handler)

  Primary handler for search_steam_games tool in stdio mode. Validates input using Zod schema, performs single or batch search via steamClient.searchGames(), and returns results as JSON.

  if (name === 'search_steam_games') {
    // Validate input using Zod schema
    const validatedInput = searchGamesSchema.parse(args);
  
    let results: SteamGame[];
  
    if (validatedInput.queries) {
      // Batch search - execute all queries in parallel
      const allResults = await Promise.all(
        validatedInput.queries.map((q) => steamClient.searchGames(q, validatedInput.limit))
      );
      // Flatten results from all queries
      results = allResults.flat();
    } else {
      // Single search
      results = await steamClient.searchGames(validatedInput.query!, validatedInput.limit);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(results, null, 2),
        },
      ],
    };

• src/index.ts:842-857 (handler)

  Duplicate handler for search_steam_games tool in SSE (HTTP) mode. Same logic as stdio handler.

  if (name === 'search_steam_games') {
    const validatedInput = searchGamesSchema.parse(args);
    let results: SteamGame[];
  
    if (validatedInput.queries) {
      const allResults = await Promise.all(
        validatedInput.queries.map((q) => steamClient.searchGames(q, validatedInput.limit))
      );
      results = allResults.flat();
    } else {
      results = await steamClient.searchGames(validatedInput.query!, validatedInput.limit);
    }
  
    return {
      content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
    };

• src/index.ts:253-261 (schema)

  Zod schema for validating search_steam_games input. Supports optional 'query' (string), 'queries' (array of 1-5 strings), and 'limit' (1-25). Refines that either query or queries must be provided.

  const searchGamesSchema = z
    .object({
      query: z.string().optional(),
      queries: z.array(z.string()).min(1).max(5).optional(),
      limit: z.number().min(1).max(25).optional(),
    })
    .refine((data) => data.query || data.queries, {
      message: 'Either query or queries must be provided',
    });

• src/index.ts:32-58 (registration)

  Tool registration/definition for search_steam_games. Declares name, description, and JSON schema input (query, queries, limit).

  {
    name: 'search_steam_games',
    description:
      'Search for Steam games by name or keywords. Supports single or batch queries. Returns basic game information including AppID, name, price, and preview image.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Single search query (game name or keywords)',
        },
        queries: {
          type: 'array',
          items: { type: 'string' },
          description: 'Multiple search queries for batch searching',
          minItems: 1,
          maxItems: 5,
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results PER QUERY (default: 10, max: 25)',
          minimum: 1,
          maximum: 25,
        },
      },
      // Note: Either query OR queries must be provided (validated in Zod)
    },

• src/utils/steam-api.ts:227-297 (helper)

  Core helper implementing the actual Steam store search. Scrapes store.steampowered.com/search HTML using cheerio, extracts appId, name, price, image, and release date. Results are cached for 2 hours.

  async searchGames(query: string, limit: number = 10): Promise<SteamGame[]> {
    const cacheKey = `search_${query}_${limit}`;
  
    // Check cache first
    if (this.config.cacheEnabled) {
      const cached = this.cache.get(cacheKey) as SteamGame[] | undefined;
      if (cached !== undefined) {
        return cached;
      }
    }
  
    // Build search URL
    const searchUrl = `https://store.steampowered.com/search/?term=${encodeURIComponent(query)}`;
  
    // Fetch HTML content using the get method for rate limiting and retry
    const html = await this.get<string>(searchUrl);
  
    // Parse HTML with cheerio
    const $ = cheerio.load(html);
    const results: SteamGame[] = [];
  
    // Select search result rows
    $('.search_result_row').each((index, element) => {
      if (results.length >= limit) {
        return false; // Stop iteration when limit reached
      }
  
      const $row = $(element);
  
      // Extract AppID from data attribute
      const appIdStr = $row.attr('data-ds-appid');
      if (!appIdStr) {
        return; // Skip if no AppID
      }
      const appId = parseInt(appIdStr, 10);
      if (isNaN(appId)) {
        return; // Skip if AppID is not a valid number
      }
  
      // Extract game name
      const name = $row.find('.title').text().trim();
  
      // Extract price
      const priceText = $row.find('.search_price').text().trim();
      const priceFormatted = this.parsePriceText(priceText);
  
      // Extract image URL
      const headerImage = $row.find('.search_capsule img').attr('src') || undefined;
  
      // Extract release date (if available)
      const releaseDate = $row.find('.search_released').text().trim() || undefined;
  
      // Build SteamGame object
      const game: SteamGame = {
        appId,
        name,
        headerImage,
        releaseDate,
        priceFormatted,
      };
  
      results.push(game);
    });
  
    // Cache the results
    if (this.config.cacheEnabled) {
      this.cache.set(cacheKey, results, this.config.cacheTTL.gameInfo);
    }
  
    return results;
  }