io.github.Ninjabeam20/sportiq-mcp

Recommend an optimal fantasy XI + captain + vice-captain for one fixture. Args: match_id: CricAPI match identifier; resolves team_a/team_b/venue automatically. team_a: First team code/name (e.g. ``MI``). Required if match_id is absent. team_b: Second team code/name (e.g. ``CSK``). Required if match_id is absent. venue: Venue key/name (e.g. ``wankhede``). Required if match_id is absent. strategy: ``"balanced"`` only in Phase 2; future variants reserved. Returns: data.players: 11 picked players with name/role/credits/team/projected_points. data.captain: name of the chosen captain. data.vice_captain: name of the chosen VC. data.total_credits: sum of credits used (<= 100). data.total_projected_points: fantasy points including C x2 and VC x1.5 boosts. meta.estimated: true — projections are model output, not a fantasy oracle. meta.form_source: "default_neutral" (role-based projections; see meta.note). meta.scoring_profile: the Dream11 T20 points profile id. meta.excluded_missing_credits: players dropped for having no contest credits. Example: cricket_build_dream11_team(team_a="MI", team_b="CSK", venue="wankhede") cricket_build_dream11_team(match_id="abc123")

Return the top-3 captain candidates ranked by projected points. IPL venues only (pitch seed is IPL grounds). Test/international matches and unknown venues fail rather than inventing a ranking. Same-role players often tie: projections use default form 55 and default opposition 0.5, not per-player history. Args: match_id: CricAPI match identifier; resolves team_a/team_b/venue automatically. team_a: First team code/name. Required if match_id is absent. team_b: Second team code/name. Required if match_id is absent. venue: Venue key/name (IPL ground, e.g. ``wankhede``). Required if match_id is absent. Returns: data.candidates: list of 3 dicts with name/role/team/projected_points. meta.source: model:captain_score. meta.estimated: true. meta.form_source: "default_neutral".

Suggest low-ownership picks with positive projected upside. Ownership is *estimated* — proxied by credit weight (lower-credit players tend to have lower ownership), not real ownership data. Flagged ``estimated: true`` in the response. Args: match_id: CricAPI match identifier; resolves team_a/team_b/venue automatically. team_a: First team code/name. Required if match_id is absent. team_b: Second team code/name. Required if match_id is absent. venue: Venue key/name. Required if match_id is absent. ownership_threshold: percent ownership cap; affects estimated label. Returns: data.picks: list of {name, role, team, credits, projected_points, estimated_ownership_pct, ownership_pct_estimated}. meta.source: model:captain_score (filtered). meta.estimated: true. meta.ownership_source: "heuristic_from_credits". meta.form_source: "default_neutral".

Compare model probabilities against market-implied IPL odds. Requires THEODDS_KEY. NOTE: cricket has no calibrated team-strength model wired yet (unlike the football Elo/Poisson path), so this tool currently returns an EMPTY ``value_bets`` list — scoring an edge against a neutral 50/50 prior would flag every market underdog, which would be misleading. It still reports how many events were screened so callers know odds were available. For raw de-vigged prices use ``cricket_get_live_odds``. Real edge detection lands when a cricket win model is wired (see cricket_head_to_head); it will flag outcomes where the model beats the de-vigged market by ``min_edge`` **and** the offered price has positive expected value. Args: team: Optional team name to filter events (case-insensitive substring). Omit to scan every IPL odds event. min_edge: Minimum edge (model_prob - devigged_market_prob), 0..1. Default 0.05. Currently informational only (no bets emitted). Returns: data.value_bets: always ``[]`` until a cricket model is wired. data.events_analysed: count of not-yet-started events screened (both teams present). data.model: ``"neutral_baseline"``. data.note: why no bets are emitted. meta.estimated: true.

Return all currently live cricket matches across all series. Returns: data.matches: list of live match objects (team names, score, status). meta.source: which adapter served the response. meta.is_stale: true if data is from stale cache.

Return live market head-to-head odds for upcoming/live IPL matches. IPL only (~March-May). An empty ``events`` list outside that window is a successful empty market, not an outage. Not international/Test/other T20 leagues. For World Cup 2026 football odds use ``football_get_odds``. Sourced from The Odds API (requires THEODDS_KEY). Without a key the call returns a clean ALL_SOURCES_FAILED envelope rather than crashing. Args: team: Optional team name to filter events (case-insensitive substring, matched against both sides). Omit to return every IPL event. The Odds API uses its own opaque event ids, so a CricAPI match_id cannot be resolved to an event yet — filtering is by team name. Returns: data.events: list of {event_id, home, away, commence_time, bookmakers: [{name, home, away}]} with decimal h2h prices per bookmaker. Empty when no IPL events are listed (typical off-season). meta.source: adapter that served the data (theodds / cache:stale).

Summarise pitch characteristics for a venue. Args: venue: Venue key (e.g. ``wankhede``), official name, or city. Returns: data: {batting_friendly 0..1, expected_first_inn, recommendation, venue, pitch_type}. meta.source: which adapter served the venue record.

Return the points table / standings for a cricket series. Args: series_id: The series identifier (e.g. IPL 2026 series ID from CricAPI). Returns: data: points table rows with team, P, W, L, NRR, Points. meta.source: adapter that served the data.

Return the upcoming match schedule, optionally filtered by series. Args: series_id: Optional. Filter to a specific series. If omitted, returns all upcoming fixtures across all active series. limit: Max matches to return, 1..200 (default 50). offset: Number of matches to skip for paging (default 0). Returns: data.matches: page of matches dated today (UTC) or later, with teams, date, venue; filtered to ``series_id`` when the source labels series. data.pagination: {total, count, offset, limit, has_more, next_offset}. meta.source: adapter that served the data.

Return the full scorecard for a specific match. Args: match_id: The match identifier (e.g. from cricket_get_live_matches). Returns: data: full scorecard with innings, partnerships, bowling figures. meta.source: adapter that served the data.

Return the squad roster for a cricket team, optionally for a specific series. Args: team: Team code or name (e.g. "MI", "CSK", "IND", "AUS"). series_id: Optional. Series ID to pull the tournament-specific squad. If omitted, falls back to static seed data. Returns: data.players: list of players with name, role, and credits. meta.source: adapter that served the data (cricapi / static_seed).

Compare two cricket teams head-to-head using squad form and player stats. Args: team_a: First team code or name (e.g. "MI", "India"). team_b: Second team code or name (e.g. "CSK", "Australia"). Returns: data: {team_a, team_b, team_a_edge_count, team_b_edge_count, key_players_a, key_players_b, h2h_win_rate_a, h2h_win_rate_b, win_prob_a, win_prob_b}. meta.estimated: true. meta.estimate_quality: "uninformative" when no player stats were available (both sides at default form), else "player_stats".

Report a 0-100 form score for a player using the player_stats chain. Args: player_id: Upstream player identifier (CricAPI/Cricbuzz id). Returns: data.form_score: 0..100 indicator. data.trend: "rising" / "stable" / "falling". data.samples: how many recent innings were available. meta.source: which adapter served the underlying stats. meta.estimated: true.

Analyse the head-to-head matchup between two cricket players based on role and career stats. Args: player_a: CricAPI player ID for the first player (names are not resolved). player_b: CricAPI player ID for the second player (names are not resolved). Returns: data: {matchup_type, edge_holder, edge_reason, signals, role_a, role_b}. meta.estimated: true — heuristic model, not ball-by-ball H2H data.

Model the joint probability of multiple outcomes across football and cricket. Args: legs: Total legs across both sports (2-8). Default 3. min_edge: Minimum edge per leg. Default 0.05. Returns: data: same shape as football_build_accumulator, with sport field per leg. meta.estimated: true.

Return driver list for a specific F1 session. Args: session_key: OpenF1 session identifier. Returns: data.drivers: list of driver objects with driver_number, full_name, team. meta.source: adapter that served the data.

Return lap times for a driver in a specific F1 session. Args: session_key: OpenF1 session identifier. driver_number: Driver's race number (driver numbers change by season; use f1_get_drivers). limit: Max laps to return, 1..200 (default 100 — covers most full races). offset: Number of laps to skip for paging (default 0). Returns: data.laps: page of lap objects with lap_number and lap_duration. OpenF1 does not put compound/tyre_life here — those live on the stints endpoint. data.pagination: {total, count, offset, limit, has_more, next_offset}. meta.source: adapter that served the data.

Return the final classification for one F1 race, keyed by year and round. Args: year: Championship year (e.g. 2025). round: Round number within the season (1-based; e.g. 1 for the opener). Returns: data.results: Ergast/Jolpica RaceTable payload — finishing order, times, grid positions, points, and fastest laps for the race. meta.source: adapter that served the data.

Return F1 sessions for a given year, optionally filtered by country or session name. Args: year: Championship year (e.g. 2026). country: Optional country name to filter (e.g. "Netherlands"). session_name: Optional session name to keep, case-insensitive (e.g. "Race", "Qualifying", "Sprint"). latest_completed: When true, return only the single session that ended most recently (greatest date_end before now, UTC) — e.g. with session_name="Race", the latest finished Grand Prix. Returns: data.sessions: list of session objects with session_key, session_type, date. meta.source: adapter that served the data.

Return F1 driver and constructor championship standings for a year. Use this for "who is leading / who will win the F1 championship this year". For title probabilities use f1_simulate_championship. This is not a cricket or football tool. Args: year: Championship year (e.g. 2026). Returns: data.season / data.round: season and the last round counted. data.drivers: [{position, driver_number, code, name, team, points, wins}] (points are season totals). data.constructors: [{position, team, points, wins}]. Same shape from every source (Jolpica primary; the FastF1 fallback sums per-race points and omits sprint points). meta.source: adapter that served the data.

Return weather data for a specific F1 session. Args: session_key: OpenF1 session identifier. Returns: data.weather: list of weather snapshots with temperature, rainfall, wind. meta.source: adapter that served the data.

Compare lap-time pace distribution between two drivers in a session. Args: session_key: OpenF1 session identifier. driver_a: First driver's race number. driver_b: Second driver's race number. Returns: data: {driver_a_avg_s, driver_b_avg_s, delta_s, faster_driver}. The "avg" values are median lap times after dropping pit-out laps and slow outliers (safety-car / in-laps). meta.estimated: true.

Predict the optimal pit-stop strategy for a driver in an F1 race session. Args: session_key: OpenF1 session identifier for a recorded race. driver_number: Driver's race number (driver numbers change by season; use f1_get_drivers). current_lap: Current lap to project from (default 1 = full race ahead). total_laps: Total race laps. If omitted, estimated from the regulation minimum race distance (305 km; Monaco 260 km) over the circuit's lap length; INVALID_INPUT when the circuit is unknown. An explicit value always wins. Returns: data.stop_laps: recommended pit laps. data.compound_sequence: tyre compounds for each stint. data.expected_finish_position: currently always None (not modelled). data.confidence: 0.0-1.0 model confidence. data.net_saving_s: stay-out time minus the best one-stop time (seconds). data.current_tyre_age: laps on the current tyre set at current_lap. meta.total_laps: race length used. meta.total_laps_source: "explicit" or "regulation_estimate". meta.estimated: true. Example: f1_predict_pit_strategy(session_key=11353, driver_number=1, total_laps=72) f1_predict_pit_strategy(session_key=11353, driver_number=1, current_lap=20)

Analyse a qualifying session: best lap per driver, gap to pole, projected grid. Args: session_key: OpenF1 session identifier for a Qualifying session. Returns: data.grid: [{position, driver_number, full_name, team_name, best_lap_gap_s}]. data.pole_time_s: pole lap duration in seconds. data.drivers_analysed: count of drivers with valid laps. meta.estimated: true — grid derived from session laps, not official timing.

Compare race-pace and tyre degradation between two F1 drivers in a session. Args: session_key: OpenF1 session identifier. driver_a: First driver's race number. driver_b: Second driver's race number. Returns: data: {by_compound, overall_faster, compounds_compared}. meta.estimated: true — degradation model fit, not official timing.

Estimate each driver's F1 drivers' title probability for the rest of a season. Monte Carlo over the remaining races and sprints (Plackett-Luce finishing orders weighted by each driver's season points rate), plus exact elimination maths: a driver who cannot catch the leader's current points even by winning every remaining race and sprint has title_prob 0.0. This is not a cricket or football tool. Args: year: Championship season (2018-2030, default 2026). iterations: Monte Carlo iterations, clamped to 1000-20000 (default 10000). seed: Optional RNG seed for reproducible probabilities. Returns: data.drivers: [{code, points_now, title_prob, expected_points, eliminated, max_possible}] sorted by title_prob. data.max_remaining_points: most points one driver can still score. data.rounds_remaining: races left after the last completed round. meta.estimated: true. meta.model: "plackett-luce-points-rate". meta.is_stale: true if standings or schedule came from stale cache.

Fit a tyre degradation model for a driver + compound in a session. Args: session_key: OpenF1 session identifier. driver_number: Driver's race number. compound: Tyre compound (SOFT, MEDIUM, HARD, INTER, WET; "INTERMEDIATE" = INTER). Returns: data: {intercept, slope, residual_std, sample_count}. meta.estimated: true — model output, not telemetry oracle.

Estimate whether an undercut is viable for the attacker against the target. Args: session_key: OpenF1 session identifier. attacker_number: Attacking driver's race number. target_number: Target driver's race number. current_lap: Current lap number in the race. Returns: data: {laps_to_clear, viable, marginal}. meta.gap_to_target_s: attacker-minus-target race time at current_lap. meta.gap_source: "cumulative_lap_time", or "default" (assumed 2.0 s, also in meta.assumed_gap_s) when either driver lacks a full lap history. meta.estimated: true.

Analyse weather data and recommend compound or pit-window adjustments. Args: session_key: OpenF1 session identifier. Returns: data: {has_rain, avg_track_temp_c, compound_recommendation, recommendation}. meta.estimated: true.

Model the joint probability of several match outcomes from the top model-vs-market gaps. Calls ``football_find_value_bets`` internally to fetch live odds, then selects the strongest legs and combines them under the joint-probability model. Args: legs: Number of legs (2-8). Default 3. min_edge: Minimum edge threshold per leg. Default 0.05. Returns: data: {legs, legs_used, combined_odds, combined_model_prob, combined_edge, risk_flag, independence_warning}. meta.estimated: true.

Surface the largest gaps between the model's win probability and the market. De-vigs each market's 1X2 decimal odds (removes the margin so implied probabilities sum to 1) and compares them to this server's own match-outcome probabilities — the same Elo/Poisson path ``football_match_predictor`` uses. Flags outcomes where the model beats the de-vigged market by ``min_edge`` **and** the offered price has positive expected value, with the edge, the expected value and the model's fair odds. Events that have already started are skipped. Args: team: Optional FIFA code or team name to filter events (matched against both sides; an unrecognised value falls back to a case-insensitive substring match). Omit to scan every WC 2026 odds event. min_edge: Minimum edge (model_prob - devigged_market_prob), 0..1. Default 0.05 (5 percentage points). Returns: data.value_bets: list of {event_id, home, away, outcome, model_prob, fair_odds, market_odds, edge, ev_pct, bookmaker, price_updated_at}, sorted by edge descending. data.events_analysed: not-yet-started events with both teams in the draw. meta.estimated: true. meta.is_stale reflects the odds freshness.

Return rolling form, goal record, and xG trend for a football team. Args: team: FIFA code (e.g. ARG) or name (e.g. "Argentina", "South Korea"). Returns: data: {form_string, wins, draws, losses, goals_scored, goals_conceded, xg_for, xg_against, recent_trend, matches_analysed}. meta.estimated: true — derived from available fixture data.

Return World Cup 2026 fixtures (live providers, else the group schedule). Args: limit: Max fixtures to return, 1..200 (default 50). offset: Number of fixtures to skip for paging (default 0). Returns: data.fixtures: page of {home, away, date/group, status, home_goals, away_goals}. data.pagination: {total, count, offset, limit, has_more, next_offset}. meta.source: adapter that served the data (static_seed = group schedule only).

Return the FIFA World Cup 2026 group draw and advancement format. Returns: data.groups: {group_letter: [4 team codes]} for all 12 groups. data.format: 48-team / 12-group / top-2 + 8-best-thirds rule. data.teams: team-code -> {name, fifa_code} metadata. meta.source: adapter that served the data.

Return a team's aggregate World Cup tournament statistics. Network-only enrichment: requires a configured API-Football (or football-data.org) key. There is no offline static fallback, so without a key the call returns a clean ALL_SOURCES_FAILED envelope. Args: team: API-Football numeric team id (not a country code). Returns: data.team_stats: {team, played, wins, goals_for, goals_against}. meta.source: adapter that served the data.

Return market head-to-head odds for any World Cup 2026 events the odds feed still lists. Sourced from The Odds API (requires THEODDS_KEY). Without a key the call returns a clean ALL_SOURCES_FAILED envelope rather than crashing. The tournament ended with the 2026-07-19 final, so the feed is normally empty. Args: team: Optional team name to filter events (case-insensitive substring, matched against both sides). Omit to return every WC event. Returns: data.events: list of {event_id, home, away, commence_time, bookmakers: [{name, home, draw, away, last_update}]} with decimal 1X2 prices per bookmaker. meta.source: adapter that served the data (theodds / cache:stale).

Return a national team's World Cup squad. Args: team: Team code or name (e.g. "ARG"). Live rosters need an API-Football key; without one the static seed serves an empty-but-valid squad (no rosters are bundled). Returns: data.squad: list of {name, number, position, age} (empty from the seed). meta.source: adapter that served the data. meta.note: present when the seed served it — how to get live squads.

Return current World Cup 2026 group standings. Args: limit: Max standing rows to return, 1..200 (default 50). offset: Number of rows to skip for paging (default 0). Returns: data.standings: page of {rank, team, group, points, played, goals_diff}. data.pagination: {total, count, offset, limit, has_more, next_offset}. meta.source: adapter that served the data.

Return the World Cup 2026 top scorers. Returns: data.scorers: list of {name, team, goals, assists}. meta.source: adapter that served the data.

Round-by-round survival probabilities for one team in the full sim. Args: team: FIFA code or name (e.g. "FRA" or "France"). iterations: Number of tournament simulations (clamped to 100..20000). seed: Optional RNG seed. Returns: data: {team, reach_r32, reach_r16, reach_qf, reach_sf, reach_final, win}. meta.estimated: true.

Predict a single match: most likely scoreline + outcome probabilities. Args: home_team: First team, FIFA code or name (e.g. "ESP" or "Spain"). away_team: Second team, FIFA code or name. neutral: True for a neutral venue (World Cup default). Returns: data: {most_likely_score, home_win, draw, away_win, predicted_winner}. meta.estimated: true.

Monte Carlo the full World Cup 2026 — per-team round + title probabilities. Simulates all 12 groups, advances the top 2 + 8 best third-placed teams to a 32-team knockout, and plays it to a champion, ``iterations`` times. Args: iterations: Number of tournament simulations (clamped to 100..20000; ~10000 gives stable ±2% probabilities). seed: Optional RNG seed for reproducible output. Returns: data.teams: {code: {reach_r32, reach_r16, reach_qf, reach_sf, reach_final, win}} sorted by win probability descending. data.champion: most likely winner. data.iterations: iterations run. meta.estimated: true. meta.conditioned_matches: completed matches locked in (played group results fixed, decided knockout ties locked). Example: football_simulate_bracket() football_simulate_bracket(iterations=20000, seed=42)

Monte Carlo one group within the full 12-group qualification context. Args: group: Group letter A-L (also accepts "Group A"). iterations: Number of simulations (clamped to 100..20000). Returns: data.teams: Per-team position probabilities, p_auto_advance, p_best_third_advance, truthful combined p_advance, and avg_points. data.iterations: iterations actually run. meta.estimated: true. meta.conditioned_matches: completed matches locked in.

Replay World Cup 2026 from a chosen stage, optionally flipping one real knockout result. Keeps every real result played before ``replay_from`` and Monte-Carlos the rest of the tournament from there. ``flip_winner_of`` makes one decided knockout tie in the kept results go the other way first. Args: replay_from: Stage to re-simulate from: "group" (whole tournament, no real results kept), "r32", "r16", "qf", "sf" or "final" (keeps every result before the final and simulates only the final). flip_winner_of: Optional tie to flip, as two FIFA codes or names joined by a hyphen in any order (e.g. "ESP-FRA"). It must be a decided knockout tie before ``replay_from``. iterations: Number of tournament simulations (clamped to 100..20000). seed: Optional RNG seed for reproducible output. Returns: data.teams: {code: {reach_r32, reach_r16, reach_qf, reach_sf, reach_final, win}} sorted by win probability descending. data.champion: most likely winner. data.iterations: iterations run. meta.mode: "what_if". meta.replay_from: the stage. meta.flipped: {tie: [code_a, code_b], winner: code} or null. meta.estimated: true. Example: football_what_if(replay_from="qf") football_what_if(replay_from="final", flip_winner_of="ESP-FRA", seed=7)

Estimate a match's expected goals and win/draw/loss probabilities. Args: home_team: First team, FIFA code or name (e.g. "ARG" or "Argentina"). away_team: Second team, FIFA code or name (e.g. "BRA" or "Brazil"). neutral: True for a neutral venue (no home advantage). World Cup default. Returns: data: {expected_home_goals, expected_away_goals, home_win, draw, away_win}. meta.estimated: true.

Report cache backend, per-adapter healthcheck, and quota status. Returns: HealthReport-shaped dict with `cache_backend`, `cache_ok`, `adapters` (per-source ok/detail), and `quotas`.