Scryfall MCP Server

Instructions

Implementation Reference

• src/tools/get-card.ts:57-142 (handler)

  The main handler function that validates input, fetches card data from ScryfallClient, formats the response, and handles various errors including validation, rate limits, and API errors.

  async execute(args: unknown) {
    try {
      // Validate parameters
      const params = validateGetCardParams(args);
      
      // Sanitize and validate card identifier
      const sanitizedIdentifier = sanitizeCardIdentifier(params.identifier);
      validateCardIdentifier(sanitizedIdentifier);
  
      // Execute card lookup
      const card = await this.scryfallClient.getCard({
        identifier: sanitizedIdentifier,
        set: params.set,
        lang: params.lang,
        face: params.face
      });
  
      // Format detailed card information
      const responseText = formatCardDetails(card, params.include_image);
  
      return {
        content: [
          {
            type: 'text',
            text: responseText
          }
        ]
      };
  
    } catch (error) {
      // Handle different error types
      if (error instanceof ValidationError) {
        return {
          content: [
            {
              type: 'text',
              text: `Validation error: ${error.message}`
            }
          ],
          isError: true
        };
      }
  
      if (error instanceof RateLimitError) {
        const retry = error.retryAfter ? ` Retry after ${error.retryAfter}s.` : '';
        return {
          content: [{ type: 'text', text: `Rate limit exceeded.${retry} Please wait and try again.` }],
          isError: true
        };
      }
  
      if (error instanceof ScryfallAPIError) {
        let errorMessage = `Scryfall API error: ${error.message}`;
        
        if (error.status === 404) {
          errorMessage = `Card not found: "${(args as GetCardParams)?.identifier ?? 'unknown'}". Check the card name, set code, or ID.`;
        } else if (error.status === 422) {
          errorMessage = `Invalid card identifier format. Use card name, "SET/NUMBER", or Scryfall UUID.`;
        } else if (error.status === 429) {
          errorMessage = 'Rate limit exceeded. Please wait a moment and try again.';
        }
  
        return {
          content: [
            {
              type: 'text',
              text: errorMessage
            }
          ],
          isError: true
        };
      }
  
      // Generic error handling with enhanced context
      const errorDetails = this.formatGenericError(error, args as GetCardParams);
      return {
        content: [
          {
            type: 'text',
            text: errorDetails
          }
        ],
        isError: true
      };
    }
  }

• src/tools/get-card.ts:23-52 (schema)

  Input schema defining the parameters accepted by the get_card tool, including identifier (required), set, lang, face, and include_image.

  readonly inputSchema = {
    type: 'object' as const,
    properties: {
      identifier: {
        type: 'string',
        description: 'Card name, set code+collector number (e.g., "dom/123"), or Scryfall UUID'
      },
      set: {
        type: 'string',
        description: '3-letter set code for disambiguation when using card name',
        pattern: '^[a-zA-Z0-9]{3,4}$'
      },
      lang: {
        type: 'string',
        description: '2-letter language code (default: en)',
        pattern: '^[a-z]{2}$',
        default: 'en'
      },
      face: {
        type: 'string',
        enum: ['front', 'back'],
        description: 'Which face to show for double-faced cards'
      },
      include_image: {
        type: 'boolean',
        description: 'Include image URL in response',
        default: true
      }
    },
    required: ['identifier']

• src/server.ts:67-67 (registration)

  Registers the GetCardTool instance in the server's tools Map under the name 'get_card', making it available for MCP tool calls.

  this.tools.set("get_card", new GetCardTool(this.scryfallClient));