@semanticintent/semantic-chirp-intelligence-mcp 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,113 @@
1
+ /**
2
+ * Tool Metadata Configuration
3
+ *
4
+ * Semantic Anchoring Governance markers for all tools
5
+ */
6
+ export const TOOL_METADATA = {
7
+ get_team_roster: {
8
+ chirp_style: "analytical_assessment",
9
+ discovery_tags: ["roster", "lineup", "players", "status", "team"],
10
+ intent_category: "team_assessment",
11
+ hockey_context: "roster_analysis",
12
+ chirp_potential: "roster_weaknesses"
13
+ },
14
+ get_league_standings: {
15
+ chirp_style: "competitive_reality",
16
+ discovery_tags: ["standings", "league", "competition", "rankings", "position"],
17
+ intent_category: "league_awareness",
18
+ hockey_context: "competitive_landscape",
19
+ chirp_potential: "standings_truth"
20
+ },
21
+ get_current_matchup: {
22
+ chirp_style: "matchup_assessment",
23
+ discovery_tags: ["matchup", "opponent", "week", "competition", "stats"],
24
+ intent_category: "weekly_strategy",
25
+ hockey_context: "head_to_head_battle",
26
+ chirp_potential: "matchup_reality"
27
+ },
28
+ get_games_in_hand: {
29
+ chirp_style: "strategic_advantage",
30
+ discovery_tags: ["schedule", "advantage", "games", "strategy", "matchup"],
31
+ intent_category: "competitive_intelligence",
32
+ hockey_context: "schedule_warfare",
33
+ chirp_potential: "schedule_domination",
34
+ // 🆕 Template Pattern Metadata
35
+ uses_template_pattern: true,
36
+ analysis_class: "GamesInHandAnalysis",
37
+ template_version: "1.0.0",
38
+ analysis_type: "schedule_advantage"
39
+ },
40
+ get_streaming_recommendations: {
41
+ chirp_style: "opportunity_hunter",
42
+ discovery_tags: ["pickups", "waivers", "streaming", "schedule", "trends"],
43
+ intent_category: "acquisition_strategy",
44
+ hockey_context: "waiver_wire_mastery",
45
+ chirp_potential: "pickup_strategy",
46
+ // 🆕 Template Pattern Metadata
47
+ uses_template_pattern: true,
48
+ analysis_class: "StreamingAnalysis",
49
+ template_version: "1.0.0",
50
+ analysis_type: "streaming_strategy"
51
+ },
52
+ get_roster_transaction_recommendations: {
53
+ chirp_style: "ice_cold_truth",
54
+ discovery_tags: ["optimization", "ICE", "championship", "decisions", "transactions"],
55
+ intent_category: "ultimate_advisor",
56
+ hockey_context: "league_domination",
57
+ chirp_potential: "brutal_optimization",
58
+ is_ice_engine: true,
59
+ tool_semantic_identity: "ICE - Intent Chirp Engine",
60
+ // 🆕 Template Pattern Metadata
61
+ uses_template_pattern: true,
62
+ analysis_class: "IceAnalysis",
63
+ template_version: "1.0.0",
64
+ analysis_type: "ice_roster"
65
+ },
66
+ get_weekly_stats: {
67
+ chirp_style: "performance_review",
68
+ discovery_tags: ["stats", "weekly", "performance", "matchup", "analysis"],
69
+ intent_category: "performance_tracking",
70
+ hockey_context: "stat_battle",
71
+ chirp_potential: "weekly_performance"
72
+ },
73
+ compare_matchup: {
74
+ chirp_style: "head_to_head_analysis",
75
+ discovery_tags: ["comparison", "matchup", "opponent", "strategy", "categories"],
76
+ intent_category: "tactical_analysis",
77
+ hockey_context: "category_warfare",
78
+ chirp_potential: "matchup_insights"
79
+ },
80
+ optimize_lineup: {
81
+ chirp_style: "lineup_optimization",
82
+ discovery_tags: ["lineup", "optimization", "active", "bench", "strategy"],
83
+ intent_category: "daily_management",
84
+ hockey_context: "lineup_strategy",
85
+ chirp_potential: "lineup_fixes",
86
+ // 🆕 Template Pattern Metadata
87
+ uses_template_pattern: true,
88
+ analysis_class: "LineupAnalysis",
89
+ template_version: "1.0.0",
90
+ analysis_type: "lineup_optimization"
91
+ },
92
+ search_players: {
93
+ chirp_style: "player_discovery",
94
+ discovery_tags: ["search", "players", "available", "free_agents", "discovery"],
95
+ intent_category: "player_research",
96
+ hockey_context: "talent_scouting",
97
+ chirp_potential: "player_insights"
98
+ },
99
+ get_player_stats: {
100
+ chirp_style: "player_evaluation",
101
+ discovery_tags: ["stats", "player", "performance", "evaluation", "analysis"],
102
+ intent_category: "player_analysis",
103
+ hockey_context: "individual_assessment",
104
+ chirp_potential: "player_reality"
105
+ },
106
+ get_trending_players: {
107
+ chirp_style: "trend_hunting",
108
+ discovery_tags: ["trends", "hot", "cold", "momentum", "pickups"],
109
+ intent_category: "market_intelligence",
110
+ hockey_context: "waiver_trends",
111
+ chirp_potential: "trend_opportunities"
112
+ }
113
+ };
@@ -0,0 +1,322 @@
1
+ /**
2
+ * 🏛️ Semantic Anchoring Governance System
3
+ *
4
+ * This module implements the complete Semantic Anchoring Governance framework
5
+ * across all 5 phases:
6
+ * - Phase 1: Semantic Markers and Tool Identity
7
+ * - Phase 2: Immutability Protection
8
+ * - Phase 3: Semantic Contract Validation
9
+ * - Phase 4: Documentation
10
+ * - Phase 5: Runtime Governance Enforcement
11
+ *
12
+ * Governance Rules:
13
+ * - Rule 1: Semantic Over Structural - Decisions based on semantic properties
14
+ * - Rule 2: Intent Preservation - Semantic intent validated through transformations
15
+ * - Rule 3: Observable Anchoring - Decisions based on observable semantic properties
16
+ * - Rule 4: Immutability Protection - Semantic contracts cannot be mutated
17
+ */
18
+ // ==========================================
19
+ // 📈 Runtime Governance Monitor
20
+ // ==========================================
21
+ /**
22
+ * 🏛️ GOVERNANCE_MONITOR
23
+ *
24
+ * Central monitoring system for all governance enforcement.
25
+ * Tracks violations, contracts, immutability enforcement, and semantic decisions.
26
+ *
27
+ * Enhanced in Template Pattern Migration:
28
+ * - Added analysis execution tracking
29
+ * - Added performance monitoring
30
+ * - Added analysis-specific metrics
31
+ */
32
+ export const GOVERNANCE_MONITOR = {
33
+ // Existing governance metrics (Phases 1-5)
34
+ violations: [],
35
+ contracts_validated: 0,
36
+ immutability_enforced: 0,
37
+ semantic_decisions: 0,
38
+ // 🆕 NEW: Analysis tracking (Template Pattern)
39
+ analyses_executed: 0,
40
+ analysis_by_type: new Map(),
41
+ analysis_durations: [],
42
+ /**
43
+ * Track a governance violation
44
+ * Automatically adds timestamp and maintains violation history
45
+ */
46
+ trackViolation(violation) {
47
+ this.violations.push({
48
+ ...violation,
49
+ timestamp: new Date()
50
+ });
51
+ // Keep only last 100 violations to prevent memory growth
52
+ if (this.violations.length > 100) {
53
+ this.violations = this.violations.slice(-100);
54
+ }
55
+ },
56
+ /**
57
+ * 🆕 Track analysis start
58
+ * Called when template method begins execution
59
+ */
60
+ trackAnalysisStart(type) {
61
+ if (process.env.NODE_ENV === "development") {
62
+ console.log(`[GOVERNANCE] Analysis started: ${type}`);
63
+ }
64
+ },
65
+ /**
66
+ * 🆕 Track analysis completion
67
+ * Records execution time and updates metrics
68
+ */
69
+ trackAnalysisComplete(type, duration_ms) {
70
+ this.analyses_executed++;
71
+ this.analysis_by_type.set(type, (this.analysis_by_type.get(type) || 0) + 1);
72
+ this.analysis_durations.push({
73
+ type,
74
+ duration_ms,
75
+ timestamp: new Date()
76
+ });
77
+ // Keep only last 100 duration records
78
+ if (this.analysis_durations.length > 100) {
79
+ this.analysis_durations = this.analysis_durations.slice(-100);
80
+ }
81
+ if (process.env.NODE_ENV === "development") {
82
+ console.log(`[GOVERNANCE] Analysis completed: ${type} (${duration_ms}ms)`);
83
+ }
84
+ },
85
+ /**
86
+ * Get governance health report
87
+ * Returns comprehensive metrics about system health
88
+ */
89
+ getHealthReport() {
90
+ const warnings = this.violations.filter(v => v.severity === "warning").length;
91
+ const errors = this.violations.filter(v => v.severity === "error").length;
92
+ return {
93
+ total_violations: this.violations.length,
94
+ warnings,
95
+ errors,
96
+ contracts_validated: this.contracts_validated,
97
+ immutability_enforced: this.immutability_enforced,
98
+ semantic_decisions: this.semantic_decisions,
99
+ recent_violations: this.violations.slice(-10), // Last 10 violations
100
+ // 🆕 Analysis metrics
101
+ analyses_executed: this.analyses_executed,
102
+ analysis_by_type: Object.fromEntries(this.analysis_by_type),
103
+ avg_duration_ms: this.calculateAverageDuration(),
104
+ slowest_analysis: this.getSlowestAnalysis()
105
+ };
106
+ },
107
+ /**
108
+ * 🆕 Calculate average analysis duration
109
+ */
110
+ calculateAverageDuration() {
111
+ if (this.analysis_durations.length === 0)
112
+ return 0;
113
+ const total = this.analysis_durations.reduce((sum, d) => sum + d.duration_ms, 0);
114
+ return Math.round(total / this.analysis_durations.length);
115
+ },
116
+ /**
117
+ * 🆕 Get slowest analysis from recent executions
118
+ */
119
+ getSlowestAnalysis() {
120
+ if (this.analysis_durations.length === 0)
121
+ return null;
122
+ return this.analysis_durations.reduce((slowest, current) => current.duration_ms > slowest.duration_ms ? current : slowest);
123
+ },
124
+ /**
125
+ * Reset monitoring counters (for testing)
126
+ */
127
+ reset() {
128
+ this.violations = [];
129
+ this.contracts_validated = 0;
130
+ this.immutability_enforced = 0;
131
+ this.semantic_decisions = 0;
132
+ this.analyses_executed = 0;
133
+ this.analysis_by_type.clear();
134
+ this.analysis_durations = [];
135
+ }
136
+ };
137
+ // ==========================================
138
+ // 🔍 Semantic Contract Audit Logger
139
+ // ==========================================
140
+ /**
141
+ * Audit semantic contract operations
142
+ * Logs contract state during validation, enforcement, and decisions
143
+ *
144
+ * @param contract - The semantic contract being audited
145
+ * @param toolName - Name of the tool processing the contract
146
+ * @param phase - Which phase of processing (validation, enforcement, decision)
147
+ */
148
+ export function auditSemanticContract(contract, toolName, phase) {
149
+ const audit = {
150
+ phase,
151
+ tool_name: toolName,
152
+ semantic_intent: contract.semantic_intent,
153
+ enable_chirp: contract.enable_chirp,
154
+ chirp_intensity: contract.chirp_intensity,
155
+ personality_mode: contract.personality_mode,
156
+ tool_context: contract.tool_context,
157
+ timestamp: new Date().toISOString()
158
+ };
159
+ // Log to console in development mode
160
+ if (process.env.NODE_ENV === "development") {
161
+ console.log(`🔍 Semantic Audit [${phase}]:`, JSON.stringify(audit, null, 2));
162
+ }
163
+ // Update monitoring counters
164
+ if (phase === "validation") {
165
+ GOVERNANCE_MONITOR.contracts_validated++;
166
+ }
167
+ else if (phase === "enforcement") {
168
+ GOVERNANCE_MONITOR.immutability_enforced++;
169
+ }
170
+ else if (phase === "decision") {
171
+ GOVERNANCE_MONITOR.semantic_decisions++;
172
+ }
173
+ }
174
+ // ==========================================
175
+ // 🏥 Governance Health Check
176
+ // ==========================================
177
+ /**
178
+ * Check governance system health
179
+ * Returns status and actionable recommendations
180
+ */
181
+ export function checkGovernanceHealth() {
182
+ const report = GOVERNANCE_MONITOR.getHealthReport();
183
+ const recommendations = [];
184
+ let status = "healthy";
185
+ // Check error rate
186
+ if (report.errors > 10) {
187
+ status = "critical";
188
+ recommendations.push("Critical: High error rate detected. Review recent violations immediately.");
189
+ }
190
+ else if (report.errors > 0) {
191
+ status = "degraded";
192
+ recommendations.push("Warning: Governance errors detected. Review violation logs.");
193
+ }
194
+ // Check warning rate
195
+ if (report.warnings > 20) {
196
+ if (status !== "critical")
197
+ status = "degraded";
198
+ recommendations.push("Warning: High warning rate. Review semantic contract usage patterns.");
199
+ }
200
+ // Check validation rate
201
+ if (report.contracts_validated === 0) {
202
+ recommendations.push("Info: No contracts validated yet. System may not be processing requests.");
203
+ }
204
+ // 🆕 Check analysis performance
205
+ if (report.avg_duration_ms > 5000) {
206
+ if (status !== "critical")
207
+ status = "degraded";
208
+ recommendations.push(`Performance: Average analysis duration is ${report.avg_duration_ms}ms (threshold: 5000ms)`);
209
+ }
210
+ if (recommendations.length === 0) {
211
+ recommendations.push("System is operating within governance parameters.");
212
+ }
213
+ return { status, report, recommendations };
214
+ }
215
+ // ==========================================
216
+ // 📚 Semantic Contract Validation
217
+ // ==========================================
218
+ /**
219
+ * 🏛️ validateSemanticChirpContract Function:
220
+ * Enforces Semantic Anchoring Governance Rule 2 (Intent Preservation) by validating
221
+ * that semantic intent is preserved through chirp parameter transformations.
222
+ *
223
+ * Purpose:
224
+ * Ensures that chirp parameters maintain semantic coherence and prevents accidental
225
+ * or malicious violations of user intent.
226
+ *
227
+ * Governance Principles:
228
+ * - User intent has highest priority and must never be overridden
229
+ * - System defaults should be semantically consistent
230
+ * - Tool-specific overrides must be confined to their tool context
231
+ * - Conflicting intentions should be detected and reported
232
+ *
233
+ * Validation Cases:
234
+ *
235
+ * Case 1: User-Requested Disable
236
+ * Scenario: User explicitly sets enable_chirp=false with semantic_intent="user_requested"
237
+ * Action: Allow and preserve user intent (highest priority)
238
+ * Governance: Protects user autonomy and semantic control
239
+ *
240
+ * Case 2: Default Behavior
241
+ * Scenario: enable_chirp is undefined or true (system default)
242
+ * Action: Allow as valid default semantic behavior
243
+ * Governance: System defaults are semantically consistent
244
+ *
245
+ * Case 3: Ice Cold Intensity Validation
246
+ * Scenario: chirp_intensity="ice_cold" without explicit semantic intent
247
+ * Action: Warn if used on non-ICE tools (may be accidental)
248
+ * Governance: Prevents unintentional semantic shifts in tool behavior
249
+ * Rationale: ice_cold is semantically strong and should be intentional
250
+ *
251
+ * Case 4: Conflicting Intent Detection
252
+ * Scenario: enable_chirp=false but chirp_intensity is specified
253
+ * Action: Log warning about semantic contradiction
254
+ * Governance: Detects semantic incoherence in parameters
255
+ * Rationale: Disabled chirp with intensity setting is semantically inconsistent
256
+ *
257
+ * Case 5: Tool Override Protection
258
+ * Scenario: semantic_intent="tool_override" with mismatched tool_context
259
+ * Action: Throw error (strict enforcement)
260
+ * Governance: Prevents semantic contract violations across tool boundaries
261
+ * Rationale: Tool overrides must stay within their semantic domain
262
+ *
263
+ * @param contract - The semantic contract to validate
264
+ * @param toolName - Name of the tool requesting validation
265
+ * @param toolMetadata - Optional tool metadata for semantic property checks
266
+ */
267
+ export function validateSemanticChirpContract(contract, toolName, toolMetadata) {
268
+ // 🔍 Phase 5: Audit contract validation
269
+ auditSemanticContract(contract, toolName, "validation");
270
+ // Rule 2: Intent Preservation - validate semantic coherence
271
+ // Case 1: User explicitly disabled chirp - valid semantic intent
272
+ if (contract.enable_chirp === false && contract.semantic_intent === "user_requested") {
273
+ return; // Valid: User intent to disable is preserved
274
+ }
275
+ // Case 2: Default behavior - chirp enabled unless explicitly disabled
276
+ if (contract.enable_chirp === undefined || contract.enable_chirp === true) {
277
+ // This is valid default behavior
278
+ return;
279
+ }
280
+ // Case 3: ice_cold intensity should be intentional, not accidental
281
+ if (contract.chirp_intensity === "ice_cold" && !contract.semantic_intent) {
282
+ // Log warning but allow (ICE tool deliberately uses ice_cold as default)
283
+ if (toolMetadata && !toolMetadata.is_ice_engine) {
284
+ const warning = `ice_cold intensity without explicit intent on non-ICE tool '${toolName}'`;
285
+ console.error(`⚠️ Semantic Warning: ${warning}`);
286
+ // 📊 Phase 5: Track governance violation
287
+ GOVERNANCE_MONITOR.trackViolation({
288
+ rule: "Rule 2 - Intent Preservation",
289
+ severity: "warning",
290
+ tool_name: toolName,
291
+ violation_type: "unintentional_intensity",
292
+ details: warning
293
+ });
294
+ }
295
+ }
296
+ // Case 4: Detect conflicting semantic intentions
297
+ if (contract.enable_chirp === false && contract.chirp_intensity) {
298
+ const warning = `Conflicting intent - chirp disabled but intensity specified for '${toolName}'`;
299
+ console.error(`⚠️ Semantic Warning: ${warning}`);
300
+ // 📊 Phase 5: Track governance violation
301
+ GOVERNANCE_MONITOR.trackViolation({
302
+ rule: "Rule 2 - Intent Preservation",
303
+ severity: "warning",
304
+ tool_name: toolName,
305
+ violation_type: "conflicting_intent",
306
+ details: warning
307
+ });
308
+ }
309
+ // Case 5: Tool override should only be used by system, not user input
310
+ if (contract.semantic_intent === "tool_override" && contract.tool_context !== toolName) {
311
+ const error = `tool_override intent mismatch for '${toolName}' - expected context '${toolName}', got '${contract.tool_context}'`;
312
+ // 📊 Phase 5: Track governance violation
313
+ GOVERNANCE_MONITOR.trackViolation({
314
+ rule: "Rule 2 - Intent Preservation",
315
+ severity: "error",
316
+ tool_name: toolName,
317
+ violation_type: "tool_override_mismatch",
318
+ details: error
319
+ });
320
+ throw new Error(`🚨 Semantic contract violation: ${error}`);
321
+ }
322
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * 🏛️ Domain Types - Semantic Chirp Intelligence MCP
3
+ *
4
+ * This file contains all core type definitions and interfaces for the
5
+ * Yahoo Fantasy MCP with Template Method Pattern implementation.
6
+ *
7
+ * Organized by domain:
8
+ * - Analysis Types
9
+ * - Chirp Intelligence
10
+ * - Yahoo API Data
11
+ * - Recommendations
12
+ * - Responses
13
+ */
14
+ export {};
@@ -0,0 +1,188 @@
1
+ /**
2
+ * Semantic Breakout Tool Integration
3
+ *
4
+ * Implements breakout player analysis using semantic intent pattern.
5
+ * This tool uses natural language intent to auto-configure the MCP tool.
6
+ */
7
+ import { SemanticIntentParser } from './semantic-intent-parser.js';
8
+ /**
9
+ * Semantic tool definition for breakout player analysis
10
+ *
11
+ * This comprehensive prompt integrates:
12
+ * - Data-driven predictability (40% recent, 30% projections, 20% opportunity, 10% risk)
13
+ * - External source references (Rotowire, NHL EDGE, DobberHockey)
14
+ * - Position-specific filtering
15
+ * - League context awareness
16
+ */
17
+ export const SEMANTIC_BREAKOUT_ANALYSIS = {
18
+ name: "analyze_breakout_players",
19
+ description: "Analyze free agents to identify top pickups and breakout candidates using comprehensive data-driven scoring",
20
+ semanticIntent: `
21
+ I analyze free agents in Yahoo Fantasy Hockey to recommend top 5-10 pickups and 3-5 breakout candidates.
22
+ I use a predictable scoring formula: 40% recent performance + 30% projections + 20% opportunity - 10% risk.
23
+ I focus on players under 50% owned and provide position-specific analysis.
24
+
25
+ I need: position filter (optional array of strings like ["C", "RW"]),
26
+ ownership threshold (optional number, default 50),
27
+ breakout age max (optional number, default 26),
28
+ minimum score (optional number, default 0),
29
+ max results (optional number, default 10),
30
+ chirp intensity (optional string),
31
+ personality mode (optional string),
32
+ enable chirp (optional boolean)
33
+
34
+ I will: Yahoo API calls, statistical analysis, trend detection, opportunity scoring, risk assessment
35
+
36
+ I return: Top pickups with scores, breakout candidates, position breakdown, market intelligence
37
+
38
+ I estimate: moderate complexity, 3000 tokens
39
+ `
40
+ };
41
+ /**
42
+ * Parse semantic intent for breakout analysis
43
+ */
44
+ export function parseBreakoutAnalysisIntent() {
45
+ const parser = new SemanticIntentParser();
46
+ return parser.parseIntent(SEMANTIC_BREAKOUT_ANALYSIS.semanticIntent);
47
+ }
48
+ /**
49
+ * Get MCP input schema from semantic intent
50
+ */
51
+ export function getBreakoutAnalysisInputSchema() {
52
+ const parsed = parseBreakoutAnalysisIntent();
53
+ // Build schema from parsed parameters
54
+ const properties = {};
55
+ const required = [];
56
+ for (const param of parsed.parameters) {
57
+ properties[param.name] = {
58
+ type: param.type,
59
+ description: param.description
60
+ };
61
+ if (param.required) {
62
+ required.push(param.name);
63
+ }
64
+ }
65
+ // Add enum constraints for specific parameters
66
+ if (properties.chirp_intensity) {
67
+ properties.chirp_intensity.enum = ['gentle', 'standard', 'savage', 'ice_cold'];
68
+ }
69
+ if (properties.personality_mode) {
70
+ properties.personality_mode.enum = ['analytical', 'motivational', 'roast_master', 'championship_coach'];
71
+ }
72
+ if (properties.position_filter) {
73
+ properties.position_filter.items = { type: 'string' };
74
+ }
75
+ return {
76
+ type: "object",
77
+ properties,
78
+ required: required.length > 0 ? required : undefined
79
+ };
80
+ }
81
+ /**
82
+ * Execute breakout analysis with semantic configuration
83
+ */
84
+ export async function executeBreakoutAnalysis(args, breakoutAnalysis) {
85
+ const parsed = parseBreakoutAnalysisIntent();
86
+ // Build semantic contract
87
+ const semanticContract = {
88
+ chirp_intensity: args.chirp_intensity || 'standard',
89
+ personality_mode: args.personality_mode || 'analytical',
90
+ enable_chirp: args.enable_chirp !== false,
91
+ semantic_intent: 'user_requested',
92
+ tool_context: 'analyze_breakout_players'
93
+ };
94
+ // Build analysis args
95
+ const analysisArgs = {
96
+ position_filter: args.position_filter,
97
+ ownership_threshold: args.ownership_threshold,
98
+ breakout_age_max: args.breakout_age_max,
99
+ min_score: args.min_score,
100
+ max_results: args.max_results
101
+ };
102
+ try {
103
+ // Execute analysis using template pattern
104
+ const result = await breakoutAnalysis.executeAnalysis(analysisArgs, semanticContract);
105
+ // Enhance with semantic metadata
106
+ return {
107
+ ...result,
108
+ _semantic_metadata: {
109
+ tool_name: SEMANTIC_BREAKOUT_ANALYSIS.name,
110
+ parsed_capabilities: parsed.capabilities,
111
+ parse_confidence: `${(parsed.confidence * 100).toFixed(0)}%`,
112
+ message: '✅ Tool auto-configured from semantic intent!',
113
+ prompt_integration: {
114
+ scoring_formula: '40% recent + 30% projections + 20% opportunity - 10% risk',
115
+ external_sources: 'Ready for: Rotowire, NHL EDGE, DobberHockey integration',
116
+ data_driven: 'Predictable rankings with confidence scores'
117
+ }
118
+ }
119
+ };
120
+ }
121
+ catch (error) {
122
+ throw new Error(`Breakout analysis failed: ${error instanceof Error ? error.message : String(error)}`);
123
+ }
124
+ }
125
+ /**
126
+ * Improved prompt recommendations for Claude Desktop integration
127
+ */
128
+ export const BREAKOUT_PROMPT_IMPROVEMENTS = {
129
+ semantic_clarity: {
130
+ original: "Complex multi-paragraph template with embedded formulas",
131
+ improved: "Structured semantic intent with clear I need/I will/I return sections",
132
+ benefit: "Claude Desktop can better understand tool purpose and auto-suggest when user asks about breakouts"
133
+ },
134
+ parameter_discovery: {
135
+ original: "Parameters embedded in prose",
136
+ improved: "Explicit parameter definitions with types and optionality",
137
+ benefit: "MCP can auto-generate input schema, reducing manual configuration"
138
+ },
139
+ capability_mapping: {
140
+ original: "References to external sources without integration plan",
141
+ improved: "Capability tags (yahoo_api, data_analysis) that map to available functions",
142
+ benefit: "Tool knows what it can and cannot do, preventing hallucination"
143
+ },
144
+ predictability_enhancement: {
145
+ original: "Scoring formula mentioned in prose",
146
+ improved: "Formula implemented in code with observable weights",
147
+ benefit: "Consistent, repeatable results that users can trust"
148
+ },
149
+ integration_points: {
150
+ yahoo_api: "Direct integration via YahooApiClient",
151
+ rotowire: "Placeholder for future web scraping capability",
152
+ nhl_edge: "Placeholder for NHL API integration",
153
+ dobber_hockey: "Placeholder for prospect data integration"
154
+ },
155
+ usage_with_claude_desktop: `
156
+ When user asks: "tell me about breakout players" or "who should I pick up?"
157
+
158
+ Claude Desktop will:
159
+ 1. Recognize semantic intent matches analyze_breakout_players tool
160
+ 2. Auto-extract parameters from conversation context (league format, roster needs)
161
+ 3. Call tool with appropriate chirp settings (analytical by default)
162
+ 4. Present results in conversational format with player tables and reasoning
163
+
164
+ Example interaction:
165
+ User: "I need a right wing, who are the best breakout candidates?"
166
+
167
+ Claude: *uses analyze_breakout_players with position_filter=["RW"]*
168
+
169
+ "Based on data-driven analysis, here are the top RW breakout candidates:
170
+
171
+ 🏒 Must-Adds (Score 80+):
172
+ 1. [Player Name] (Team) - 85 score
173
+ - Catalyst: Top-6 center opportunity
174
+ - Recent: 0.9 PPG | Projected: 0.7 FPG
175
+ - Risk: Low (15%)
176
+ - Confidence: High
177
+
178
+ 2. [Player Name] (Team) - 82 score
179
+ ...
180
+
181
+ 📊 Position Analysis:
182
+ - RW pool strength: 15 candidates with 65+ scores
183
+ - Market trend: RW pickups trending up 23%
184
+ - Recommendation: Act fast on must-adds
185
+
186
+ 💡 Next steps: Should I analyze your roster to see who you could drop?"
187
+ `
188
+ };