Scryfall MCP Server

Instructions

Implementation Reference

• src/tools/batch-card-analysis.ts:7-515 (handler)

  Complete handler implementation in BatchCardAnalysisTool class with execute method and all analysis logic
  export class BatchCardAnalysisTool { readonly name = 'batch_card_analysis'; readonly description = 'Analyze multiple cards for legality, prices, synergies, or deck composition'; readonly inputSchema = { type: 'object' as const, properties: { card_list: { type: 'array', items: { type: 'string' }, description: 'List of card names to analyze', minItems: 1, maxItems: 100 }, analysis_type: { type: 'string', enum: ['legality', 'prices', 'synergy', 'composition', 'comprehensive'], description: 'Type of analysis to perform' }, format: { type: 'string', enum: ['standard', 'modern', 'legacy', 'vintage', 'commander', 'pioneer'], description: 'Format for legality analysis' }, currency: { type: 'string', enum: ['usd', 'eur', 'tix'], default: 'usd', description: 'Currency for price analysis' }, include_suggestions: { type: 'boolean', default: false, description: 'Include improvement suggestions' }, group_by: { type: 'string', enum: ['type', 'cmc', 'color', 'rarity', 'price_range'], description: 'How to group analysis results' } }, required: ['card_list', 'analysis_type'] }; constructor(private readonly scryfallClient: ScryfallClient) {} /** * Validate parameters */ private validateParams(args: unknown): { card_list: string[]; analysis_type: string; format?: string; currency: string; include_suggestions: boolean; group_by?: string; } { if (!args || typeof args !== 'object') { throw new ValidationError('Invalid parameters'); } const params = args as BatchCardAnalysisParams; if (!Array.isArray(params.card_list) || params.card_list.length === 0) { throw new ValidationError('Card list is required and must be a non-empty array'); } if (params.card_list.length > 100) { throw new ValidationError('Card list cannot exceed 100 cards'); } if (!params.card_list.every((card: string) => typeof card === 'string' && card.trim().length > 0)) { throw new ValidationError('All cards in the list must be non-empty strings'); } if (!params.analysis_type || typeof params.analysis_type !== 'string') { throw new ValidationError('Analysis type is required and must be a string'); } const validAnalysisTypes = ['legality', 'prices', 'synergy', 'composition', 'comprehensive']; if (!validAnalysisTypes.includes(params.analysis_type)) { throw new ValidationError(`Analysis type must be one of: ${validAnalysisTypes.join(', ')}`); } if (params.format) { const validFormats = ['standard', 'modern', 'legacy', 'vintage', 'commander', 'pioneer']; if (!validFormats.includes(params.format)) { throw new ValidationError(`Format must be one of: ${validFormats.join(', ')}`); } } const currency = params.currency || 'usd'; const validCurrencies = ['usd', 'eur', 'tix']; if (!validCurrencies.includes(currency)) { throw new ValidationError(`Currency must be one of: ${validCurrencies.join(', ')}`); } const includeSuggestions = params.include_suggestions ?? false; if (typeof includeSuggestions !== 'boolean') { throw new ValidationError('Include suggestions must be a boolean'); } if (params.group_by) { const validGroupBy = ['type', 'cmc', 'color', 'rarity', 'price_range']; if (!validGroupBy.includes(params.group_by)) { throw new ValidationError(`Group by must be one of: ${validGroupBy.join(', ')}`); } } return { card_list: params.card_list.map((card: string) => card.trim()), analysis_type: params.analysis_type, format: params.format, currency, include_suggestions: includeSuggestions, group_by: params.group_by }; } async execute(args: unknown) { try { // Validate parameters const params = this.validateParams(args); // Fetch all cards const cards = await this.fetchCards(params.card_list); // Perform analysis based on type let analysisResult: string; switch (params.analysis_type) { case 'legality': analysisResult = this.analyzeLegality(cards, params.format); break; case 'prices': analysisResult = this.analyzePrices(cards, params.currency); break; case 'synergy': analysisResult = this.analyzeSynergy(cards); break; case 'composition': analysisResult = this.analyzeComposition(cards); break; case 'comprehensive': analysisResult = this.analyzeComprehensive(cards, params); break; default: throw new ValidationError(`Unknown analysis type: ${params.analysis_type}`); } // Add suggestions if requested if (params.include_suggestions) { analysisResult += this.generateSuggestions(cards, params); } return { content: [ { type: 'text', text: analysisResult } ] }; } catch (error) { // Handle validation errors if (error instanceof ValidationError) { return { content: [ { type: 'text', text: `Validation error: ${error.message}` } ], isError: true }; } // Generic error handling return { content: [ { type: 'text', text: `Unexpected error: ${error instanceof Error ? error.message : 'Unknown error occurred'}` } ], isError: true }; } } /** * Fetch all cards from the card list */ private async fetchCards(cardList: string[]): Promise<any[]> { const cards: any[] = []; const notFound: string[] = []; // Use batch processing for efficiency for (const cardName of cardList) { try { const card = await this.scryfallClient.getCard({ identifier: cardName }); cards.push(card); } catch (error) { if (error instanceof ScryfallAPIError && error.status === 404) { notFound.push(cardName); } else { throw error; } } } if (notFound.length > 0) { throw new ValidationError(`Cards not found: ${notFound.join(', ')}`); } return cards; } /** * Analyze format legality */ private analyzeLegality(cards: any[], format?: string): string { let result = `# Legality Analysis\n\n`; result += `**Total Cards:** ${cards.length}\n\n`; if (format) { const legal = cards.filter(card => card.legalities[format] === 'legal'); const banned = cards.filter(card => card.legalities[format] === 'banned'); const restricted = cards.filter(card => card.legalities[format] === 'restricted'); const notLegal = cards.filter(card => !['legal', 'banned', 'restricted'].includes(card.legalities[format])); result += `**${format.toUpperCase()} Legality:**\n`; result += `- Legal: ${legal.length} cards\n`; result += `- Banned: ${banned.length} cards\n`; result += `- Restricted: ${restricted.length} cards\n`; result += `- Not Legal: ${notLegal.length} cards\n\n`; if (banned.length > 0) { result += `**Banned Cards:**\n`; banned.forEach(card => result += `- ${card.name}\n`); result += '\n'; } if (restricted.length > 0) { result += `**Restricted Cards:**\n`; restricted.forEach(card => result += `- ${card.name}\n`); result += '\n'; } } else { // Show legality across all formats const formats = ['standard', 'modern', 'legacy', 'vintage', 'commander', 'pioneer']; result += `**Format Legality Summary:**\n`; for (const fmt of formats) { const legal = cards.filter(card => card.legalities[fmt] === 'legal').length; result += `- ${fmt.charAt(0).toUpperCase() + fmt.slice(1)}: ${legal}/${cards.length} legal\n`; } } return result; } /** * Analyze prices */ private analyzePrices(cards: any[], currency: string): string { let result = `# Price Analysis (${currency.toUpperCase()})\n\n`; const cardsWithPrices = cards.filter(card => (card.prices as any)[currency]); const prices = cardsWithPrices.map(card => parseFloat((card.prices as any)[currency])); if (prices.length === 0) { return result + 'No price data available for the specified currency.\n'; } const totalValue = prices.reduce((sum, price) => sum + price, 0); const averagePrice = totalValue / prices.length; const minPrice = Math.min(...prices); const maxPrice = Math.max(...prices); result += `**Summary:**\n`; result += `- Total Value: ${currency.toUpperCase()} ${totalValue.toFixed(2)}\n`; result += `- Average Price: ${currency.toUpperCase()} ${averagePrice.toFixed(2)}\n`; result += `- Price Range: ${currency.toUpperCase()} ${minPrice.toFixed(2)} - ${currency.toUpperCase()} ${maxPrice.toFixed(2)}\n`; result += `- Cards with Prices: ${cardsWithPrices.length}/${cards.length}\n\n`; // Price breakdown const expensive = cardsWithPrices.filter(card => parseFloat((card.prices as any)[currency]) >= 10); const moderate = cardsWithPrices.filter(card => { const price = parseFloat((card.prices as any)[currency]); return price >= 1 && price < 10; }); const budget = cardsWithPrices.filter(card => parseFloat((card.prices as any)[currency]) < 1); result += `**Price Categories:**\n`; result += `- Expensive (≥$10): ${expensive.length} cards\n`; result += `- Moderate ($1-$10): ${moderate.length} cards\n`; result += `- Budget (<$1): ${budget.length} cards\n\n`; if (expensive.length > 0) { result += `**Most Expensive Cards:**\n`; expensive .sort((a, b) => parseFloat((b.prices as any)[currency]) - parseFloat((a.prices as any)[currency])) .slice(0, 5) .forEach(card => { result += `- ${card.name}: ${currency.toUpperCase()} ${(card.prices as any)[currency]}\n`; }); } return result; } /** * Analyze synergy patterns */ private analyzeSynergy(cards: any[]): string { let result = `# Synergy Analysis\n\n`; // Analyze types const types = new Map<string, number>(); const keywords = new Map<string, number>(); const mechanics = new Map<string, number>(); cards.forEach(card => { // Extract types const cardTypes = card.type_line.toLowerCase().split(/[\s—]+/); cardTypes.forEach((type: string) => { if (type && type !== '—') { types.set(type, (types.get(type) || 0) + 1); } }); // Extract keywords and mechanics from oracle text if (card.oracle_text) { const text = card.oracle_text.toLowerCase(); // Common keywords const keywordList = ['flying', 'trample', 'haste', 'vigilance', 'lifelink', 'deathtouch', 'first strike', 'double strike']; keywordList.forEach(keyword => { if (text.includes(keyword)) { keywords.set(keyword, (keywords.get(keyword) || 0) + 1); } }); // Common mechanics const mechanicList = ['proliferate', 'scry', 'surveil', 'explore', 'convoke', 'delve']; mechanicList.forEach(mechanic => { if (text.includes(mechanic)) { mechanics.set(mechanic, (mechanics.get(mechanic) || 0) + 1); } }); } }); // Report common types result += `**Common Types:**\n`; Array.from(types.entries()) .sort((a, b) => b[1] - a[1]) .slice(0, 10) .forEach(([type, count]) => { result += `- ${type.charAt(0).toUpperCase() + type.slice(1)}: ${count} cards\n`; }); // Report common keywords if (keywords.size > 0) { result += `\n**Common Keywords:**\n`; Array.from(keywords.entries()) .sort((a, b) => b[1] - a[1]) .slice(0, 5) .forEach(([keyword, count]) => { result += `- ${keyword.charAt(0).toUpperCase() + keyword.slice(1)}: ${count} cards\n`; }); } // Report common mechanics if (mechanics.size > 0) { result += `\n**Common Mechanics:**\n`; Array.from(mechanics.entries()) .sort((a, b) => b[1] - a[1]) .slice(0, 5) .forEach(([mechanic, count]) => { result += `- ${mechanic.charAt(0).toUpperCase() + mechanic.slice(1)}: ${count} cards\n`; }); } return result; } /** * Analyze deck composition */ private analyzeComposition(cards: any[]): string { let result = `# Composition Analysis\n\n`; result += `**Total Cards:** ${cards.length}\n\n`; // Mana curve analysis const manaCurve = new Map<number, number>(); cards.forEach(card => { const cmc = card.cmc || 0; manaCurve.set(cmc, (manaCurve.get(cmc) || 0) + 1); }); result += `**Mana Curve:**\n`; for (let i = 0; i <= 10; i++) { const count = manaCurve.get(i) || 0; if (count > 0 || i <= 7) { result += `- ${i}${i >= 7 ? '+' : ''}: ${count} cards\n`; } } // Color distribution const colors = new Map<string, number>(); const colorIdentity = new Map<string, number>(); cards.forEach(card => { // Count individual colors in mana cost if (card.mana_cost) { const colorMatches = card.mana_cost.match(/[WUBRG]/g) || []; colorMatches.forEach((color: string) => { colors.set(color, (colors.get(color) || 0) + 1); }); } // Count color identity if (card.color_identity && card.color_identity.length > 0) { const identity = card.color_identity.sort().join(''); colorIdentity.set(identity, (colorIdentity.get(identity) || 0) + 1); } else { colorIdentity.set('Colorless', (colorIdentity.get('Colorless') || 0) + 1); } }); result += `\n**Color Distribution:**\n`; const colorNames = { W: 'White', U: 'Blue', B: 'Black', R: 'Red', G: 'Green' }; Object.entries(colorNames).forEach(([symbol, name]) => { const count = colors.get(symbol) || 0; result += `- ${name}: ${count} symbols\n`; }); result += `\n**Color Identity:**\n`; Array.from(colorIdentity.entries()) .sort((a, b) => b[1] - a[1]) .forEach(([identity, count]) => { result += `- ${identity || 'Colorless'}: ${count} cards\n`; }); return result; } /** * Comprehensive analysis combining all types */ private analyzeComprehensive(cards: any[], params: any): string { let result = `# Comprehensive Analysis\n\n`; result += this.analyzeLegality(cards, params.format); result += '\n---\n\n'; result += this.analyzePrices(cards, params.currency); result += '\n---\n\n'; result += this.analyzeComposition(cards); result += '\n---\n\n'; result += this.analyzeSynergy(cards); return result; } /** * Generate improvement suggestions */ private generateSuggestions(cards: any[], params: any): string { let suggestions = `\n\n# Suggestions\n\n`; // Format-specific suggestions if (params.format) { const illegal = cards.filter(card => card.legalities[params.format] !== 'legal'); if (illegal.length > 0) { suggestions += `**Format Compliance:**\n`; suggestions += `- Consider replacing ${illegal.length} cards that are not legal in ${params.format}\n`; } } // Price suggestions const expensiveCards = cards.filter(card => { const price = parseFloat((card.prices as any)[params.currency] || '0'); return price >= 20; }); if (expensiveCards.length > 0) { suggestions += `**Budget Optimization:**\n`; suggestions += `- Consider finding alternatives for ${expensiveCards.length} expensive cards (≥$20)\n`; } // Mana curve suggestions const highCmc = cards.filter(card => (card.cmc || 0) >= 6).length; const lowCmc = cards.filter(card => (card.cmc || 0) <= 2).length; if (highCmc > cards.length * 0.2) { suggestions += `**Mana Curve:**\n`; suggestions += `- Consider reducing high-cost cards (${highCmc} cards with CMC ≥6)\n`; } if (lowCmc < cards.length * 0.3) { suggestions += `**Early Game:**\n`; suggestions += `- Consider adding more low-cost cards for early game presence\n`; } return suggestions; } }
• src/tools/batch-card-analysis.ts:11-49 (schema)

  Input schema definition for the batch_card_analysis tool, defining parameters like card_list, analysis_type, format, etc.
  readonly inputSchema = { type: 'object' as const, properties: { card_list: { type: 'array', items: { type: 'string' }, description: 'List of card names to analyze', minItems: 1, maxItems: 100 }, analysis_type: { type: 'string', enum: ['legality', 'prices', 'synergy', 'composition', 'comprehensive'], description: 'Type of analysis to perform' }, format: { type: 'string', enum: ['standard', 'modern', 'legacy', 'vintage', 'commander', 'pioneer'], description: 'Format for legality analysis' }, currency: { type: 'string', enum: ['usd', 'eur', 'tix'], default: 'usd', description: 'Currency for price analysis' }, include_suggestions: { type: 'boolean', default: false, description: 'Include improvement suggestions' }, group_by: { type: 'string', enum: ['type', 'cmc', 'color', 'rarity', 'price_range'], description: 'How to group analysis results' } }, required: ['card_list', 'analysis_type'] };
• src/server.ts:75-75 (registration)

  Registration of the batch_card_analysis tool in the MCP server constructor.
  this.tools.set("batch_card_analysis", new BatchCardAnalysisTool(this.scryfallClient));
• src/types/mcp-types.ts:55-63 (schema)

  TypeScript interface for BatchCardAnalysisParams used in tool validation.
  export interface BatchCardAnalysisParams { card_list: string[]; analysis_type: "legality" | "prices" | "synergy" | "composition" | "comprehensive"; format?: MagicFormat; currency?: "usd" | "eur" | "tix"; include_images?: boolean; include_suggestions?: boolean; group_by?: string; }