FinaShopping MCP Server

Instructions

Implementation Reference

• src/tools/loans.ts:35-77 (handler)

  The handler function for the 'search-loans' tool. Fetches all loans using getLoans(), applies optional filters for amount (within 50-200% range), term (50-200% range), and type (keyword match in loan name), then returns a JSON stringified response with filtered loans, count, and applied filters.

  async ({ amount, term, type }) => {
    const loans = await getLoans();
    let filteredLoans = [...loans];
  
    // Filter by amount (±50% range)
    if (amount) {
      const minAmount = amount * 0.5;
      const maxAmount = amount * 2;
      filteredLoans = filteredLoans.filter(
        loan => loan.amount >= minAmount && loan.amount <= maxAmount
      );
    }
  
    // Filter by type
    if (type) {
      const loanName = type.toLowerCase();
      filteredLoans = filteredLoans.filter(loan => {
        const name = loan.name.toLowerCase();
        if (loanName === 'personal') return name.includes('personal');
        if (loanName === 'auto') return name.includes('auto');
        if (loanName === 'hipotecario') return name.includes('hipotec');
        return true;
      });
    }
  
    // Filter by term
    if (term) {
      filteredLoans = filteredLoans.filter(
        loan => loan.term >= term * 0.5 && loan.term <= term * 2
      );
    }
  
    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify({
          loans: filteredLoans,
          count: filteredLoans.length,
          filters: { amount, term, type }
        }, null, 2)
      }]
    };
  }

• src/tools/loans.ts:30-34 (schema)

  Input schema for search-loans tool using Zod: optional amount (positive number), term (6-360 months), type (enum: personal, auto, hipotecario).

  {
    amount: z.number().positive().optional().describe('Loan amount in Uruguayan pesos | Monto del préstamo en pesos uruguayos'),
    term: z.number().min(6).max(360).optional().describe('Term in months | Plazo en meses'),
    type: z.enum(['personal', 'auto', 'hipotecario']).optional().describe('Loan type | Tipo de préstamo')
  },

• src/tools/loans.ts:27-78 (registration)

  Registration of the 'search-loans' tool on the MCP server using server.tool(), including name, bilingual description, input schema, and inline handler function. Called from registerLoanTools.

  server.tool(
    'search-loans',
    'Search available loans from Uruguayan financial institutions. Filter by amount, term, and type. | Buscar préstamos disponibles en instituciones financieras uruguayas. Filtrar por monto, plazo y tipo.',
    {
      amount: z.number().positive().optional().describe('Loan amount in Uruguayan pesos | Monto del préstamo en pesos uruguayos'),
      term: z.number().min(6).max(360).optional().describe('Term in months | Plazo en meses'),
      type: z.enum(['personal', 'auto', 'hipotecario']).optional().describe('Loan type | Tipo de préstamo')
    },
    async ({ amount, term, type }) => {
      const loans = await getLoans();
      let filteredLoans = [...loans];
  
      // Filter by amount (±50% range)
      if (amount) {
        const minAmount = amount * 0.5;
        const maxAmount = amount * 2;
        filteredLoans = filteredLoans.filter(
          loan => loan.amount >= minAmount && loan.amount <= maxAmount
        );
      }
  
      // Filter by type
      if (type) {
        const loanName = type.toLowerCase();
        filteredLoans = filteredLoans.filter(loan => {
          const name = loan.name.toLowerCase();
          if (loanName === 'personal') return name.includes('personal');
          if (loanName === 'auto') return name.includes('auto');
          if (loanName === 'hipotecario') return name.includes('hipotec');
          return true;
        });
      }
  
      // Filter by term
      if (term) {
        filteredLoans = filteredLoans.filter(
          loan => loan.term >= term * 0.5 && loan.term <= term * 2
        );
      }
  
      return {
        content: [{
          type: 'text' as const,
          text: JSON.stringify({
            loans: filteredLoans,
            count: filteredLoans.length,
            filters: { amount, term, type }
          }, null, 2)
        }]
      };
    }
  );

• src/tools/loans.ts:17-23 (helper)

  Helper function getLoans() that fetches the full list of loans from the API via fetchLoans() for use in search-loans and other loan tools.

  /**
   * Fetch loans from API
   */
  async function getLoans(): Promise<Loan[]> {
    const response = await fetchLoans();
    return response.loans;
  }

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

  Central tool registration function that calls registerLoanTools (which registers search-loans among others). This is invoked from the main server setup.

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