Character Versions

Instructions

Implementation Reference

• src/tools/character-versions.ts:32-76 (handler)

  The async handler function passed to server.registerTool for 'character_versions'. It calls getCardsByCharacterName, groups results by version, and returns formatted text output.

  async (args) => {
    const cards = getCardsByCharacterName(db, args.character_name);
  
    if (cards.length === 0) {
      // Try partial match suggestions
      const suggestions = db
        .prepare(
          'SELECT DISTINCT name FROM cards WHERE name LIKE @pattern LIMIT 5',
        )
        .all({ pattern: `%${args.character_name}%` }) as { name: string }[];
  
      let text = `No versions found for character "${args.character_name}".`;
      if (suggestions.length > 0) {
        text += `\n\nDid you mean one of these?\n${suggestions.map((s) => `  - ${s.name}`).join('\n')}`;
      }
  
      return {
        content: [{ type: 'text' as const, text }],
        isError: true,
      };
    }
  
    // Group by version
    const versionMap = new Map<string, CardRow[]>();
    for (const card of cards) {
      const version = card.version ?? card.full_name ?? card.name;
      const existing = versionMap.get(version) ?? [];
      existing.push(card);
      versionMap.set(version, existing);
    }
  
    const header = `**${args.character_name}** — ${versionMap.size} version${versionMap.size !== 1 ? 's' : ''}, ${cards.length} printing${cards.length !== 1 ? 's' : ''}`;
  
    const sections: string[] = [header, ''];
    for (const [, printings] of versionMap) {
      for (const card of printings) {
        sections.push(formatVersionCard(card));
        sections.push('');
      }
    }
  
    return {
      content: [{ type: 'text' as const, text: sections.join('\n').trimEnd() }],
    };
  },

• src/tools/character-versions.ts:28-30 (schema)

  Input schema for the 'character_versions' tool, defining the 'character_name' parameter with a Zod string description.

  inputSchema: {
    character_name: z.string().describe('Character base name (e.g. "Elsa", "Mickey Mouse")'),
  },

• src/tools/character-versions.ts:21-78 (registration)

  The registerCharacterVersions function that calls server.registerTool with the name 'character_versions', schema, and handler.

  export function registerCharacterVersions(server: McpServer, db: Database.Database): void {
    server.registerTool(
      'character_versions',
      {
        title: 'Character Versions',
        description:
          'Show all printings/versions of a Disney Lorcana character across sets. Useful for comparing different versions of the same character.',
        inputSchema: {
          character_name: z.string().describe('Character base name (e.g. "Elsa", "Mickey Mouse")'),
        },
      },
      async (args) => {
        const cards = getCardsByCharacterName(db, args.character_name);
  
        if (cards.length === 0) {
          // Try partial match suggestions
          const suggestions = db
            .prepare(
              'SELECT DISTINCT name FROM cards WHERE name LIKE @pattern LIMIT 5',
            )
            .all({ pattern: `%${args.character_name}%` }) as { name: string }[];
  
          let text = `No versions found for character "${args.character_name}".`;
          if (suggestions.length > 0) {
            text += `\n\nDid you mean one of these?\n${suggestions.map((s) => `  - ${s.name}`).join('\n')}`;
          }
  
          return {
            content: [{ type: 'text' as const, text }],
            isError: true,
          };
        }
  
        // Group by version
        const versionMap = new Map<string, CardRow[]>();
        for (const card of cards) {
          const version = card.version ?? card.full_name ?? card.name;
          const existing = versionMap.get(version) ?? [];
          existing.push(card);
          versionMap.set(version, existing);
        }
  
        const header = `**${args.character_name}** — ${versionMap.size} version${versionMap.size !== 1 ? 's' : ''}, ${cards.length} printing${cards.length !== 1 ? 's' : ''}`;
  
        const sections: string[] = [header, ''];
        for (const [, printings] of versionMap) {
          for (const card of printings) {
            sections.push(formatVersionCard(card));
            sections.push('');
          }
        }
  
        return {
          content: [{ type: 'text' as const, text: sections.join('\n').trimEnd() }],
        };
      },
    );
  }

• src/server.ts:45-49 (registration)

  Registration call in src/server.ts that invokes registerCharacterVersions(server, db) to attach the tool to the MCP server.

  registerCharacterVersions(server, db);
  registerBrowseFranchise(server, db);
  registerAnalyzeInkCurve(server, db);
  registerAnalyzeLore(server, db);
  registerFindSongSynergies(server, db);

• src/tools/character-versions.ts:7-19 (helper)

  Helper function formatVersionCard that formats a single CardRow into a readable text block with name, rarity, set, ink, cost, stats, and text.

  function formatVersionCard(card: CardRow): string {
    const lines: string[] = [];
    lines.push(`**${card.full_name ?? card.name}**`);
    lines.push(`  Rarity: ${card.rarity ?? '—'} | Set: ${card.set_code ?? '—'}`);
    lines.push(`  Ink: ${card.color} | Cost: ${card.cost ?? '—'} | Inkwell: ${card.inkwell ? 'Yes' : 'No'}`);
    if (card.type === 'Character') {
      lines.push(`  Strength: ${card.strength ?? '—'} | Willpower: ${card.willpower ?? '—'} | Lore: ${card.lore ?? '—'}`);
    }
    if (card.full_text) {
      lines.push(`  Text: ${card.full_text}`);
    }
    return lines.join('\n');
  }