get_format_staples

Instructions

Implementation Reference

• src/tools/get-format-staples.ts:39-144 (handler)

  Main handler function that executes the 'get_format_staples' tool logic. Looks up format info, finds relevant archetypes, collects staple cards, and returns a FormatStaplesResult.

  export function handler(_db: Database.Database, params: GetFormatStaplesParams): FormatStaplesResult {
    const formatLower = params.format.toLowerCase();
  
    // 1. Find format info
    const formatInfo = FORMATS.find(f =>
      f.id === formatLower || f.name.toLowerCase() === formatLower
    );
  
    // 2. If format is commander, include commander strategies
    const isCommander = formatLower === 'commander' || formatLower === 'edh';
  
    // 3. Find relevant archetypes
    let archetypes: Archetype[];
    if (params.archetype) {
      const arch = ARCHETYPES.find(a =>
        a.id === params.archetype!.toLowerCase() ||
        a.name.toLowerCase() === params.archetype!.toLowerCase()
      );
      archetypes = arch ? [arch] : [];
    } else {
      archetypes = ARCHETYPES.filter(a =>
        a.formatPresence.some(f => f.toLowerCase() === formatLower)
      );
    }
  
    // 4. Collect staple cards
    const stapleSet = new Set<string>();
  
    // From archetypes
    for (const arch of archetypes) {
      for (const card of arch.exampleCards) {
        stapleSet.add(card);
      }
    }
  
    // From commander strategies if format is commander
    if (isCommander) {
      let strategies: CommanderStrategy[];
      if (params.archetype) {
        const strat = COMMANDER_STRATEGIES.find(s =>
          s.id === params.archetype!.toLowerCase() ||
          s.name.toLowerCase() === params.archetype!.toLowerCase()
        );
        strategies = strat ? [strat] : [];
  
        // If we found a commander strategy, use it even if no archetype matched
        if (strategies.length > 0 && archetypes.length === 0) {
          // Commander strategies are valid archetype sources too
        }
      } else {
        strategies = [...COMMANDER_STRATEGIES];
      }
  
      for (const strat of strategies) {
        for (const card of strat.stapleCards) {
          stapleSet.add(card);
        }
      }
    }
  
    // Build archetype output — include commander strategies as pseudo-archetypes
    const archetypeOutput: Array<{ id: string; name: string; example_cards: string[] }> = [];
  
    for (const arch of archetypes) {
      archetypeOutput.push({
        id: arch.id,
        name: arch.name,
        example_cards: [...arch.exampleCards],
      });
    }
  
    if (isCommander) {
      let strategies: CommanderStrategy[];
      if (params.archetype) {
        const strat = COMMANDER_STRATEGIES.find(s =>
          s.id === params.archetype!.toLowerCase() ||
          s.name.toLowerCase() === params.archetype!.toLowerCase()
        );
        strategies = strat ? [strat] : [];
      } else {
        strategies = [...COMMANDER_STRATEGIES];
      }
  
      for (const strat of strategies) {
        archetypeOutput.push({
          id: strat.id,
          name: strat.name,
          example_cards: [...strat.stapleCards],
        });
      }
    }
  
    return {
      format: params.format,
      format_info: formatInfo
        ? {
            name: formatInfo.name,
            description: formatInfo.description,
            power_level: formatInfo.powerLevel,
          }
        : null,
      archetype_filter: params.archetype ?? null,
      staple_cards: [...stapleSet],
      archetypes: archetypeOutput,
    };
  }

• src/tools/get-format-staples.ts:12-17 (schema)

  Input schema using Zod: validates 'format' (string, required) and 'archetype' (string, optional).

  export const GetFormatStaplesInput = z.object({
    format: z.string().describe('Format to get staples for (e.g. "commander", "modern", "legacy")'),
    archetype: z.string().optional().describe('Optional archetype filter (e.g. "aggro-red", "control-uw")'),
  });
  
  export type GetFormatStaplesParams = z.infer<typeof GetFormatStaplesInput>;

• src/tools/get-format-staples.ts:21-35 (schema)

  Output type interface 'FormatStaplesResult' defining the shape of the returned data (format info, staple cards, archetypes).

  export interface FormatStaplesResult {
    format: string;
    format_info: {
      name: string;
      description: string;
      power_level: number;
    } | null;
    archetype_filter: string | null;
    staple_cards: string[];
    archetypes: Array<{
      id: string;
      name: string;
      example_cards: string[];
    }>;
  }

• src/server.ts:237-249 (registration)

  Registration of the 'get_format_staples' tool with the MCP server, wiring up the schema, handler, and formatter.

  server.tool(
    'get_format_staples',
    'Get staple cards and popular archetypes for a specific format (Commander, Modern, Legacy, etc.). Use this when a user asks about the meta, popular decks, or key cards in a format. Optionally filter by archetype.',
    GetFormatStaplesInput.shape,
    async (params) => {
      try {
        const result = getFormatStaplesHandler(db, params);
        return { content: [{ type: 'text' as const, text: formatGetFormatStaples(result) }] };
      } catch (err) {
        return { content: [{ type: 'text' as const, text: `Error getting format staples: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
      }
    },
  );

• src/format.ts:399-428 (helper)

  Formatting function that converts the FormatStaplesResult into a human-readable string for the response.

  export function formatGetFormatStaples(result: FormatStaplesResult): string {
    const lines: string[] = [];
  
    const title = result.archetype_filter
      ? `# ${capitalize(result.format)} Staples — ${result.archetype_filter}`
      : `# ${capitalize(result.format)} Staples`;
    lines.push(title);
  
    if (result.format_info) {
      lines.push(`${result.format_info.description}`);
      lines.push(`Power Level: ${result.format_info.power_level}/10`);
    }
  
    if (result.staple_cards.length > 0) {
      lines.push(`\n## Key Cards (${result.staple_cards.length})`);
      lines.push(result.staple_cards.map(c => `- ${c}`).join('\n'));
    }
  
    if (result.archetypes.length > 0) {
      lines.push('\n## Archetypes');
      for (const arch of result.archetypes) {
        lines.push(`\n### ${arch.name}`);
        if (arch.example_cards.length > 0) {
          lines.push(arch.example_cards.map(c => `- ${c}`).join('\n'));
        }
      }
    }
  
    return lines.join('\n');
  }