FinaShopping MCP Server

Instructions

Implementation Reference

• src/tools/cards.ts:23-53 (handler)

  The handler function that fetches all credit cards, filters by optional network and maxAnnualFee parameters, sorts by ascending annual fee, and returns a structured JSON response with the results, count, applied filters, and usage tip.

  async ({ network, maxAnnualFee }) => {
    const creditCards = await getCreditCards();
    let filteredCards = [...creditCards];
  
    // Filter by network
    if (network) {
      filteredCards = filteredCards.filter(card => card.network === network);
    }
  
    // Filter by max annual fee
    if (maxAnnualFee !== undefined) {
      filteredCards = filteredCards.filter(card => card.annualFee <= maxAnnualFee);
    }
  
    // Sort by annual fee (lowest first)
    filteredCards.sort((a, b) => a.annualFee - b.annualFee);
  
    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify({
          creditCards: filteredCards,
          count: filteredCards.length,
          filters: { network, maxAnnualFee },
          tip: maxAnnualFee === 0 || (maxAnnualFee !== undefined && maxAnnualFee === 0)
            ? 'You found cards with no annual fee! | Encontraste tarjetas sin costo anual!'
            : 'Tip: Use maxAnnualFee: 0 to see only free cards | Tip: Usa maxAnnualFee: 0 para ver solo tarjetas gratis'
        }, null, 2)
      }]
    };
  }

• src/tools/cards.ts:19-22 (schema)

  Input schema defined with Zod: optional 'network' as enum ['OCA', 'Visa', 'Mastercard'], optional 'maxAnnualFee' as number >= 0, both with bilingual descriptions.

  {
    network: z.enum(['OCA', 'Visa', 'Mastercard']).optional().describe('Payment network | Red de pago'),
    maxAnnualFee: z.number().min(0).optional().describe('Maximum annual fee in Uruguayan pesos | Costo anual máximo en pesos uruguayos')
  },

• src/tools/cards.ts:16-54 (registration)

  Primary registration of the 'search-credit-cards' tool via server.tool() within registerCardTools, including bilingual description, input schema, and inline handler.

  server.tool(
    'search-credit-cards',
    'Search available credit cards in Uruguay. Filter by payment network and maximum annual fee. | Buscar tarjetas de crédito disponibles en Uruguay. Filtrar por red de pago y costo anual máximo.',
    {
      network: z.enum(['OCA', 'Visa', 'Mastercard']).optional().describe('Payment network | Red de pago'),
      maxAnnualFee: z.number().min(0).optional().describe('Maximum annual fee in Uruguayan pesos | Costo anual máximo en pesos uruguayos')
    },
    async ({ network, maxAnnualFee }) => {
      const creditCards = await getCreditCards();
      let filteredCards = [...creditCards];
  
      // Filter by network
      if (network) {
        filteredCards = filteredCards.filter(card => card.network === network);
      }
  
      // Filter by max annual fee
      if (maxAnnualFee !== undefined) {
        filteredCards = filteredCards.filter(card => card.annualFee <= maxAnnualFee);
      }
  
      // Sort by annual fee (lowest first)
      filteredCards.sort((a, b) => a.annualFee - b.annualFee);
  
      return {
        content: [{
          type: 'text' as const,
          text: JSON.stringify({
            creditCards: filteredCards,
            count: filteredCards.length,
            filters: { network, maxAnnualFee },
            tip: maxAnnualFee === 0 || (maxAnnualFee !== undefined && maxAnnualFee === 0)
              ? 'You found cards with no annual fee! | Encontraste tarjetas sin costo anual!'
              : 'Tip: Use maxAnnualFee: 0 to see only free cards | Tip: Usa maxAnnualFee: 0 para ver solo tarjetas gratis'
          }, null, 2)
        }]
      };
    }
  );

• src/tools/cards.ts:9-12 (helper)

  Helper function that fetches credit cards data from the API using fetchCreditCards() and returns the creditCards array.

  async function getCreditCards(): Promise<CreditCard[]> {
    const response = await fetchCreditCards();
    return response.creditCards;
  }

• src/tools/index.ts:6-10 (registration)

  Top-level tool registration function that calls registerCardTools(server), indirectly registering search-credit-cards.

  export function registerAllTools(server: McpServer): void {
    registerLoanTools(server);
    registerCardTools(server);
    registerInsuranceTools(server);
  }