@semanticintent/semantic-chirp-intelligence-mcp 3.1.0 → 4.0.0

package/README.md

@@ -1,7 +1,8 @@
 # 🏒 Semantic CHIRP Intelligence MCP
 
-> **Fantasy hockey intelligence that chirps you into championships.**
-> A Model Context Protocol (MCP) server that turns your Yahoo Fantasy Hockey league into an AI advisor — not just a data pipe, but a **Semantic Intent** brain that reads the ice and tells you the cold truth.
+> **Universal fantasy hockey intelligence.**
+> A Model Context Protocol (MCP) server that turns any roster into an AI advisor —
+> no account, no API key, no platform lock-in. Paste your team, get the cold truth.
 
 [![Docs](https://img.shields.io/badge/docs-chirp.semanticintent.dev-1f6feb)](https://chirp.semanticintent.dev)
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
@@ -15,15 +16,25 @@
 
 ## What this is
 
-Most fantasy MCP servers stop at "fetch my roster." This one is a **semantic intelligence layer**: every tool carries intent metadata, analyses run through a shared template, and results come back with a *point of view* — schedule edges, streaming opportunities, and savage roster truths.
+CHIRP is a **players-and-teams intelligence layer**. You tell it who is on your
+roster — by pasting it from anywhere — and it reasons about schedules, statistics,
+lineups, trades and draft value using the NHL's public API.
 
-It's built on the same **Semantic Intent** philosophy as its sibling project, the temporal-intelligence brain [`@semanticintent/semantic-wake-intelligence-mcp`](https://github.com/semanticintent/semantic-wake-intelligence-mcp) — here applied to the domain of fantasy hockey.
+It is not tied to a fantasy platform. Yahoo, ESPN, Sleeper, CBS, a spreadsheet or a
+paper league all work the same way, because the only thing CHIRP needs from you is
+a list of names.
+
+Every tool carries intent metadata, analyses run through a shared template, and
+results come back with a *point of view* — schedule edges, roster truths, and the
+occasional chirp.
 
 ### Highlights
 
+- 🚀 **Zero setup** — no OAuth, no API key, no application to any platform. Install, paste a roster, done.
+- 📋 **Paste from anywhere** — names resolve against live NHL rosters, so team and position fill themselves in. Accents, `Lastname, Firstname` and punctuation all handled.
 - ❄️ **ICE — the Intent Chirp Engine** — championship-level roster analysis with brutal honesty
-- 🗓️ **Schedule intelligence** — games-in-hand edges and streaming windows (NHL public API for real schedules)
-- 🌊 **Weekend stream classifier** — tells desperation pickups apart from genuine multi-week opportunities
+- 🎯 **Draft intelligence** — who to take at pick N, scored on real production and playoff-week schedule
+- 🗓️ **Schedule intelligence** — every game count comes from the NHL's public club-schedule API, per club, per week
 - 🏛️ **Semantic Anchoring Governance** — every tool declares its intent; a dashboard surfaces the health metrics
 - 🧩 **Template Pattern architecture** — analyses are composable, consistent, and testable
 - 🔒 **Read-only & local** — OAuth 2.0, minimum permissions, no third-party data egress
@@ -46,7 +57,10 @@ It's built on the same **Semantic Intent** philosophy as its sibling project, th
 ├─────────────────────────────────────────────────────────────┤
 │  Services (src/services/)                                     │
 │    • ChirpIntelligence  — turns data into chirp               │
-│    • YahooApiClient     — all Yahoo Fantasy API access         │
+│    • NhlScheduleService — schedules, standings (NHL public API)│
+│    • NhlStatsService    — player identity + season statistics  │
+│    • RosterStore        — parses and stores what you paste     │
+│    • LeagueDataService  — league state, source-agnostic        │
 ├─────────────────────────────────────────────────────────────┤
 │  Domain (src/domain/)   — types + governance                 │
 └─────────────────────────────────────────────────────────────┘
@@ -59,90 +73,97 @@ It's built on the same **Semantic Intent** philosophy as its sibling project, th
 
 ## Available Tools
 
-### Core data tools (read-only Yahoo Fantasy)
+### Setting up your league (paste-based)
 
 | Tool | Description |
 |------|-------------|
-| `get_team_roster` | Your current roster with players, positions, and status |
-| `get_league_standings` | League standings — all teams and their records |
-| `get_current_matchup` | Your current week's matchup and status |
-| `search_players` | Search free agents by position (C, LW, RW, D, G) |
-| `get_player_stats` | Detailed stats for a player by ID |
-| `get_weekly_stats` | Your week's stats vs. your opponent |
-| `compare_matchup` | Category-by-category breakdown of your matchup |
-| `optimize_lineup` | Lineup recommendations based on health and positions |
-| `get_trending_players` | Most-added / most-owned players — hot pickups |
-| `debug_api_call` | Inspect raw Yahoo API responses for troubleshooting |
-
-### CHIRP intelligence tools (Template Pattern + semantic analysis)
+| `set_roster` | 📋 Paste your roster. Names resolve against live NHL rosters; team and position fill themselves in |
+| `set_opponent_roster` | 📋 Paste your weekly opponent, enabling head-to-head analysis |
+| `set_standings` | 📊 Paste league standings for league context |
+| `show_stored_data` | 🗂️ Show (or clear) what CHIRP currently knows |
+
+### Core data tools
 
 | Tool | Description |
 |------|-------------|
-| `ice` | ❄️ **Intent Chirp Engine** — the flagship multi-mode advisor; ice-cold, championship-level analysis combining all insights |
-| `get_roster_transaction_recommendations` | 🏒 ICE roster optimization — savage, brutally honest lineup/transaction calls |
-| `get_streaming_recommendations` | Schedule- and trend-aware waiver/streaming picks (weekly / weekend / daily strategies) |
-| `get_games_in_hand` | Schedule-advantage analysis — remaining games, you vs. opponent |
-| `analyze_weekend_streams` | 🌊 Weekend stream classifier — desperation filler vs. genuine multi-week upside (0–100 upside score) |
-| `governance_dashboard` | 🏛️ Semantic Anchoring Governance health, analysis metrics, and violations |
+| `get_team_roster` | Your roster with live NHL club, position, season stats and games this week |
+| `get_league_standings` | The standings you pasted |
+| `search_players` | Search all 1,200+ NHL players by position, ranked by production |
+| `get_player_stats` | Full stats for any player — by name, not an internal id |
+| `compare_matchup` | Category-by-category comparison of your roster against your opponent's |
 
----
+### CHIRP intelligence tools
 
-## Prerequisites
+| Tool | Description |
+|------|-------------|
+| `ice` | ❄️ **Intent Chirp Engine** — the flagship advisor; ice-cold, championship-level roster analysis |
+| `get_roster_transaction_recommendations` | 🏒 ICE roster optimization — savage, brutally honest calls |
+| `optimize_lineup` | Lineup recommendations from health, position and who actually plays tonight |
+| `get_games_in_hand` | Schedule-advantage analysis, you vs. your opponent |
+| `get_streaming_recommendations` | Schedule-aware pickup candidates |
+| `analyze_weekend_streams` | 🌊 Weekend classifier — desperation filler vs. genuine upside |
+| `analyze_breakout_players` | 📈 Breakout candidates scored on real production, opportunity and risk |
+| `analyze_trade` | Category-by-category trade breakdown with an ACCEPT / DECLINE / PUSH verdict |
+| `chirp_opponent` | Scouts your opponent's roster and chirps its weaknesses |
+| `governance_dashboard` | 🏛️ Semantic Anchoring Governance health and analysis metrics |
+
+### Draft tools
 
-- **Node.js 20+**
-- A **Yahoo account** with a Fantasy Hockey team
-- An MCP client — e.g. **Claude Desktop**
+| Tool | Description |
+|------|-------------|
+| `chirp_draft_pick` | 🎯 **ICE at the draft table** — who to take at pick N, given who is gone, what you need, and playoff-week schedule |
+| `schedule_value` | 🗓️ All 32 clubs rated — total games, four-game weeks, light weeks, back-to-backs, playoff-window volume |
 
-## Setup
+> **On availability:** CHIRP knows every NHL player, but it cannot know who is
+> *unowned in your league* — ownership is league-private and no public source
+> exposes it. Pool-based tools therefore return "players not on the rosters you
+> provided", ranked by production, and say so. Check availability before adding.
 
-### 1. Create a Yahoo app
+## Where the numbers come from
 
-Go to [developer.yahoo.com/apps/create](https://developer.yahoo.com/apps/create/) and create an app:
+Every figure is fetched, not estimated — and none of it needs an account:
 
-- **OAuth Client Type:** `Confidential Client`
-- **Redirect URI:** `https://localhost:3000/callback` *(must match exactly)*
-- **API Permissions:** `Fantasy Sports → Read`
+| Signal | Source |
+|--------|--------|
+| Games per week, back-to-backs, playoff-window volume | NHL public API (`club-schedule-season`) — all 32 clubs, cached per season |
+| Player identity, club, position | NHL public API (`roster`) — 1,268 players |
+| Season statistics (skaters and goalies) | NHL public API (`club-stats`) |
+| Opponent difficulty | NHL standings, ranked by goals allowed per game |
+| Your roster, opponent, standings | What you paste |
 
-Copy your **Client ID** and **Client Secret**.
+When a source is unreachable, the tool says so in its output and drops that
+component from its scoring — it does not substitute an estimate for a fact.
 
-> 🔒 Treat the Client Secret like a password. Never commit it. If it ever leaks, **rotate it** by creating a new app and deleting the old one — see [SECURITY.md](./SECURITY.md).
+---
 
-### 2. Find your league and team IDs
+## Prerequisites
 
-From your team URL `https://hockey.fantasysports.yahoo.com/hockey/{LEAGUE_ID}/{TEAM_ID}` — the two numbers are your league and team IDs.
+- **Node.js 20+**
+- An MCP client — e.g. **Claude Desktop**
 
-### 3. Install & configure
+That is the whole list. There is no account to create, no application to file, and
+no credential to store.
 
-```bash
-git clone https://github.com/semanticintent/semantic-chirp-intelligence-mcp.git
-cd semantic-chirp-intelligence-mcp
-npm install
-cp .env.example .env   # then fill in your credentials
-```
+> **Coming from v3?** v3 read your league through the Yahoo Fantasy API. In 2026
+> Yahoo put that API behind a manual approval process that also revoked existing
+> access, so a working install could stop working without any change to the code.
+> v4 removes the dependency entirely: CHIRP now reasons about any roster you paste,
+> on any platform. The Yahoo integration is preserved at the
+> [v3.2.0 tag](https://github.com/semanticintent/semantic-chirp-intelligence-mcp/releases/tag/v3.2.0).
 
-`.env`:
-```
-YAHOO_CLIENT_ID=your_client_id
-YAHOO_CLIENT_SECRET=your_client_secret
-YAHOO_LEAGUE_ID=your_league_id
-YAHOO_TEAM_ID=your_team_id
-```
+---
 
-### 4. Build
+## Setup
 
 ```bash
+git clone https://github.com/semanticintent/semantic-chirp-intelligence-mcp.git
+cd semantic-chirp-intelligence-mcp
+npm install
 npm run build
+npm run preflight    # checks the build and the NHL API — no credentials involved
 ```
 
-### 5. Authenticate with Yahoo (one time)
-
-```bash
-node authenticate.js
-```
-
-Open the printed URL, click through the self-signed-certificate warning (it's a local callback), sign in, and authorize. The token is saved to `.yahoo-oauth.json` (git-ignored). The server auto-refreshes it after that.
-
-### 6. Add to Claude Desktop
+### Add to Claude Desktop
 
 Edit your Claude Desktop config:
 - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -155,10 +176,6 @@ Edit your Claude Desktop config:
       "command": "node",
       "args": ["/absolute/path/to/semantic-chirp-intelligence-mcp/build/index.js"],
       "env": {
-        "YAHOO_CLIENT_ID": "your_client_id",
-        "YAHOO_CLIENT_SECRET": "your_client_secret",
-        "YAHOO_LEAGUE_ID": "your_league_id",
-        "YAHOO_TEAM_ID": "your_team_id",
         "DOTENV_CONFIG_QUIET": "true"
       }
     }
@@ -168,12 +185,20 @@ Edit your Claude Desktop config:
 
 Use an **absolute path** to `build/index.js` (forward slashes, even on Windows). Restart Claude Desktop — the CHIRP tools will appear.
 
+Your credentials stay in the project's git-ignored `.env`; the server resolves
+it from its own install directory, so it is found regardless of the working
+directory the client launches it with. You do **not** need to copy secrets into
+the client config. If you prefer to set them there anyway, a client `env` block
+still overrides the file.
+
 ---
 
 ## Usage
 
 Once connected, just talk to Claude about your team:
 
+- *"I'm on the clock at pick 47 — who should I take?"*
+- *"Which teams have the best schedule during my league's playoff weeks?"*
 - *"Run ICE on my roster — what should I actually do this week?"*
 - *"Where do I have a games-in-hand edge over my opponent?"*
 - *"Find me streaming goalies for the weekend — real value, not desperation pickups."*
@@ -191,6 +216,8 @@ npm run type-check   # tsc --noEmit
 npm test             # run the vitest suite once
 npm run test:watch   # watch mode
 npm run test:coverage
+npm run preflight    # build + NHL API reachability
+npm run smoke        # call every tool and flag crash-like responses
 ```
 
 ### Project structure
@@ -199,25 +226,48 @@ npm run test:coverage
 semantic-chirp-intelligence-mcp/
 ├── src/
 │   ├── index.ts            # MCP server (stdio) + tool registration
-│   ├── analyses/           # Template-Pattern analyses (Ice, Streaming, GamesInHand, WeekendStream, Lineup, Breakout)
+│   ├── analyses/           # Template-Pattern analyses (Ice, Streaming, GamesInHand,
+│   │                       #   WeekendStream, Lineup, Breakout, ScheduleValue, DraftPick)
 │   ├── template/           # AnalysisTemplate base
-│   ├── services/           # ChirpIntelligence, YahooApiClient
+│   ├── services/           # NhlScheduleService, NhlStatsService, RosterStore,
+│   │                       #   LeagueDataService, ChirpIntelligence
 │   ├── config/             # tool-metadata, personality-modes, chirp-styles
-│   ├── domain/             # types, governance
-│   └── experimental/       # semantic-intent parser experiments
+│   ├── domain/             # types, governance, nhl-teams, yahoo-stats
 ├── tests/                  # vitest tests
-├── authenticate.js         # one-time Yahoo OAuth helper
+├── scripts/preflight.mjs   # build + NHL API check
+├── scripts/smoke.mjs       # calls every tool, flags crash-like responses
 ├── docs/                   # documentation (architecture, setup, dev notes)
-└── .env.example
 ```
 
 ---
 
+## Troubleshooting
+
+**A name did not resolve**
+`set_roster` reports every line it could not match to exactly one NHL player,
+under `needs_attention`. Ambiguous surnames come back with their candidates —
+give a full name and re-run. Nothing is ever guessed onto your roster.
+
+**Tools say no roster has been provided**
+Paste one with `set_roster`. `show_stored_data` shows what is currently stored.
+
+**Game counts are zero**
+Check the dates. Outside the regular season there are genuinely no games to count;
+`schedule_value` still works year-round because it reads the whole published season.
+
+**Stats look like last season**
+They are. Before opening night the current season has no statistics at all, so
+CHIRP attaches the last completed season — which is the right basis at a draft.
+Every response names the season it used.
+
+---
+
 ## Security
 
-- **Read-only** integration — requests the minimum Yahoo `Read` permission; never modifies your roster or transactions.
-- **Local-only** — runs over stdio; the only network calls are to Yahoo's API (and the NHL public schedule API).
-- **Secrets never committed** — `.env` and `.yahoo-oauth.json` are git-ignored. See [SECURITY.md](./SECURITY.md) for the full policy and how to rotate a leaked credential.
+- **No credentials at all** — v4 holds no API keys, tokens or account bindings. There is nothing to leak.
+- **Read-only** — the only network calls are GETs to the NHL's public API. CHIRP cannot modify a roster anywhere.
+- **Local-only** — runs over stdio. Your pasted roster stays in `.chirp-data/` on your machine and is git-ignored.
+- See [SECURITY.md](./SECURITY.md) for the full policy.
 
 ## Part of Cormorant Foraging
 
@@ -242,7 +292,7 @@ Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code
 ## Acknowledgments
 
 - [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
-- [Yahoo Fantasy Sports API](https://developer.yahoo.com/fantasysports/)
+- [NHL public API](https://api-web.nhle.com) — schedules, rosters, statistics and standings, free and unauthenticated
 - Sibling project: [`semantic-wake-intelligence-mcp`](https://github.com/semanticintent/semantic-wake-intelligence-mcp)
 
 ---

package/build/analyses/BreakoutAnalysis.js

@@ -12,42 +12,25 @@
  */
 import { AnalysisTemplate } from '../template/AnalysisTemplate.js';
 import { ChirpIntelligence } from '../services/ChirpIntelligence.js';
+import { LEAGUE_DATA, LeagueDataService } from '../services/LeagueDataService.js';
+import { NHL_STATS } from '../services/NhlStatsService.js';
+import { NHL_SCHEDULE } from '../services/NhlScheduleService.js';
 export class BreakoutAnalysis extends AnalysisTemplate {
-    yahooClient;
-    leagueId;
-    teamId;
-    constructor(yahooClient, leagueId, teamId) {
+    constructor() {
         super('get_breakout_analysis', 'streaming_recommendations');
-        this.yahooClient = yahooClient;
-        this.leagueId = leagueId;
-        this.teamId = teamId;
     }
     /**
      * Fetch raw data: free agents, trending players, roster
      */
     async fetchData(args) {
-        const ownershipThreshold = args.ownership_threshold || 50;
-        // Fetch free agents across all positions
-        const positions = args.position_filter || ['C', 'LW', 'RW', 'D', 'G'];
-        const freeAgentPromises = positions.map(pos => this.yahooClient.searchPlayers(pos, 50, this.leagueId));
-        const [freeAgentResults, trendingAdds, roster] = await Promise.all([
-            Promise.all(freeAgentPromises),
-            this.yahooClient.getTrendingPlayers('add', 25, this.leagueId),
-            this.yahooClient.getTeamRoster(this.leagueId, this.teamId)
-        ]);
-        // Combine and deduplicate free agents
-        const allFreeAgents = [];
-        for (const result of freeAgentResults) {
-            if (result.players) {
-                allFreeAgents.push(...result.players);
-            }
-        }
-        // Remove duplicates and filter by ownership
-        const uniqueFreeAgents = Array.from(new Map(allFreeAgents.map(p => [p.player_id, p])).values()).filter(p => (p.percent_owned || 0) < ownershipThreshold);
+        await Promise.all([NHL_STATS.load(), NHL_SCHEDULE.load()]);
+        // Breakout candidates are drawn from every NHL player not already on a
+        // roster you provided, scored on their real season line.
         return {
-            freeAgents: uniqueFreeAgents,
-            trendingAdds: trendingAdds.players || [],
-            roster
+            freeAgents: LEAGUE_DATA.getPlayerPool({ limit: 200 }),
+            trendingAdds: [],
+            roster: LEAGUE_DATA.getRoster(),
+            pool_caveat: LeagueDataService.POOL_CAVEAT
         };
     }
     /**
@@ -228,17 +211,23 @@ export class BreakoutAnalysis extends AnalysisTemplate {
         return 'sleeper';
     }
     /**
-     * Get player metrics (mock implementation)
+     * Real season stat line for a candidate, from Yahoo.
+     *
+     * Missing categories come back as 0 rather than absent so the scoring
+     * formula keeps its shape; `has_stats` distinguishes a genuine zero from a
+     * player Yahoo returned nothing for.
      */
     async getPlayerMetrics(player) {
-        // In real implementation, fetch detailed stats
-        // For now, return mock data
+        // v4: the pool carries NHL season statistics on each player already.
+        const stats = player.stats ?? null;
         return {
-            G: Math.random() * 30,
-            A: Math.random() * 40,
-            GP: 50 + Math.random() * 30,
-            PPP: Math.random() * 20,
-            SOG: Math.random() * 150
+            G: stats?.goals ?? 0,
+            A: stats?.assists ?? 0,
+            GP: stats?.games_played ?? 0,
+            // The NHL feed publishes power-play goals, not power-play points.
+            PPP: stats?.power_play_goals ?? 0,
+            SOG: stats?.shots ?? 0,
+            has_stats: Boolean(stats)
         };
     }
     /**