Scryfall MCP Server

Instructions

Implementation Reference

• src/tools/build-scryfall-query.ts:101-163 (handler)

  The main execute method implementing the tool logic: validates input, parses natural language, builds and tests Scryfall query, formats response.

  async execute(args: unknown) {
    try {
      // Validate input parameters
      const params = validateBuildQueryParams(args);
      
      // Sanitize natural language input (using a more permissive approach for natural language)
      const sanitizedQuery = params.natural_query.trim()
        // eslint-disable-next-line no-control-regex
        .replace(/[\x00-\x1F\x7F-\x9F]/g, '') // Remove control characters
        .substring(0, 500); // Enforce max length
      
      if (!sanitizedQuery) {
        throw new ValidationError('Natural query cannot be empty after sanitization');
      }
      
      // Parse natural language
      const parsed = this.parser.parse(sanitizedQuery, {
        targetFormat: params.format,
        optimizationStrategy: params.optimize_for,
        maxResults: params.max_results
      });
      
      // Check parsing confidence
      if (parsed.confidence < 0.3) {
        return this.handleLowConfidenceParsing(parsed, params);
      }
      
      // Build Scryfall query
      const buildOptions = {
        optimize_for: params.optimize_for,
        format: params.format,
        max_results: params.max_results,
        price_budget: params.price_budget
      };
      
      const buildResult = await this.queryBuilder.build(parsed, buildOptions);
      
      // Test query if requested (sanitize the generated query before testing)
      let testResult;
      if (params.test_query) {
        const sanitizedTestQuery = sanitizeQuery(buildResult.query);
        testResult = await this.testQuery(sanitizedTestQuery);
      }
      
      // Format response
      const responseText = this.formatResponse(
        buildResult,
        testResult,
        params,
        parsed
      );
      
      return {
        content: [{
          type: 'text',
          text: responseText
        }]
      };
  
    } catch (error) {
      return this.handleError(error);
    }
  }

• src/tools/build-scryfall-query.ts:31-92 (schema)

  Input schema defining parameters for the build_scryfall_query tool, including natural_query, format, optimization options, etc.

  readonly inputSchema = {
    type: 'object' as const,
    properties: {
      natural_query: {
        type: 'string',
        description: 'Natural language description of what you want to find (e.g., "red creatures under $5 for aggressive decks", "blue counterspells in modern")',
        minLength: 1,
        maxLength: 500
      },
      format: {
        type: 'string',
        enum: ['standard', 'modern', 'legacy', 'vintage', 'commander', 'pioneer', 'brawl', 'pauper', 'penny', 'historic', 'alchemy'],
        description: 'Magic format to restrict search to (optional)'
      },
      optimize_for: {
        type: 'string',
        enum: ['precision', 'recall', 'discovery', 'budget'],
        default: 'precision',
        description: 'Search optimization strategy: precision (fewer, more relevant results), recall (broader search), discovery (interesting cards), budget (cost-effective)'
      },
      max_results: {
        type: 'number',
        minimum: 1,
        maximum: 175,
        default: 20,
        description: 'Target number of results for optimization'
      },
      price_budget: {
        type: 'object',
        properties: {
          max: {
            type: 'number',
            minimum: 0,
            description: 'Maximum price per card'
          },
          currency: {
            type: 'string',
            enum: ['usd', 'eur', 'tix'],
            default: 'usd',
            description: 'Currency for price constraints'
          }
        },
        description: 'Price constraints for the search'
      },
      include_alternatives: {
        type: 'boolean',
        default: true,
        description: 'Whether to include alternative query suggestions'
      },
      explain_mapping: {
        type: 'boolean',
        default: true,
        description: 'Whether to include detailed explanation of natural language to Scryfall mapping'
      },
      test_query: {
        type: 'boolean',
        default: true,
        description: 'Whether to test the generated query and optimize based on results'
      }
    },
    required: ['natural_query']
  };

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

  Registration of the BuildScryfallQueryTool instance in the server's tools map under the name 'build_scryfall_query'.

  this.tools.set("build_scryfall_query", new BuildScryfallQueryTool(this.scryfallClient));

• src/tools/build-scryfall-query.ts:27-28 (handler)

  Class definition with tool name and description.

  export class BuildScryfallQueryTool {
    readonly name = 'build_scryfall_query';