Lutris MCP Server

Instructions

Implementation Reference

• src/db/queries.ts:235-284 (handler)

  The actual business logic that queries the database to calculate library statistics.

  export function getLibraryStats(): LibraryStats {
    const db = getDatabase();
  
    const totals = db
      .prepare(
        "SELECT COUNT(*) as total, SUM(CASE WHEN installed = 1 THEN 1 ELSE 0 END) as installed, COALESCE(SUM(playtime), 0) as playtime FROM games"
      )
      .get() as { total: number; installed: number; playtime: number };
  
    const topByPlaytime = db
      .prepare(
        "SELECT name, playtime FROM games WHERE playtime > 0 ORDER BY playtime DESC LIMIT 10"
      )
      .all() as { name: string; playtime: number }[];
  
    const byRunner = db
      .prepare(
        "SELECT COALESCE(runner, 'unknown') as runner, COUNT(*) as count FROM games GROUP BY runner ORDER BY count DESC"
      )
      .all() as { runner: string; count: number }[];
  
    const byPlatform = db
      .prepare(
        "SELECT COALESCE(platform, 'unknown') as platform, COUNT(*) as count FROM games GROUP BY platform ORDER BY count DESC"
      )
      .all() as { platform: string; count: number }[];
  
    const byService = db
      .prepare(
        "SELECT COALESCE(service, 'none') as service, COUNT(*) as count FROM games GROUP BY service ORDER BY count DESC"
      )
      .all() as { service: string; count: number }[];
  
    const recentlyPlayed = db
      .prepare(
        "SELECT name, lastplayed FROM games WHERE lastplayed IS NOT NULL AND lastplayed > 0 ORDER BY lastplayed DESC LIMIT 10"
      )
      .all() as { name: string; lastplayed: number }[];
  
    return {
      total_games: totals.total,
      installed_games: totals.installed,
      total_playtime_hours: Math.round((totals.playtime / 60) * 100) / 100,
      top_games_by_playtime: topByPlaytime,
      games_by_runner: byRunner,
      games_by_platform: byPlatform,
      games_by_service: byService,
      recently_played: recentlyPlayed,
    };
  }

• src/tools/stats.ts:5-20 (handler)

  MCP tool definition and handler that calls the database query.

  server.tool(
    "get_library_stats",
    "Get aggregate statistics about the Lutris game library",
    {},
    async () => {
      try {
        const stats = getLibraryStats();
        return {
          content: [{ type: "text", text: JSON.stringify(stats, null, 2) }],
        };
      } catch (error) {
        const msg = error instanceof Error ? error.message : String(error);
        return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
      }
    }
  );

• src/tools/stats.ts:4-21 (registration)

  Function to register the stats tools with the MCP server.

  export function registerStatsTools(server: McpServer) {
    server.tool(
      "get_library_stats",
      "Get aggregate statistics about the Lutris game library",
      {},
      async () => {
        try {
          const stats = getLibraryStats();
          return {
            content: [{ type: "text", text: JSON.stringify(stats, null, 2) }],
          };
        } catch (error) {
          const msg = error instanceof Error ? error.message : String(error);
          return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
        }
      }
    );
  }

• src/db/queries.ts:224-233 (schema)

  Type definition for the library statistics object.

  export interface LibraryStats {
    total_games: number;
    installed_games: number;
    total_playtime_hours: number;
    top_games_by_playtime: { name: string; playtime: number }[];
    games_by_runner: { runner: string; count: number }[];
    games_by_platform: { platform: string; count: number }[];
    games_by_service: { service: string; count: number }[];
    recently_played: { name: string; lastplayed: number }[];
  }