@semanticintent/semantic-chirp-intelligence-mcp 3.0.0

package/.env.example

@@ -0,0 +1,8 @@
+# Get these from https://developer.yahoo.com/apps/create/
+YAHOO_CLIENT_ID=your_client_id_here
+YAHOO_CLIENT_SECRET=your_client_secret_here
+
+# Your league and team IDs, from your team URL:
+# https://hockey.fantasysports.yahoo.com/hockey/{LEAGUE_ID}/{TEAM_ID}
+YAHOO_LEAGUE_ID=your_league_id_here
+YAHOO_TEAM_ID=your_team_id_here

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 semanticintent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# 🏒 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.
+
+[![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)
+![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
+![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)
+
+📖 **Full documentation:** [chirp.semanticintent.dev](https://chirp.semanticintent.dev)
+
+---
+
+## 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.
+
+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.
+
+### Highlights
+
+- ❄️ **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
+- 🏛️ **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
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  MCP Server (src/index.ts)  — stdio transport for Claude     │
+├─────────────────────────────────────────────────────────────┤
+│  Semantic config (src/config/)                               │
+│    • tool-metadata.ts   — intent, discovery tags, chirp style │
+│    • personality-modes.ts / chirp-styles.ts — the voice       │
+├─────────────────────────────────────────────────────────────┤
+│  Intelligence layer (src/analyses/ + src/template/)          │
+│    • AnalysisTemplate   — shared Template Pattern base         │
+│    • Ice / Streaming / GamesInHand / WeekendStream / Lineup   │
+├─────────────────────────────────────────────────────────────┤
+│  Services (src/services/)                                     │
+│    • ChirpIntelligence  — turns data into chirp               │
+│    • YahooApiClient     — all Yahoo Fantasy API access         │
+├─────────────────────────────────────────────────────────────┤
+│  Domain (src/domain/)   — types + governance                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **Semantic Anchoring Governance** — every tool registers intent metadata (intent category, hockey context, discovery tags, chirp potential). See [`SEMANTIC_ANCHORING_GOVERNANCE.md`](./SEMANTIC_ANCHORING_GOVERNANCE.md). The `governance_dashboard` tool reports live health.
+- **Template Pattern** — analyses extend `AnalysisTemplate`, so each one produces output the same disciplined way. Adding an analysis is adding one class.
+
+---
+
+## Available Tools
+
+### Core data tools (read-only Yahoo Fantasy)
+
+| 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)
+
+| 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 |
+
+---
+
+## Prerequisites
+
+- **Node.js 20+**
+- A **Yahoo account** with a Fantasy Hockey team
+- An MCP client — e.g. **Claude Desktop**
+
+## Setup
+
+### 1. Create a Yahoo app
+
+Go to [developer.yahoo.com/apps/create](https://developer.yahoo.com/apps/create/) and create an app:
+
+- **OAuth Client Type:** `Confidential Client`
+- **Redirect URI:** `https://localhost:3000/callback` *(must match exactly)*
+- **API Permissions:** `Fantasy Sports → Read`
+
+Copy your **Client ID** and **Client Secret**.
+
+> 🔒 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
+
+From your team URL `https://hockey.fantasysports.yahoo.com/hockey/{LEAGUE_ID}/{TEAM_ID}` — the two numbers are your league and team IDs.
+
+### 3. Install & configure
+
+```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
+```
+
+`.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
+
+```bash
+npm run build
+```
+
+### 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
+
+Edit your Claude Desktop config:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "semantic-chirp-intelligence-mcp": {
+      "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"
+      }
+    }
+  }
+}
+```
+
+Use an **absolute path** to `build/index.js` (forward slashes, even on Windows). Restart Claude Desktop — the CHIRP tools will appear.
+
+---
+
+## Usage
+
+Once connected, just talk to Claude about your team:
+
+- *"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."*
+- *"Am I winning my matchup? Which categories am I losing?"*
+- *"Who are the hottest waiver adds in my league?"*
+- *"Show me the governance dashboard."*
+
+---
+
+## Development
+
+```bash
+npm run build        # compile TypeScript -> build/
+npm run type-check   # tsc --noEmit
+npm test             # run the vitest suite once
+npm run test:watch   # watch mode
+npm run test:coverage
+```
+
+### Project structure
+
+```
+semantic-chirp-intelligence-mcp/
+├── src/
+│   ├── index.ts            # MCP server (stdio) + tool registration
+│   ├── analyses/           # Template-Pattern analyses (Ice, Streaming, GamesInHand, WeekendStream, Lineup, Breakout)
+│   ├── template/           # AnalysisTemplate base
+│   ├── services/           # ChirpIntelligence, YahooApiClient
+│   ├── config/             # tool-metadata, personality-modes, chirp-styles
+│   ├── domain/             # types, governance
+│   └── experimental/       # semantic-intent parser experiments
+├── tests/                  # vitest tests
+├── authenticate.js         # one-time Yahoo OAuth helper
+├── docs/                   # documentation (architecture, setup, dev notes)
+└── .env.example
+```
+
+---
+
+## 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.
+
+## Part of Cormorant Foraging
+
+ChirpIQX is the **Sound** (communication) dimension of [Cormorant Foraging](https://cormorantforaging.dev) — a family of Semantic Intent intelligence systems, each mapping a different dimension:
+
+| System | Dimension | Domain |
+|--------|-----------|--------|
+| **ChirpIQX** *(this repo)* | Sound | Fantasy hockey intelligence |
+| **WakeIQX** | Time | [AI context temporal intelligence](https://github.com/semanticintent/semantic-wake-intelligence-mcp) |
+| **PerchIQX** | Space | Database schema intelligence |
+
+📖 Learn more at [chirp.semanticintent.dev](https://chirp.semanticintent.dev) · [cormorantforaging.dev](https://cormorantforaging.dev)
+
+## Contributing
+
+Contributions welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md). New analyses should extend `AnalysisTemplate` and declare intent metadata in `tool-metadata.ts`.
+
+## License
+
+[MIT](./LICENSE) © semanticintent
+
+## Acknowledgments
+
+- [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
+- [Yahoo Fantasy Sports API](https://developer.yahoo.com/fantasysports/)
+- Sibling project: [`semantic-wake-intelligence-mcp`](https://github.com/semanticintent/semantic-wake-intelligence-mcp)
+
+---
+
+**🏒 Now go win your league. ICE doesn't lie.**

package/authenticate.js

@@ -0,0 +1,207 @@
+// OAuth Helper Script for Yahoo Fantasy
+// Run this ONCE to get your access token
+// Usage: node authenticate.js
+
+import * as fs from 'fs';
+import * as dotenv from 'dotenv';
+import * as https from 'https';
+import * as url from 'url';
+import selfsigned from 'selfsigned';
+
+dotenv.config();
+
+const CLIENT_ID = process.env.YAHOO_CLIENT_ID;
+const CLIENT_SECRET = process.env.YAHOO_CLIENT_SECRET;
+const REDIRECT_URI = 'https://localhost:3000/callback';
+const TOKEN_FILE = '.yahoo-oauth.json';
+
+if (!CLIENT_ID || !CLIENT_SECRET) {
+  console.error('❌ Missing YAHOO_CLIENT_ID or YAHOO_CLIENT_SECRET in .env');
+  console.error('📝 Please create a .env file with your Yahoo API credentials');
+  console.error('   Get them from: https://developer.yahoo.com/apps/create/');
+  process.exit(1);
+}
+
+// Generate self-signed certificate for local HTTPS
+console.log('🔐 Generating self-signed certificate for HTTPS...');
+const attrs = [{ name: 'commonName', value: 'localhost' }];
+const pems = selfsigned.generate(attrs, {
+  keySize: 2048,
+  days: 365,
+  algorithm: 'sha256',
+  extensions: [
+    {
+      name: 'subjectAltName',
+      altNames: [
+        { type: 2, value: 'localhost' },
+        { type: 7, ip: '127.0.0.1' }
+      ]
+    }
+  ]
+});
+
+console.log('🔐 Starting Yahoo OAuth flow...\n');
+
+// HTTPS server options with self-signed certificate
+const serverOptions = {
+  key: pems.private,
+  cert: pems.cert,
+};
+
+// Create an HTTPS server to handle the callback
+const server = https.createServer(serverOptions, async (req, res) => {
+  const parsedUrl = url.parse(req.url, true);
+
+  if (parsedUrl.pathname === '/') {
+    // Build Yahoo OAuth authorization URL
+    const authUrl = `https://api.login.yahoo.com/oauth2/request_auth?client_id=${CLIENT_ID}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&response_type=code&language=en-us`;
+
+    res.writeHead(302, { 'Location': authUrl });
+    res.end();
+    console.log('🔐 Redirecting to Yahoo for authorization...');
+    return;
+  }
+
+  if (parsedUrl.pathname === '/callback') {
+    const authCode = parsedUrl.query.code;
+
+    if (!authCode) {
+      res.writeHead(400, { 'Content-Type': 'text/html' });
+      res.end('<h1>❌ Error: No authorization code received</h1>');
+      setTimeout(() => {
+        server.close();
+        process.exit(1);
+      }, 1000);
+      return;
+    }
+
+    try {
+      console.log('📝 Exchanging authorization code for access token...');
+
+      // Exchange the code for a token
+      const tokenResponse = await fetch('https://api.login.yahoo.com/oauth2/get_token', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Authorization': 'Basic ' + Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')
+        },
+        body: new URLSearchParams({
+          grant_type: 'authorization_code',
+          redirect_uri: REDIRECT_URI,
+          code: authCode
+        })
+      });
+
+      if (!tokenResponse.ok) {
+        throw new Error(`Token exchange failed: ${tokenResponse.status} ${tokenResponse.statusText}`);
+      }
+
+      const token = await tokenResponse.json();
+      console.log('📝 Token retrieved successfully');
+
+      // Save the token with timestamp
+      const tokenWithTimestamp = {
+        access_token: token.access_token,
+        refresh_token: token.refresh_token,
+        expires_in: token.expires_in,
+        token_type: token.token_type,
+        xoauth_yahoo_guid: token.xoauth_yahoo_guid,
+        timestamp: Date.now(),
+      };
+
+      fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokenWithTimestamp, null, 2));
+      console.log(`✅ Token saved to ${TOKEN_FILE}`);
+
+      // Success page
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <html>
+          <head>
+            <title>🏒 Authentication Successful - ICE Activated</title>
+            <style>
+              body {
+                font-family: Arial, sans-serif;
+                padding: 50px;
+                text-align: center;
+                background: linear-gradient(135deg, #0891b2 0%, #06b6d4 100%);
+                color: white;
+              }
+              .container {
+                background: white;
+                color: #333;
+                padding: 40px;
+                border-radius: 10px;
+                max-width: 500px;
+                margin: 0 auto;
+                box-shadow: 0 10px 40px rgba(0,0,0,0.2);
+              }
+              h1 { color: #0891b2; }
+              .emoji { font-size: 48px; margin: 20px 0; }
+              code {
+                background: #f5f5f5;
+                padding: 2px 6px;
+                border-radius: 3px;
+                color: #0891b2;
+              }
+            </style>
+          </head>
+          <body>
+            <div class="container">
+              <div class="emoji">🏒✅❄️</div>
+              <h1>ICE Activated!</h1>
+              <p>Yahoo authentication successful. Intent Chirp Engine is ready to dominate.</p>
+              <p>You can close this window and return to your terminal.</p>
+              <hr>
+              <p><strong>Next steps:</strong></p>
+              <ol style="text-align: left; display: inline-block;">
+                <li>Server is built and ready</li>
+                <li>Test with: <code>npm start</code></li>
+                <li>Add to Claude Desktop config</li>
+                <li>Start getting chirped with winning insights</li>
+              </ol>
+            </div>
+          </body>
+        </html>
+      `);
+
+      // Close server after success
+      setTimeout(() => {
+        server.close();
+        console.log('\n🏒 ICE is ready! Next steps:');
+        console.log('   1. Test the server: npm start');
+        console.log('   2. Add to Claude Desktop config (see ACTIVATION_STEPS.md)');
+        console.log('   3. Start dominating your fantasy league with semantic chirps');
+        process.exit(0);
+      }, 1000);
+    } catch (error) {
+      console.error('❌ Error during callback:', error);
+      res.writeHead(500, { 'Content-Type': 'text/html' });
+      res.end(`
+        <html>
+          <head><title>Authentication Failed</title></head>
+          <body style="font-family: Arial; padding: 50px; text-align: center;">
+            <h1 style="color: #f44336;">❌ Authentication Failed</h1>
+            <p>Check the terminal for error details.</p>
+          </body>
+        </html>
+      `);
+      setTimeout(() => {
+        server.close();
+        process.exit(1);
+      }, 1000);
+    }
+  }
+});
+
+server.listen(3000, () => {
+  console.log('🌐 HTTPS Server started on https://localhost:3000');
+  console.log('\n👉 Open this URL in your browser to start authentication:');
+  console.log('   https://localhost:3000/\n');
+  console.log('⏳ Waiting for authentication...\n');
+
+  // Helpful reminders
+  console.log('💡 Make sure your Yahoo app has this redirect URI configured:');
+  console.log('   https://localhost:3000/callback\n');
+  console.log('⚠️  Your browser will show a security warning (self-signed cert)');
+  console.log('   Click "Advanced" → "Proceed to localhost" to continue\n');
+});