chesscom-mxcp

# Chess MXCP Server An enterprise-grade Chess.com MCP server built with MXCP, featuring caching, analytics, audit trails, and advanced data analysis capabilities. ## Features ### 🚀 Core Chess.com API Integration - **Player Tools**: Profile, stats, online status, current games, game archives - **Game Tools**: Monthly games, PGN downloads with caching - **Titled Players**: List players by title (GM, IM, FM, etc.) - **Club Tools**: Club profiles and member lists ### 💎 Enterprise Features (MXCP Advantages) - **Smart Caching**: Configurable TTLs for different data types - **Rate Limiting**: Token bucket algorithm to respect API limits - **Connection Pooling**: Efficient HTTP client with keepalive - **Retry Logic**: Automatic retries with exponential backoff - **Audit Trails**: Track all API usage and queries - **Error Handling**: Graceful degradation and detailed error messages ### 📊 Advanced Analytics (Not Available in Original) - **Rating Trends**: Analyze player rating changes over time - **Game Analysis**: Win/loss/draw patterns by time control and color - **Opening Statistics**: Most played openings and success rates - **Activity Patterns**: When players are most active - **Trending Players**: Track popular players and follower growth - **SQL Query Access**: Direct SQL access to cached data for custom analysis ### 🔐 Security & Governance - **Authentication Support**: OAuth integration ready - **Audit Logging**: Complete API call tracking - **Policy Engine**: Fine-grained access control - **Type Safety**: Comprehensive validation ## Installation 1. Install dependencies: ```bash pip install httpx ``` 2. Initialize the database: ```bash mxcp run tool get_player_profile --param username=hikaru ``` This will create the necessary cache tables automatically. ## Usage ### Start the Server ```bash mxcp serve ``` ### Connect to Claude Desktop The `server_config.json` was generated during `mxcp init`. Add it to your Claude Desktop configuration. ### Example Queries Ask Claude: - "Get Magnus Carlsen's profile and analyze his rating trends" - "Show me all GMs and their recent activity" - "Analyze my opening repertoire" (after fetching games) - "Compare win rates between blitz and rapid for a player" - "Find trending chess players this week" ### SQL Analytics With SQL tools enabled, you can run custom queries: - "Show me all cached games where I played the Sicilian Defense" - "What's my performance on Tuesdays vs other days?" - "List all players whose ratings improved by 100+ points" ## Configuration Edit `mxcp-site.yml` to adjust: - Cache TTLs for different data types - Rate limiting parameters - Audit settings - SQL tool permissions ## Architecture ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Chess.com │ │ MXCP Server │ │ DuckDB Cache │ │ API │◄────│ - Rate Limiter │────►│ - API Cache │ │ │ │ - Retry Logic │ │ - Game Archive │ └─────────────────┘ │ - Type Safety │ │ - Analytics │ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ LLM Client │ │ (Claude, etc) │ └──────────────────┘ ``` ## Advanced Features ### Caching Strategy - Player profiles: 1 hour TTL - Player stats: 30 minutes TTL - Current games: 5 minutes TTL - Game archives: 24 hours TTL (historical data) - Titled players: 7 days TTL - Individual games: Permanent cache ### Analytics Tables - `chess_api_cache`: General API response cache - `chess_games_cache`: Individual game storage with PGN - `player_profile_views`: Track profile access patterns - `rating_history`: Player rating changes over time - `player_activity`: Game count tracking - `audit_log`: Complete API usage audit trail ## Development ### Adding New Tools 1. Create Python implementation in `python/` 2. Define tool in `tools/` with YAML 3. Add SQL analytics if applicable 4. Update cache tables if needed ### Testing ```bash # Test a specific tool mxcp run tool get_player_profile --param username=hikaru # Validate all tools mxcp validate # Check for drift mxcp drift check ``` ## Why MXCP? This implementation showcases how MXCP improves upon a basic MCP server: 1. **Performance**: Caching reduces API calls by 90%+ 2. **Analytics**: SQL access enables complex analysis impossible with just API 3. **Reliability**: Retry logic and rate limiting prevent failures 4. **Observability**: Audit trails show exactly what's happening 5. **Extensibility**: Easy to add new analytics without touching core code 6. **Type Safety**: Validation prevents runtime errors 7. **Production Ready**: Built for scale from day one ## License MIT