Sipap Intelligence

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

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: [email protected]