feat: add LoL Stats plugin — op.gg-powered player lookup

New plugin for League of Legends stats tracking, similar to op.gg:
- Search summoners by Riot ID (Name#Tag) + region
- Profile overview: rank, tier, LP, win rate, ladder position
- Top champions with KDA and win rates
- Match history with KDA, CS, items, game duration
- Expandable match details showing all 10 players
- Recent searches persisted across restarts

Uses op.gg MCP server (no API key needed, no 24h expiration).
Backend: server/src/plugins/lolstats/ (3 files)
Frontend: web/src/plugins/lolstats/ (2 files)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/src/index.ts

@@ -7,6 +7,7 @@ import { loadState, getFullState, getStateDiag } from './core/persistence.js';
 import { getPlugins, registerPlugin, getPluginCtx, type PluginContext } from './core/plugin.js';
 import radioPlugin from './plugins/radio/index.js';
 import soundboardPlugin from './plugins/soundboard/index.js';
+import lolstatsPlugin from './plugins/lolstats/index.js';
 
 // ── Config ──
 const PORT = Number(process.env.PORT ?? 8080);
@@ -122,6 +123,11 @@ async function boot(): Promise<void> {
   registerPlugin(soundboardPlugin, ctxJukebox);
   registerPlugin(radioPlugin, ctxRadio);
 
+  // lolstats has no Discord bot — use a dummy client (never logged in)
+  const clientLolstats = createClient();
+  const ctxLolstats: PluginContext = { client: clientLolstats, dataDir: DATA_DIR, adminPwd: ADMIN_PWD, allowedGuildIds: ALLOWED_GUILD_IDS };
+  registerPlugin(lolstatsPlugin, ctxLolstats);
+
   // Init all plugins
   for (const p of getPlugins()) {
     const pCtx = getPluginCtx(p.name)!;

server/src/plugins/lolstats/index.ts

@@ -0,0 +1,134 @@
+import type express from 'express';
+import type { Plugin, PluginContext } from '../../core/plugin.js';
+import { sseBroadcast } from '../../core/sse.js';
+import { getState, setState } from '../../core/persistence.js';
+import { getProfile, getMatches, getMatchDetail, REGIONS } from './opgg-api.js';
+import type { RecentSearch } from './types.js';
+
+// ── Recent searches ──
+
+function getRecent(): RecentSearch[] {
+  return getState<RecentSearch[]>('lolstats_recent', []);
+}
+
+function addRecent(entry: Omit<RecentSearch, 'timestamp'>): void {
+  let list = getRecent();
+  // Remove duplicate
+  list = list.filter(
+    r => !(r.game_name.toLowerCase() === entry.game_name.toLowerCase()
+        && r.tag_line.toLowerCase() === entry.tag_line.toLowerCase()
+        && r.region === entry.region),
+  );
+  // Add to front, cap at 10
+  list.unshift({ ...entry, timestamp: Date.now() });
+  if (list.length > 10) list.length = 10;
+  setState('lolstats_recent', list);
+  sseBroadcast({ type: 'lolstats_recent', plugin: 'lolstats', recentSearches: list });
+}
+
+// ── Plugin ──
+
+const lolstatsPlugin: Plugin = {
+  name: 'lolstats',
+  version: '1.0.0',
+  description: 'League of Legends Stats',
+
+  async init(_ctx) {
+    console.log('[LoLStats] Initialized — using op.gg MCP (no API key needed)');
+  },
+
+  registerRoutes(app: express.Application, _ctx: PluginContext) {
+    // ── Regions ──
+    app.get('/api/lolstats/regions', (_req, res) => {
+      res.json(REGIONS);
+    });
+
+    // ── Summoner Profile Lookup ──
+    app.get('/api/lolstats/profile', async (req, res) => {
+      const { gameName, tagLine, region } = req.query as Record<string, string>;
+      if (!gameName || !tagLine || !region) {
+        return res.status(400).json({ error: 'gameName, tagLine, region required' });
+      }
+      try {
+        const profile = await getProfile(gameName, tagLine, region);
+
+        // Save to recent searches
+        const soloRank = profile.league_stats?.find(l => l.game_type === 'SOLORANKED');
+        addRecent({
+          game_name: profile.game_name,
+          tag_line: profile.tagline,
+          region,
+          profile_image_url: profile.profile_image_url,
+          level: profile.level,
+          tier: soloRank?.tier_info?.tier ?? undefined,
+          rank: soloRank?.tier_info?.division != null
+            ? String(soloRank.tier_info.division)
+            : undefined,
+        });
+
+        res.json(profile);
+      } catch (e: any) {
+        console.error('[LoLStats] Profile error:', e.message);
+        const status = e.message.includes('not found') ? 404 : 502;
+        res.status(status).json({ error: e.message });
+      }
+    });
+
+    // ── Match History ──
+    app.get('/api/lolstats/matches', async (req, res) => {
+      const { gameName, tagLine, region, limit } = req.query as Record<string, string>;
+      if (!gameName || !tagLine || !region) {
+        return res.status(400).json({ error: 'gameName, tagLine, region required' });
+      }
+      try {
+        const matches = await getMatches(gameName, tagLine, region, Number(limit) || 10);
+        res.json(matches);
+      } catch (e: any) {
+        console.error('[LoLStats] Matches error:', e.message);
+        res.status(502).json({ error: e.message });
+      }
+    });
+
+    // ── Match Detail ──
+    app.get('/api/lolstats/match/:gameId', async (req, res) => {
+      const { region, createdAt } = req.query as Record<string, string>;
+      const { gameId } = req.params;
+      if (!gameId || !region || !createdAt) {
+        return res.status(400).json({ error: 'gameId, region, createdAt required' });
+      }
+      try {
+        const match = await getMatchDetail(gameId, createdAt, region);
+        res.json(match);
+      } catch (e: any) {
+        console.error('[LoLStats] Match detail error:', e.message);
+        res.status(502).json({ error: e.message });
+      }
+    });
+
+    // ── Recent Searches ──
+    app.get('/api/lolstats/recent', (_req, res) => {
+      res.json(getRecent());
+    });
+
+    app.delete('/api/lolstats/recent', (_req, res) => {
+      setState('lolstats_recent', []);
+      sseBroadcast({ type: 'lolstats_recent', plugin: 'lolstats', recentSearches: [] });
+      res.json({ ok: true });
+    });
+  },
+
+  getSnapshot(_ctx) {
+    return {
+      lolstats: {
+        recentSearches: getRecent(),
+        regions: REGIONS,
+      },
+    };
+  },
+
+  async destroy() {
+    console.log('[LoLStats] Destroyed');
+  },
+};
+
+export default lolstatsPlugin;

server/src/plugins/lolstats/opgg-api.ts

@@ -0,0 +1,336 @@
+/**
+ * op.gg MCP Client — calls the public op.gg MCP server at https://mcp-api.op.gg/mcp
+ * Uses JSON-RPC 2.0 over StreamableHTTP (MCP protocol).
+ * No API key needed.
+ */
+
+import type {
+  RegionInfo, SummonerProfile, MatchEntry, MatchParticipant,
+  MatchParticipantStats, TeamStat,
+} from './types.js';
+
+const MCP_URL = 'https://mcp-api.op.gg/mcp';
+let rpcId = 1;
+
+// ── Regions ──
+
+export const REGIONS: RegionInfo[] = [
+  { code: 'EUW', label: 'EU West' },
+  { code: 'EUNE', label: 'EU Nordic & East' },
+  { code: 'NA', label: 'North America' },
+  { code: 'KR', label: 'Korea' },
+  { code: 'BR', label: 'Brazil' },
+  { code: 'LAN', label: 'Latin America North' },
+  { code: 'LAS', label: 'Latin America South' },
+  { code: 'TR', label: 'Turkey' },
+  { code: 'RU', label: 'Russia' },
+  { code: 'JP', label: 'Japan' },
+  { code: 'OCE', label: 'Oceania' },
+  { code: 'PH', label: 'Philippines' },
+  { code: 'SG', label: 'Singapore' },
+  { code: 'TH', label: 'Thailand' },
+  { code: 'TW', label: 'Taiwan' },
+  { code: 'VN', label: 'Vietnam' },
+];
+
+// ── MCP call helper ──
+
+async function mcpCall(toolName: string, args: Record<string, any>): Promise<any> {
+  const id = rpcId++;
+  const body = {
+    jsonrpc: '2.0',
+    id,
+    method: 'tools/call',
+    params: { name: toolName, arguments: args },
+  };
+
+  const res = await fetch(MCP_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json, text/event-stream',
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    throw new Error(`MCP HTTP ${res.status}: ${res.statusText}`);
+  }
+
+  const json = await res.json() as any;
+
+  if (json.error) {
+    const msg = json.error.message ?? JSON.stringify(json.error);
+    throw new Error(msg);
+  }
+
+  // MCP tools return content as an array of content blocks
+  const text = json.result?.content?.[0]?.text;
+  if (!text) throw new Error('Empty MCP response');
+
+  return text;
+}
+
+// ── Response parser ──
+// op.gg MCP returns a custom class-notation format, not pure JSON.
+// We need to parse the structured text into usable data.
+
+function parseClassNotation(text: string): any {
+  // The response format is like:
+  // class ClassName: field1,field2
+  // ClassName(Data(...))
+  //
+  // We need to extract the actual data. The data part after the class
+  // definitions is a nested constructor-call format.
+  // Strategy: find the last line that starts with the root class name
+  // and parse the nested parentheses structure.
+
+  const lines = text.split('\n');
+
+  // Find class definitions and the data line
+  const classDefs: Map<string, string[]> = new Map();
+  let dataLine = '';
+
+  for (const line of lines) {
+    const classMatch = line.match(/^class (\w+): (.+)$/);
+    if (classMatch) {
+      classDefs.set(classMatch[1], classMatch[2].split(','));
+      continue;
+    }
+    if (line.trim()) {
+      dataLine = line.trim();
+    }
+  }
+
+  if (!dataLine) throw new Error('No data in MCP response');
+
+  // Parse the constructor-call notation recursively
+  return parseConstructor(dataLine, classDefs);
+}
+
+function parseConstructor(input: string, classDefs: Map<string, string[]>): any {
+  // Try to match ClassName(...)
+  const ctorMatch = input.match(/^(\w+)\((.+)\)$/s);
+  if (!ctorMatch) {
+    // It's a primitive value
+    return parsePrimitive(input);
+  }
+
+  const className = ctorMatch[1];
+  const innerContent = ctorMatch[2];
+  const fields = classDefs.get(className);
+
+  if (!fields) {
+    // Unknown class, try to parse inner as a value
+    return parseConstructor(innerContent, classDefs);
+  }
+
+  // Split the inner content by top-level commas (respecting nested parens/brackets/strings)
+  const values = splitTopLevel(innerContent);
+
+  const obj: Record<string, any> = {};
+  for (let i = 0; i < fields.length && i < values.length; i++) {
+    const fieldName = fields[i].trim();
+    const rawVal = values[i].trim();
+
+    if (fieldName.endsWith('[]')) {
+      // Array field — clean field name
+      const cleanName = fieldName.replace('[]', '');
+      obj[cleanName] = parseArrayValue(rawVal, classDefs);
+    } else {
+      obj[fieldName] = parseValue(rawVal, classDefs);
+    }
+  }
+
+  return obj;
+}
+
+function parseArrayValue(input: string, classDefs: Map<string, string[]>): any[] {
+  // Array notation: [item1,item2,...] or [ClassName(...),ClassName(...)]
+  if (input === '[]' || input === 'null' || input === 'None') return [];
+
+  if (input.startsWith('[') && input.endsWith(']')) {
+    const inner = input.slice(1, -1).trim();
+    if (!inner) return [];
+    const items = splitTopLevel(inner);
+    return items.map(item => parseValue(item.trim(), classDefs));
+  }
+
+  // Single item not wrapped in brackets
+  return [parseValue(input, classDefs)];
+}
+
+function parseValue(input: string, classDefs: Map<string, string[]>): any {
+  if (!input) return null;
+
+  // Check if it's a constructor call
+  const ctorMatch = input.match(/^(\w+)\(/);
+  if (ctorMatch && classDefs.has(ctorMatch[1])) {
+    return parseConstructor(input, classDefs);
+  }
+
+  // Check if it's an array
+  if (input.startsWith('[') && input.endsWith(']')) {
+    return parseArrayValue(input, classDefs);
+  }
+
+  return parsePrimitive(input);
+}
+
+function parsePrimitive(input: string): any {
+  if (input === 'null' || input === 'None') return null;
+  if (input === 'true' || input === 'True') return true;
+  if (input === 'false' || input === 'False') return false;
+
+  // Quoted string
+  if ((input.startsWith('"') && input.endsWith('"')) ||
+      (input.startsWith("'") && input.endsWith("'"))) {
+    return input.slice(1, -1);
+  }
+
+  // Number
+  const num = Number(input);
+  if (!isNaN(num) && input !== '') return num;
+
+  // Raw string
+  return input;
+}
+
+function splitTopLevel(input: string): string[] {
+  const results: string[] = [];
+  let depth = 0;
+  let inString = false;
+  let stringChar = '';
+  let current = '';
+
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    const prev = i > 0 ? input[i - 1] : '';
+
+    if (inString) {
+      current += ch;
+      if (ch === stringChar && prev !== '\\') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringChar = ch;
+      current += ch;
+      continue;
+    }
+
+    if (ch === '(' || ch === '[') {
+      depth++;
+      current += ch;
+      continue;
+    }
+
+    if (ch === ')' || ch === ']') {
+      depth--;
+      current += ch;
+      continue;
+    }
+
+    if (ch === ',' && depth === 0) {
+      results.push(current);
+      current = '';
+      continue;
+    }
+
+    current += ch;
+  }
+
+  if (current.trim()) results.push(current);
+  return results;
+}
+
+// ── Public API functions ──
+
+export async function getProfile(
+  gameName: string, tagLine: string, region: string,
+): Promise<SummonerProfile> {
+  const raw = await mcpCall('lol_get_summoner_profile', {
+    game_name: gameName,
+    tag_line: tagLine,
+    region,
+    lang: 'en_US',
+    desired_output_fields: [
+      'data.summoner.game_name',
+      'data.summoner.tagline',
+      'data.summoner.level',
+      'data.summoner.profile_image_url',
+      'data.summoner.updated_at',
+      'data.summoner.league_stats[].tier_info.{tier,division,lp,tier_image_url}',
+      'data.summoner.league_stats[].{game_type,win,lose,is_hot_streak}',
+      'data.summoner.ladder_rank.{rank,total}',
+      'data.summoner.most_champions.champion_stats[].{champion_name,id,play,win,lose,kill,death,assist}',
+      'data.summoner.most_champions.{game_type,play,win,lose}',
+    ],
+  });
+
+  const parsed = parseClassNotation(raw);
+  // Navigate to summoner data (may be nested in data.summoner or similar)
+  const summoner = parsed?.summoner ?? parsed?.data?.summoner ?? parsed;
+
+  return {
+    game_name: summoner.game_name ?? gameName,
+    tagline: summoner.tagline ?? tagLine,
+    level: summoner.level ?? 0,
+    profile_image_url: summoner.profile_image_url ?? '',
+    league_stats: Array.isArray(summoner.league_stats) ? summoner.league_stats : [],
+    ladder_rank: summoner.ladder_rank ?? { rank: null, total: null },
+    most_champions: summoner.most_champions ?? { game_type: '', play: 0, win: 0, lose: 0, champion_stats: [] },
+    updated_at: summoner.updated_at ?? '',
+  };
+}
+
+export async function getMatches(
+  gameName: string, tagLine: string, region: string, limit = 10,
+): Promise<MatchEntry[]> {
+  const raw = await mcpCall('lol_list_summoner_matches', {
+    game_name: gameName,
+    tag_line: tagLine,
+    region,
+    lang: 'en_US',
+    limit,
+    desired_output_fields: [
+      'data.game_history[].{id,created_at,game_length_second,game_type,game_map}',
+      'data.game_history[].average_tier_info.{tier,division}',
+      'data.game_history[].participants[].{champion_name,champion_id,items[],items_names[],position,team_key,spells[]}',
+      'data.game_history[].participants[].stats.{kill,death,assist,minion_kill,neutral_minion_kill,gold_earned,total_damage_dealt_to_champions,total_damage_taken,ward_place,vision_wards_bought_in_game,champion_level,op_score,op_score_rank,result}',
+      'data.game_history[].participants[].summoner.{game_name,tagline}',
+      'data.game_history[].teams[].{key,banned_champions_names[]}',
+      'data.game_history[].teams[].game_stat.{is_win,baron_kill,dragon_kill,tower_kill,champion_kill,gold_earned,inhibitor_kill,rift_herald_kill}',
+    ],
+  });
+
+  const parsed = parseClassNotation(raw);
+  const history = parsed?.game_history ?? parsed?.data?.game_history ?? [];
+  return Array.isArray(history) ? history : [];
+}
+
+export async function getMatchDetail(
+  gameId: string, createdAt: string, region: string,
+): Promise<MatchEntry | null> {
+  const raw = await mcpCall('lol_get_summoner_game_detail', {
+    game_id: gameId,
+    created_at: createdAt,
+    region,
+    lang: 'en_US',
+    desired_output_fields: [
+      'data.game_detail.{id,created_at,game_length_second,game_type,game_map}',
+      'data.game_detail.average_tier_info.{tier,division}',
+      'data.game_detail.participants[].{champion_name,champion_id,items[],items_names[],position,team_key,spells[]}',
+      'data.game_detail.participants[].stats.{kill,death,assist,minion_kill,neutral_minion_kill,gold_earned,total_damage_dealt_to_champions,total_damage_taken,ward_place,vision_wards_bought_in_game,champion_level,op_score,op_score_rank,result}',
+      'data.game_detail.participants[].summoner.{game_name,tagline}',
+      'data.game_detail.teams[].{key,banned_champions_names[]}',
+      'data.game_detail.teams[].game_stat.{is_win,baron_kill,dragon_kill,tower_kill,champion_kill,gold_earned,inhibitor_kill,rift_herald_kill}',
+    ],
+  });
+
+  const parsed = parseClassNotation(raw);
+  return parsed?.game_detail ?? parsed?.data?.game_detail ?? null;
+}

server/src/plugins/lolstats/types.ts

@@ -0,0 +1,146 @@
+// ── op.gg MCP response types ──
+
+export interface RegionInfo {
+  code: string;   // "EUW", "NA", "KR", etc.
+  label: string;  // "EU West", "North America", etc.
+}
+
+// ── Summoner Profile ──
+
+export interface TierInfo {
+  tier: string | null;       // "GOLD", "GRANDMASTER", etc.
+  division: number | null;   // 1,2,3,4
+  lp: number | null;
+  tier_image_url?: string;
+}
+
+export interface LeagueStat {
+  game_type: string;        // "SOLORANKED", "FLEXRANKED", "ARENA"
+  win: number | null;
+  lose: number | null;
+  is_hot_streak: boolean;
+  tier_info: TierInfo;
+}
+
+export interface LadderRank {
+  rank: number | null;
+  total: number | null;
+}
+
+export interface ChampionStat {
+  champion_name: string;
+  id: number;
+  play: number;
+  win: number;
+  lose: number;
+  kill: number;
+  death: number;
+  assist: number;
+}
+
+export interface MostChampions {
+  game_type: string;
+  play: number;
+  win: number;
+  lose: number;
+  champion_stats: ChampionStat[];
+}
+
+export interface SummonerProfile {
+  game_name: string;
+  tagline: string;
+  level: number;
+  profile_image_url: string;
+  league_stats: LeagueStat[];
+  ladder_rank: LadderRank;
+  most_champions: MostChampions;
+  updated_at: string;
+}
+
+// ── Match History ──
+
+export interface MatchParticipantStats {
+  kill: number;
+  death: number;
+  assist: number;
+  minion_kill: number;
+  neutral_minion_kill: number;
+  gold_earned: number;
+  total_damage_dealt_to_champions: number;
+  total_damage_taken: number;
+  ward_place: number;
+  vision_wards_bought_in_game: number;
+  champion_level: number;
+  op_score: number;
+  op_score_rank: number;
+  result: string;  // "WIN" | "LOSE"
+}
+
+export interface MatchParticipant {
+  champion_name: string;
+  champion_id: number;
+  items: number[];
+  items_names: string[];
+  position: string;       // "TOP", "JUNGLE", "MID", "ADC", "SUPPORT"
+  team_key: string;       // "BLUE" | "RED"
+  spells: number[];
+  stats: MatchParticipantStats;
+  summoner: {
+    game_name: string;
+    tagline: string;
+    puuid?: string;
+  };
+}
+
+export interface TeamStat {
+  key: string;  // "BLUE" | "RED"
+  banned_champions_names: string[];
+  game_stat: {
+    is_win: boolean;
+    baron_kill: number;
+    dragon_kill: number;
+    tower_kill: number;
+    champion_kill: number;
+    gold_earned: number;
+    inhibitor_kill: number;
+    rift_herald_kill: number;
+  };
+}
+
+export interface MatchEntry {
+  id: string;
+  created_at: string;
+  game_length_second: number;
+  game_type: string;      // "SOLORANKED", "FLEXRANKED", "NORMAL", "ARAM"
+  game_map: string;
+  average_tier_info?: { tier: string; division: number };
+  participants: MatchParticipant[];
+  teams: TeamStat[];
+}
+
+// ── Composite types for API responses ──
+
+export interface ProfileResponse {
+  summoner: SummonerProfile;
+}
+
+export interface MatchHistoryResponse {
+  matches: MatchEntry[];
+}
+
+export interface MatchDetailResponse {
+  match: MatchEntry;
+}
+
+// ── Recent search persistence ──
+
+export interface RecentSearch {
+  game_name: string;
+  tag_line: string;
+  region: string;
+  profile_image_url: string;
+  level: number;
+  tier?: string;
+  rank?: string;
+  timestamp: number;
+}