sipap-intelligence-mcp

AI-Powered Intelligence MCP Server for Valo - Aggregating intelligence from news sentiment, weather analysis, and API-Football predictions using Claude (Bedrock).

Overview

This MCP server provides AI-powered intelligence tools that enhance sports predictions with:

• Weather Intelligence: Real-time weather forecasts and AI-assessed impact on matches

• News Sentiment Analysis: Claude-powered analysis of recent news for teams

• Injury Impact Assessment: AI-driven evaluation of injury impact on performance

• API-Football Intelligence: Algorithmic predictions, player availability, and transfers

• Historical Performance Analysis: Team performance patterns in specific conditions

Related MCP server: beast-baseball

Architecture

Unlike sipap-data-mcp (database reads only), this MCP server:

• Makes on-demand API calls (OpenWeatherMap, NewsAPI, API-Football)

• Uses Claude via AWS Bedrock for AI analysis

• Has higher latency (<2s vs <100ms) due to AI processing + API calls

• Implements differential TTL caching strategy (1h-24h) to minimize API costs

• Follows Sentinel patterns: #19 (Lambda warm start), #20 (Cache-aside)

Tools (9 Total)

Weather Intelligence (3 tools)

1. get_match_weather(match_id: str, lat?: float, lon?: float, city?: str)

   • Fetches weather forecast for match time and location

   • Source: OpenWeatherMap API

   • Returns: Temperature, precipitation, wind, visibility, humidity

   • Cache TTL: 1 hour

   • Accepts: Coordinates (lat/lon) OR city name

2. assess_weather_impact(weather_conditions: dict, match_type?: str, home_team?: str, away_team?: str)

   • AI analysis of weather impact on match outcome

   • Uses: Claude via Bedrock

   • Returns: Impact level, confidence, factors, betting implications

   • Cache TTL: 6 hours

   • Optional team context for tactical analysis

3. get_historical_weather_performance(team_id: str, team_name: str, weather_type: str, max_matches?: int)

   • Analyzes team's historical performance in specific weather

   • Uses: Mock historical data + Claude analysis

   • Returns: Pattern strength, confidence, win rate, goal stats, insights

   • Cache TTL: 24 hours

News Intelligence (2 tools)

4. fetch_and_analyze_team_news(team_id: str, team_name: str, days_back?: int)

   • Fetches recent news and performs sentiment analysis

   • Uses: NewsAPI + Claude

   • Returns: Sentiment, confidence, key topics, impact summary, articles analyzed

   • Cache TTL: 6 hours

   • Default: 7 days back, top 5 sources

5. get_injury_reports(team_id: str, team_name: str, severity_filter?: str)

   • Injury reports with AI-powered impact assessment

   • Uses: Mock injury data + Claude

   • Returns: Injuries with AI-assessed impact scores

   • Cache TTL: 24 hours

   • Filters: "all", "major", "minor"

API-Football Intelligence (4 tools)

6. get_match_predictions(fixture_id: int)

   • Algorithmic match predictions from API-Football

   • Source: API-Football predictions endpoint (poisson, stats, form)

   • Returns: Winner prediction, probabilities (home/draw/away), league/teams info

   • Cache TTL: 6 hours

7. get_sidelined_players(player_id?: int, coach_id?: int)

   • Player/coach availability (injuries, suspensions, absences)

   • Source: API-Football sidelined endpoint

   • Returns: Type, player/coach info, start date, end date

   • Cache TTL: 24 hours

   • Mutually exclusive: provide player_id OR coach_id

8. get_player_transfers(player_id?: int, team_id?: int)

   • Player transfer history and context

   • Source: API-Football transfers endpoint

   • Returns: Transfer details, teams, dates, type

   • Cache TTL: 24 hours

   • Optional filters: player_id, team_id

9. get_available_timezones()

   • Available timezones for fixture scheduling

   • Source: API-Football timezones endpoint

   • Returns: List of valid timezone identifiers

   • Cache TTL: 7 days (static data)

Installation

# Install from wheel
pip install sipap_intelligence_mcp-0.1.0-py3-none-any.whl

# Or install in editable mode for development
cd sipap-intelligence-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Requirements

• Python 3.12, 3.13, or 3.14

• AWS credentials with Bedrock access (Claude)

• OpenWeatherMap API key (free tier: 60 calls/min)

• NewsAPI key (free tier: 100 requests/day)

• API-Football key (Ultra plan: 75,000 requests/day)

• sipap-common >= 0.1.0

• sipap-mcp >= 0.1.0

• Redis instance (AWS ElastiCache or local)

Usage

Direct Tool Usage

from sipap_intelligence_mcp.tools.weather import get_match_weather, assess_weather_impact

# Get weather forecast for match
weather = await get_match_weather(match_id="match-123")
# Returns: {
#     'temperature': 15.2,
#     'precipitation': 'light_rain',
#     'wind_speed': 12.5,
#     'visibility': 8000
# }

# Assess impact on match
impact = await assess_weather_impact(weather, match_type="soccer")
# Returns: {
#     'impact_level': 'medium',
#     'factors': ['Light rain favors defensive play', 'Wind affects long passes'],
#     'betting_implications': 'Consider under 2.5 goals',
#     'confidence': 0.78
# }

MCP Protocol Usage (JSON-RPC 2.0)

from sipap_intelligence_mcp.server import IntelligenceMCPServer

# Initialize MCP server
server = IntelligenceMCPServer()

# List available tools
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
}
response = await server.handle_request(request)
# Returns list of 9 tools with JSON schemas

# Call a weather tool
request = {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "get_match_weather",
        "arguments": {
            "match_id": "match-123",
            "lat": 51.5,
            "lon": -0.1
        }
    }
}
response = await server.handle_request(request)

# Call an API-Football tool
request = {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "get_match_predictions",
        "arguments": {
            "fixture_id": 198772
        }
    }
}
response = await server.handle_request(request)

Configuration

Environment Variables

# AWS Bedrock (required for AI analysis)
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=anthropic.claude-3-haiku-20240307-v1:0

# OpenWeatherMap API (required for weather intelligence)
OPENWEATHER_API_KEY=your_api_key_here

# NewsAPI (required for news intelligence)
NEWS_API_KEY=your_api_key_here

# API-Football (required for predictions/transfers/sidelined)
API_FOOTBALL_KEY=your_api_key_here

# Redis cache (required for all tools)
REDIS_ENDPOINT=sipap-dev-cache.cache.amazonaws.com:6379

# Database (optional, for historical analysis)
DB_ENDPOINT=sipap-dev-aurora.cluster-xxx.us-east-1.rds.amazonaws.com
DB_NAME=sipap_dev
DB_USER=sipap_admin
DB_PASSWORD=stored_in_secrets_manager

Testing

Quality Gates Status

✅ Tests: 130/130 passing (72% coverage)

• Unit tests: 112 (weather: 17, news: 21, API-Football: 36, clients: 38)

• Integration tests: 18 (MCP server: 8, workflows: 10)

✅ Type Checking: Zero mypy errors (strict mode)

✅ Linting: Zero ruff errors

✅ Imports: All successful

Coverage Breakdown

• Weather tools: 92% coverage

• News tools: 89% coverage

• API-Football tools: 95% coverage

• MCP server: 83% coverage

• Claude client: 99% coverage

• Prompts: 100% coverage

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/sipap_intelligence_mcp --cov-report=html

# Run specific test suites
pytest tests/unit/           # Unit tests only
pytest tests/integration/    # Integration tests only

# Run type checking
mypy src/sipap_intelligence_mcp --strict

# Run linting
ruff check src/ tests/

# Run all quality gates
pytest && mypy src/sipap_intelligence_mcp --strict && ruff check src/ tests/

Performance

• Latency: <2s average (AI processing + API calls overhead)

• Cache Hit Rate: 85%+ target (differential TTL strategy)

• Cost: ~$15/month (Claude analysis + API calls)

• Rate Limits:

  • OpenWeatherMap: 60 calls/min (free tier)

  • NewsAPI: 100 requests/day (free tier)

  • API-Football: 75,000 requests/day (Ultra plan)

  • Claude/Bedrock: Pay-as-you-go (~$0.01 per analysis)

• Caching Strategy:

  • Weather: 1 hour (volatile)

  • Weather impact: 6 hours (semi-stable)

  • Historical performance: 24 hours (stable)

  • News sentiment: 6 hours (semi-stable)

  • Injury reports: 24 hours (stable)

  • Predictions: 6 hours (semi-stable)

  • Sidelined/Transfers: 24 hours (stable)

  • Timezones: 7 days (static)

Architecture Patterns

Sentinel Pattern Adoption

• Pattern #9: Structured output enforcement (JSON Schema for AI responses)

• Pattern #19: Lambda warm start optimization (global variables for API clients)

• Pattern #20: Cache-aside with TTL strategy (6h-24h based on volatility)

AI Integration

• Claude Haiku: Fast, cost-effective for simple analyses (<$0.003 per call)

• Claude Sonnet: Complex reasoning for injury impact (<$0.015 per call)

• Prompt Engineering: Sport-specific prompts optimized for accuracy

• Structured Output: Force JSON schema to eliminate parsing errors

Examples

See examples/ directory for:

1. weather_intelligence.py - Weather forecast + impact assessment + historical performance

2. news_intelligence.py - News sentiment analysis + injury reports

3. api_football_intelligence.py - Match predictions + sidelined players + transfers

4. mcp_client.py - Full MCP protocol usage with all 9 tools

5. README.md - Setup instructions and usage guide

Development

# Setup development environment
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

# Run quality gates before committing
pytest && mypy src/sipap_intelligence_mcp --strict && ruff check src/ tests/

License

MIT License - See LICENSE file for details

Support

For issues or questions: charles@sipap.com