Topdeck Tournament MCP

An MCP server that provides AI assistants with tools to interact with Topdeck.gg tournament data.

What This MCP Does

This MCP bridges the gap between AI assistants and tournament data, enabling:

For Tournament Organizers:

• Search and analyze tournament trends
• Get detailed tournament information
• Monitor standings and player performance
• Analyze meta game trends

For Players & Analysts:

• Research tournament results
• Analyze deck performance
• Track player statistics
• Study meta game evolution

Architecture Explained

1. Type Definitions (src/types.ts)

Defines the data structures that mirror Topdeck.gg's API responses. This gives us type safety and makes the code self-documenting.

2. API Client (src/topdeck-client.ts)

Handles all HTTP communication with Topdeck.gg. Includes:

• Authentication management
• Error handling
• Request/response transformation
• Rate limiting awareness

3. MCP Server (src/index.ts)

The main server that:

• Registers tools that AI assistants can use
• Translates tool calls into API requests
• Formats responses for AI consumption
• Handles errors gracefully

Tools Provided

Tournament Management

1. search_tournaments - Find tournaments with filtering
2. get_tournament_details - Detailed tournament information
3. get_tournament_standings - Current tournament rankings
4. get_player_details - Individual player performance

Deck Analysis & Meta Tools

5. analyze_tournament_meta - Basic meta game analysis
6. get_tournament_decks - Pull all deck information from a tournament
7. get_decks_by_archetype - Filter decks by specific archetype
8. get_meta_breakdown - Comprehensive meta analysis with win rates and trends

Discovery Tools (No IDs Required!)

9. discover_recent_tournaments - Find recent tournaments without knowing IDs
10. find_tournament_by_name - Search tournaments by name or partial name
11. get_latest_tournament_for_format - Get most recent tournament for specific format
12. find_player_across_tournaments - Find players by name across multiple tournaments

Setup

1. Get a Topdeck.gg API key (free at topdeck.gg/docs)
2. Set environment variable: export TOPDECK_API_KEY=your_key_here
3. Install dependencies: npm install
4. Build: npm run build
5. Run: npm start

Usage Examples

Natural Language Queries (Perfect for UIs & Chatbots!)

"Show me recent Magic tournaments"
"Find the latest Standard tournament"
"What decks are winning in Modern lately?"
"Search for player 'Reid Duke' across recent tournaments"
"Get meta breakdown for the most recent Pro Tour"
"Find all Control decks from the latest Legacy tournament"

Before vs After: UI/Chatbot Integration

Before (Hard to Use):

User: "What decks won the recent Pro Tour?"
Bot: "I need the tournament ID (TID). Please find it first."
User: 😤 *gives up*

After (User-Friendly):

User: "What decks won the recent Pro Tour?"
Bot: *Uses discover_recent_tournaments + get_meta_breakdown*
Bot: "Found Pro Tour Vegas! Control decks dominated with 35% of the meta..."
User: 😍 *continues conversation*

Building UIs & Chatbots

This MCP is designed for easy integration:

For Web UIs:

// Natural language to tournament data
const response = await mcpClient.callTool('discover_recent_tournaments', {
  game: 'Magic: The Gathering',
  format: 'Standard'
});
// Returns user-friendly tournament list with TIDs for deeper analysis

For Chatbots:

// User says: "What's the meta like in Standard?"
// 1. discover_recent_tournaments (game: Magic, format: Standard)
// 2. get_meta_breakdown (using TID from step 1)  
// 3. Return natural language summary

Key Features for Developers:

• No upfront ID knowledge required
• Human-readable responses
• Progressive disclosure (summary → details)
• Error handling for missing data
• Natural language friendly tool names

Learning Notes

Why MCPs Matter:

• They extend AI capabilities with real-time data
• They provide structured ways to interact with external services
• They make complex APIs accessible through natural language

Key MCP Concepts:

• Tools: Functions the AI can call
• Resources: Data the AI can access
• Transport: How the AI communicates with the MCP

Design Decisions:

• Used TypeScript for better developer experience
• Separated API client from MCP server for modularity
• Included meta analysis tools for deeper insights
• Built with tournament organizers and analysts in mind