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:

pip install httpx

2. Initialize the database:

mxcp run tool get_player_profile --param username=hikaru

This will create the necessary cache tables automatically.

Usage

Start the Server

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

# 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