@semanticintent/semantic-chirp-intelligence-mcp 4.0.4 → 4.1.0

package/build/analyses/DraftKitAnalysis.js

@@ -0,0 +1,333 @@
+/**
+ * 📋 Draft Kit Analysis — tiers, flags, and the schedule nobody else knows
+ *
+ * A conventional draft kit ranks players in the abstract: rankings, tiers,
+ * projections, ADP, sleepers. ChirpIQX cannot produce half of that — there is
+ * no public source of projections, draft-market consensus, line combinations
+ * or injuries, and inventing them would be the same sin as the constants and
+ * random numbers this codebase spent v3.2 removing.
+ *
+ * What it can do is the half that depends on facts: real production, real ages,
+ * and the real schedule — including the weeks *your* league plays its playoffs,
+ * which no published kit can know.
+ *
+ * So this tool works two ways, from one engine:
+ *
+ *   • no `rankings` given  — builds the board from last season's production
+ *   • `rankings` pasted    — keeps that order as the baseline and annotates it
+ *
+ * The second mode is the useful one: bring a kit you trust for projections,
+ * and let ChirpIQX overlay schedule and flags onto it.
+ *
+ * 🏛️ Rule 3 (Observable Anchoring): every figure names the season it came from,
+ * and the response states plainly what a draft kit normally contains that this
+ * one does not.
+ */
+import { AnalysisTemplate } from '../template/AnalysisTemplate.js';
+import { ChirpIntelligence } from '../services/ChirpIntelligence.js';
+import { NHL_SCHEDULE, NhlScheduleService } from '../services/NhlScheduleService.js';
+import { NHL_STATS, NhlStatsService } from '../services/NhlStatsService.js';
+import { ROSTER_STORE } from '../services/RosterStore.js';
+/** Positions a kit is organised by, in the order people draft them. */
+const KIT_POSITIONS = ['C', 'LW', 'RW', 'D', 'G'];
+/** NHL position codes map to the winger labels fantasy platforms use. */
+const NHL_TO_FANTASY = { C: 'C', L: 'LW', R: 'RW', D: 'D', G: 'G' };
+export class DraftKitAnalysis extends AnalysisTemplate {
+    constructor() {
+        super('draft_kit', 'draft_pick');
+    }
+    // ==========================================
+    // Hook 1: Fetch
+    // ==========================================
+    async fetchData(args) {
+        await Promise.all([NHL_STATS.load(), NHL_SCHEDULE.load()]);
+        return {};
+    }
+    // ==========================================
+    // Hook 2: Prepare
+    // ==========================================
+    async prepareData(rawData, args) {
+        const window = this.resolvePlayoffWindow(args);
+        // Two entry points, one engine.
+        const pasted = String(args.rankings ?? '').trim();
+        const source = pasted ? 'pasted rankings' : 'NHL production';
+        const { players, unresolved } = pasted
+            ? this.fromPastedRankings(pasted)
+            : { players: this.fromProduction(), unresolved: [] };
+        return { kitPlayers: players, unresolved, window, source };
+    }
+    /**
+     * Resolve a pasted ranked list, preserving its order.
+     *
+     * The list's own ordering is the baseline rank — that is the whole point of
+     * the overlay mode. Someone else did the projection work; this adds what
+     * they could not know.
+     */
+    fromPastedRankings(text) {
+        const report = ROSTER_STORE.parseRoster(text);
+        const players = report.resolved
+            .map(p => NHL_STATS.getById(p.player_id))
+            .filter((p) => p !== null);
+        return { players, unresolved: [...report.unresolved, ...report.ambiguous] };
+    }
+    /** Build a board from last season's production when no list is given. */
+    fromProduction() {
+        return NHL_STATS.getAll()
+            .filter(p => (p.stats?.games_played ?? 0) > 0)
+            .sort((a, b) => this.productionValue(b) - this.productionValue(a));
+    }
+    /** Skaters rank on points, goalies on wins — they are not comparable. */
+    productionValue(p) {
+        return p.position === 'G' ? (p.stats?.wins ?? 0) : (p.stats?.points ?? 0);
+    }
+    // ==========================================
+    // Hook 3: Analyze
+    // ==========================================
+    async analyzeData(data, args) {
+        const d = data;
+        const window = d.window;
+        const tierSize = Math.max(3, args.tier_size ?? 6);
+        const maxPerPosition = Math.max(5, args.max_per_position ?? 24);
+        const wanted = (args.positions?.length ? args.positions : KIT_POSITIONS)
+            .map(p => p.toUpperCase());
+        const annotated = d.kitPlayers.map((p, index) => this.annotate(p, index + 1, window));
+        // Tiers are per position, because "when does C dry up" is the question a
+        // draft kit exists to answer.
+        const byPosition = {};
+        for (const pos of wanted) {
+            const group = annotated.filter(p => p.position === pos).slice(0, maxPerPosition);
+            if (group.length === 0)
+                continue;
+            byPosition[pos] = {
+                count: group.length,
+                tiers: this.buildTiers(group, tierSize),
+                // Where the position stops being replaceable.
+                dries_up_after: group.length >= tierSize ? `tier ${Math.ceil(group.length / tierSize)}` : 'one tier'
+            };
+        }
+        return {
+            source: d.source,
+            stats_season: NHL_STATS.getSeasons().stats,
+            playoff_window: window,
+            unresolved: d.unresolved,
+            positions: byPosition,
+            signals: {
+                shooting_rebounds: this.shootingRebounds(annotated),
+                decline_risk: this.declineRisk(annotated),
+                playoff_schedule_winners: this.playoffWinners(annotated, window),
+                category_specialists: this.categorySpecialists(annotated)
+            },
+            cheat_sheet: this.cheatSheet(byPosition),
+            not_included: [
+                'Projections for the coming season — ChirpIQX reports the last completed season, it does not forecast',
+                'ADP or value-vs-market — there is no public source of draft-market consensus',
+                'Line combinations and power-play units — the NHL does not publish them',
+                'Injury status — no public feed',
+                'Whether a player is available in your league — ownership is league-private'
+            ]
+        };
+    }
+    annotate(p, rank, window) {
+        const s = p.stats;
+        const gp = s?.games_played ?? 0;
+        const points = s?.points ?? 0;
+        const profile = NHL_SCHEDULE.isAvailable() ? NHL_SCHEDULE.getTeamProfile(p.team) : null;
+        const playoffGames = window?.resolved && NHL_SCHEDULE.isAvailable()
+            ? NHL_SCHEDULE.countGamesInRange(p.team, window.start, window.end)
+            : null;
+        return {
+            rank,
+            player_id: p.player_id,
+            name: p.name,
+            team: p.team,
+            position: NHL_TO_FANTASY[p.position] ?? p.position,
+            age: NhlStatsService.ageOf(p),
+            games_played: gp,
+            points,
+            points_per_game: gp > 0 ? Number((points / gp).toFixed(2)) : 0,
+            playoff_games: playoffGames,
+            four_game_weeks: profile?.weeks_with_4_plus ?? null,
+            flags: this.flagsFor(p, playoffGames)
+        };
+    }
+    /** Short, human-readable notes that survive being read at speed. */
+    flagsFor(p, playoffGames) {
+        const flags = [];
+        const s = p.stats;
+        const age = NhlStatsService.ageOf(p);
+        const gp = s?.games_played ?? 0;
+        if (!s || gp < 20)
+            return flags;
+        if (p.position !== 'G') {
+            const shots = s.shots ?? 0;
+            const shPct = shots > 0 ? ((s.goals ?? 0) / shots) * 100 : 0;
+            if (age !== null && age <= 25 && shots >= 150 && shPct < 8) {
+                flags.push(`shooting ${shPct.toFixed(1)}% on ${shots} shots — volume without conversion`);
+            }
+            if (age !== null && age >= 33 && (s.time_on_ice_per_game ?? 0) / 60 >= 19) {
+                flags.push(`age ${age} on ${((s.time_on_ice_per_game ?? 0) / 60).toFixed(1)} min — usage may not hold`);
+            }
+            if ((s.penalty_minutes ?? 0) / gp >= 1.2) {
+                flags.push(`${((s.penalty_minutes ?? 0) / gp).toFixed(2)} PIM/gm`);
+            }
+            if ((s.shots ?? 0) / gp >= 3.2) {
+                flags.push(`${((s.shots ?? 0) / gp).toFixed(1)} shots/gm`);
+            }
+        }
+        else if ((s.save_percentage ?? 0) >= 0.915 && (s.wins ?? 0) < 28) {
+            flags.push(`${(s.save_percentage ?? 0).toFixed(3)} SV% on only ${s.wins} wins — rate beats the record`);
+        }
+        if (playoffGames !== null && playoffGames >= 11)
+            flags.push(`${playoffGames} playoff-window games`);
+        if (playoffGames !== null && playoffGames <= 8)
+            flags.push(`only ${playoffGames} playoff-window games`);
+        return flags;
+    }
+    buildTiers(group, tierSize) {
+        const tiers = [];
+        for (let i = 0; i < group.length; i += tierSize) {
+            const slice = group.slice(i, i + tierSize);
+            tiers.push({
+                tier: tiers.length + 1,
+                players: slice.map(p => ({
+                    rank: p.rank,
+                    name: p.name,
+                    team: p.team,
+                    age: p.age,
+                    ppg: p.points_per_game,
+                    playoff_games: p.playoff_games,
+                    flags: p.flags
+                }))
+            });
+        }
+        return tiers;
+    }
+    // ==========================================
+    // 🎯 Signals
+    // ==========================================
+    shootingRebounds(players) {
+        return players
+            .filter(p => p.flags.some(f => f.includes('volume without conversion')))
+            .slice(0, 8)
+            .map(p => ({ name: p.name, team: p.team, position: p.position, age: p.age, note: p.flags[0] }));
+    }
+    declineRisk(players) {
+        return players
+            .filter(p => p.flags.some(f => f.includes('usage may not hold')))
+            .slice(0, 8)
+            .map(p => ({ name: p.name, team: p.team, position: p.position, age: p.age, note: p.flags.find(f => f.includes('usage')) }));
+    }
+    playoffWinners(players, window) {
+        if (!window?.resolved)
+            return [];
+        return players
+            .filter(p => (p.playoff_games ?? 0) >= 11)
+            .sort((a, b) => b.points_per_game - a.points_per_game)
+            .slice(0, 10)
+            .map(p => ({
+            name: p.name, team: p.team, position: p.position,
+            ppg: p.points_per_game, playoff_games: p.playoff_games
+        }));
+    }
+    categorySpecialists(players) {
+        const pick = (needle, limit = 5) => players
+            .filter(p => p.flags.some(f => f.includes(needle)))
+            .slice(0, limit)
+            .map(p => ({ name: p.name, team: p.team, position: p.position, note: p.flags.find(f => f.includes(needle)) }));
+        return {
+            penalty_minutes: pick('PIM/gm'),
+            shot_volume: pick('shots/gm'),
+            goalie_rate_over_record: pick('rate beats the record')
+        };
+    }
+    /** The condensed board — the format people actually take to a draft. */
+    cheatSheet(byPosition) {
+        const sheet = {};
+        for (const [pos, data] of Object.entries(byPosition)) {
+            sheet[pos] = data.tiers.map((t) => `T${t.tier}: ` + t.players
+                .map((p) => `${p.name}${p.playoff_games !== null ? ` (${p.playoff_games})` : ''}`)
+                .join(', '));
+        }
+        return {
+            note: 'Numbers in brackets are games during your playoff window.',
+            board: sheet
+        };
+    }
+    // ==========================================
+    // Hooks 4 & 5
+    // ==========================================
+    async generateChirp(analysisResults, semanticContract, data) {
+        const contract = this.mergeContractWithDefaults(semanticContract);
+        const enhanced = ChirpIntelligence.enhance(this.toolName, analysisResults, contract);
+        const winners = analysisResults.signals.playoff_schedule_winners;
+        const rebounds = analysisResults.signals.shooting_rebounds;
+        const parts = [];
+        parts.push(analysisResults.source === 'pasted rankings'
+            ? 'Working from your list — the order is theirs, the schedule and flags are mine.'
+            : `Board built from ${analysisResults.stats_season} production.`);
+        if (winners?.length) {
+            parts.push(`${winners[0].name} is the best producer on an 11-game playoff club. That is your tiebreaker.`);
+        }
+        if (rebounds?.length) {
+            parts.push(`${rebounds[0].name} is shooting well under his volume — that usually corrects.`);
+        }
+        if (!analysisResults.playoff_window?.resolved) {
+            parts.push('Pass playoff_start_week and playoff_end_week and the schedule half of this becomes real.');
+        }
+        return {
+            ...enhanced,
+            chirp_intelligence: { ...enhanced.chirp_intelligence, analysis_chirp: parts.join(' ') }
+        };
+    }
+    async formatResponse(chirpEnhanced, data) {
+        const recommendations = (chirpEnhanced.signals?.playoff_schedule_winners ?? []).slice(0, 5).map((p, i) => ({
+            priority: i < 2 ? 'HIGH' : 'MEDIUM',
+            action: 'target',
+            reasoning: `${p.name} (${p.team} ${p.position}) — ${p.ppg} P/gm and ${p.playoff_games} games in your playoff window`
+        }));
+        const analysisInsights = {
+            source: chirpEnhanced.source,
+            stats_season: chirpEnhanced.stats_season,
+            schedule_source: NHL_SCHEDULE.isAvailable()
+                ? `NHL public API (season ${NHL_SCHEDULE.getSeason()})`
+                : `UNAVAILABLE - ${NHL_SCHEDULE.getUnavailableReason()}`,
+            playoff_window: chirpEnhanced.playoff_window,
+            positions: chirpEnhanced.positions,
+            signals: chirpEnhanced.signals,
+            cheat_sheet: chirpEnhanced.cheat_sheet,
+            not_included: chirpEnhanced.not_included,
+            ...(chirpEnhanced.unresolved?.length ? { rankings_not_matched: chirpEnhanced.unresolved } : {})
+        };
+        const metadata = {
+            analysis_type: this.analysisType,
+            timestamp: new Date().toISOString(),
+            team_context: { team_name: 'Draft Kit' },
+            semantic_contract_applied: true
+        };
+        return {
+            analysis_insights: analysisInsights,
+            recommendations,
+            chirp_intelligence: chirpEnhanced.chirp_intelligence,
+            metadata
+        };
+    }
+    /** Same anchoring as the other draft tools: week 1 is the NHL opener. */
+    resolvePlayoffWindow(args) {
+        const startWeek = Number(args?.playoff_start_week ?? 0);
+        const endWeek = Number(args?.playoff_end_week ?? 0);
+        const seasonStart = NHL_SCHEDULE.getSeasonStartDate();
+        if (!startWeek || !endWeek || startWeek > endWeek || !seasonStart) {
+            return { resolved: false, start: null, end: null, weeks: [] };
+        }
+        const week1Monday = NhlScheduleService.weekStart(seasonStart);
+        return {
+            resolved: true,
+            week_1_anchor: `${week1Monday} (NHL season opener)`,
+            playoff_start_week: startWeek,
+            end_week: endWeek,
+            start: NhlScheduleService.addDays(week1Monday, (startWeek - 1) * 7),
+            end: NhlScheduleService.addDays(week1Monday, endWeek * 7 - 1),
+            weeks: Array.from({ length: endWeek - startWeek + 1 }, (_, i) => NhlScheduleService.addDays(week1Monday, (startWeek - 1 + i) * 7))
+        };
+    }
+}

package/build/config/tool-metadata.js

@@ -157,6 +157,18 @@ export const TOOL_METADATA = {
         template_version: "1.0.0",
         analysis_type: "schedule_advantage"
     },
+    draft_kit: {
+        chirp_style: "strategic_advantage",
+        discovery_tags: ["draft", "kit", "tiers", "cheat_sheet", "rankings", "sleepers"],
+        intent_category: "draft_intelligence",
+        hockey_context: "draft_preparation",
+        chirp_potential: "draft_board_truth",
+        // 🆕 Template Pattern Metadata
+        uses_template_pattern: true,
+        analysis_class: "DraftKitAnalysis",
+        template_version: "1.0.0",
+        analysis_type: "draft_pick"
+    },
     chirp_draft_pick: {
         chirp_style: "ice_cold_truth",
         discovery_tags: ["draft", "pick", "ADP", "value", "roster_build"],

package/build/index.js

@@ -24,6 +24,7 @@ import { WeekendStreamAnalysis } from './analyses/WeekendStreamAnalysis.js';
 import { BreakoutAnalysis } from './analyses/BreakoutAnalysis.js';
 import { ScheduleValueAnalysis } from './analyses/ScheduleValueAnalysis.js';
 import { DraftPickAnalysis } from './analyses/DraftPickAnalysis.js';
+import { DraftKitAnalysis } from './analyses/DraftKitAnalysis.js';
 import { NHL_STATS } from './services/NhlStatsService.js';
 import { ROSTER_STORE } from './services/RosterStore.js';
 import { LEAGUE_DATA, NO_ROSTER_MESSAGE, NO_OPPONENT_MESSAGE } from './services/LeagueDataService.js';
@@ -60,6 +61,7 @@ const lineupAnalysis = new LineupAnalysis();
 const breakoutAnalysis = new BreakoutAnalysis();
 const scheduleValueAnalysis = new ScheduleValueAnalysis();
 const draftPickAnalysis = new DraftPickAnalysis();
+const draftKitAnalysis = new DraftKitAnalysis();
 const weekendStreamAnalysis = new WeekendStreamAnalysis();
 // Helper function to find current matchup by status
 function findCurrentMatchup(matchups) {
@@ -1191,6 +1193,35 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     }
                 }
             },
+            {
+                name: "draft_kit",
+                description: "📋 A full draft kit — positional tiers, a cheat sheet, and flags you cannot get elsewhere: playoff-window schedule per club, shooting-luck rebound candidates, age-based decline risk, and category specialists. Works two ways: call it plain and it builds the board from last season's NHL production, or paste a ranked list (from any published kit) and it keeps that order while annotating it with schedule and flags. States plainly what it does not include — no projections, no ADP, no line combos, no injuries.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        playoff_start_week: {
+                            type: "number",
+                            description: "First week of your fantasy playoffs. Supply this with playoff_end_week and every player gets their club's playoff-window game count."
+                        },
+                        playoff_end_week: {
+                            type: "number",
+                            description: "Final week of your fantasy playoffs."
+                        },
+                        rankings: {
+                            type: "string",
+                            description: "Optional. Paste a ranked player list — from NHL.com, Dobber, FantasyPros, anywhere — one per line. Its order becomes the baseline rank and CHIRP annotates it rather than replacing it. Omit to have the board built from NHL production instead."
+                        },
+                        positions: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Limit to positions, e.g. [\"C\", \"G\"] (default: all)"
+                        },
+                        tier_size: { type: "number", description: "Players per tier (default 6)", default: 6 },
+                        max_per_position: { type: "number", description: "How deep to go per position (default 24)", default: 24 },
+                        ...baseChirpSchema
+                    }
+                }
+            },
             {
                 name: "chirp_draft_pick",
                 description: "❄️ ICE at the draft table — with a pick on the clock, ranks who to take against YOUR draft: who is already gone, what your roster still needs, Yahoo's ADP (so 'value' means the market is wrong here), and each club's schedule during your league's playoff weeks. Pass already_drafted if Yahoo's draft results lag your live draft.",
@@ -1633,6 +1664,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     };
                 }
             }
+            case "draft_kit": {
+                try {
+                    const result = await draftKitAnalysis.executeAnalysis({
+                        playoff_start_week: args?.playoff_start_week,
+                        playoff_end_week: args?.playoff_end_week,
+                        rankings: args?.rankings,
+                        positions: args?.positions,
+                        tier_size: args?.tier_size,
+                        max_per_position: args?.max_per_position
+                    }, {
+                        chirp_intensity: args?.chirp_intensity || 'standard',
+                        personality_mode: args?.personality_mode || 'analytical',
+                        enable_chirp: args?.enable_chirp !== false,
+                        semantic_intent: 'user_requested'
+                    });
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({
+                                    error: errorMessage,
+                                    note: "Draft kit failed - it needs only the NHL public API, so retry shortly"
+                                }, null, 2) }],
+                        isError: true
+                    };
+                }
+            }
             case "chirp_draft_pick": {
                 try {
                     const semanticContract = {

package/build/services/NhlStatsService.js

@@ -25,6 +25,15 @@ const __dirname = path.dirname(__filename);
 const NHL_API_BASE = 'https://api-web.nhle.com/v1';
 const GAME_TYPE_REGULAR_SEASON = 2;
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Bump whenever the cached player shape changes.
+ *
+ * The cache is keyed by season, so adding a field to NhlPlayer would otherwise
+ * keep serving records without it until the TTL expired — silently, and looking
+ * exactly like the field is unavailable from the NHL. Including the version in
+ * the filename makes a shape change invalidate the cache immediately.
+ */
+const CACHE_SCHEMA_VERSION = 2;
 export class NhlStatsService {
     byId = new Map();
     byNameKey = new Map();
@@ -113,6 +122,7 @@ export class NhlStatsService {
                         name: `${p.firstName?.default ?? ''} ${p.lastName?.default ?? ''}`.trim(),
                         team,
                         position: p.positionCode ?? (group === 'goalies' ? 'G' : '?'),
+                        birth_date: p.birthDate,
                         stats: statsById.get(id)
                     });
                 }
@@ -235,6 +245,21 @@ export class NhlStatsService {
     getByTeam(team) {
         return this.getAll().filter(p => p.team === team);
     }
+    /**
+     * Age in years at a given date, or null when the birth date is unknown.
+     *
+     * Age drives the breakout and decline signals a draft kit needs, and the NHL
+     * publishes it on the roster endpoint, so there is no reason to estimate it.
+     */
+    static ageOf(player, asOf = new Date()) {
+        if (!player.birth_date)
+            return null;
+        const born = Date.parse(`${player.birth_date}T00:00:00Z`);
+        if (!Number.isFinite(born))
+            return null;
+        const years = (asOf.getTime() - born) / (365.2425 * 24 * 60 * 60 * 1000);
+        return Number(years.toFixed(1));
+    }
     getPlayerCount() {
         return this.byId.size;
     }
@@ -259,7 +284,7 @@ export class NhlStatsService {
     // 🎯 Cache
     // ==========================================
     cachePath(rosterSeason, statsSeason) {
-        return path.join(this.cacheDir, `players-${rosterSeason}-${statsSeason}.json`);
+        return path.join(this.cacheDir, `players-v${CACHE_SCHEMA_VERSION}-${rosterSeason}-${statsSeason}.json`);
     }
     readCache(rosterSeason, statsSeason) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semanticintent/semantic-chirp-intelligence-mcp",
-  "version": "4.0.4",
+  "version": "4.1.0",
   "description": "Universal fantasy hockey intelligence \u2014 a Model Context Protocol server that reads NHL schedule and player data and analyses any roster you paste. No account, no API key, no platform lock-in.",
   "type": "module",
   "main": "build/index.js",

package/scripts/smoke.mjs

@@ -39,6 +39,7 @@ const TOOLS = [
   ['analyze_trade', { giving: ['Cale Makar'], receiving: ['Quinn Hughes'] }],
   ['schedule_value', { teams: ['TOR', 'SEA'], playoff_start_week: 22, playoff_end_week: 24 }],
   ['chirp_draft_pick', { pick_number: 5, max_results: 5 }],
+  ['draft_kit', { playoff_start_week: 22, playoff_end_week: 24, positions: ['C'], max_per_position: 6 }],
 ];
 
 const proc = spawn(process.execPath, ['build/index.js'], { stdio: ['pipe', 'pipe', 'pipe'] });