FinaShopping MCP Server

Instructions

Implementation Reference

• src/tools/loans.ts:118-166 (handler)

  Handler function that takes loanIds, fetches all loans using getLoans(), selects specified loans, checks for at least 2, computes comparison data including totalCost, finds best by lowest rate/payment and highest approval probability, returns JSON with comparison table and recommendations.

  async ({ loanIds }) => {
    const loans = await getLoans();
    const selectedLoans = loans.filter(loan => loanIds.includes(loan.id));
  
    if (selectedLoans.length < 2) {
      return {
        content: [{
          type: 'text' as const,
          text: JSON.stringify({
            error: 'At least 2 valid loans are required for comparison | Se necesitan al menos 2 préstamos válidos para comparar',
            validIds: loans.map(l => l.id)
          })
        }],
        isError: true
      };
    }
  
    const comparison = selectedLoans.map(loan => ({
      id: loan.id,
      name: loan.name,
      institution: loan.institution,
      amount: loan.amount,
      currency: loan.currency,
      rate: loan.rate,
      term: loan.term,
      monthlyPayment: loan.monthlyPayment,
      totalCost: loan.monthlyPayment * loan.term,
      probability: loan.probability
    }));
  
    // Find best options
    const lowestRate = comparison.reduce((min, l) => l.rate < min.rate ? l : min);
    const lowestPayment = comparison.reduce((min, l) => l.monthlyPayment < min.monthlyPayment ? l : min);
    const highestProbability = comparison.find(l => l.probability === 'alta') || comparison[0];
  
    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify({
          comparison,
          recommendations: {
            lowestRate: { id: lowestRate.id, name: lowestRate.name, rate: lowestRate.rate },
            lowestPayment: { id: lowestPayment.id, name: lowestPayment.name, payment: lowestPayment.monthlyPayment },
            highestApproval: { id: highestProbability.id, name: highestProbability.name, probability: highestProbability.probability }
          }
        }, null, 2)
      }]
    };
  }

• src/tools/loans.ts:115-117 (schema)

  Zod input schema requiring an array of 2 to 5 numeric loan IDs.

  {
    loanIds: z.array(z.number()).min(2).max(5).describe('Loan IDs to compare | IDs de préstamos a comparar')
  },

• src/tools/loans.ts:111-167 (registration)

  Direct registration of the compare-loans tool using server.tool(), including description, schema, and inline handler.

  // Tool: compare-loans
  server.tool(
    'compare-loans',
    'Compare multiple loans side by side. Useful for choosing the best option. | Comparar múltiples préstamos lado a lado. Útil para elegir la mejor opción.',
    {
      loanIds: z.array(z.number()).min(2).max(5).describe('Loan IDs to compare | IDs de préstamos a comparar')
    },
    async ({ loanIds }) => {
      const loans = await getLoans();
      const selectedLoans = loans.filter(loan => loanIds.includes(loan.id));
  
      if (selectedLoans.length < 2) {
        return {
          content: [{
            type: 'text' as const,
            text: JSON.stringify({
              error: 'At least 2 valid loans are required for comparison | Se necesitan al menos 2 préstamos válidos para comparar',
              validIds: loans.map(l => l.id)
            })
          }],
          isError: true
        };
      }
  
      const comparison = selectedLoans.map(loan => ({
        id: loan.id,
        name: loan.name,
        institution: loan.institution,
        amount: loan.amount,
        currency: loan.currency,
        rate: loan.rate,
        term: loan.term,
        monthlyPayment: loan.monthlyPayment,
        totalCost: loan.monthlyPayment * loan.term,
        probability: loan.probability
      }));
  
      // Find best options
      const lowestRate = comparison.reduce((min, l) => l.rate < min.rate ? l : min);
      const lowestPayment = comparison.reduce((min, l) => l.monthlyPayment < min.monthlyPayment ? l : min);
      const highestProbability = comparison.find(l => l.probability === 'alta') || comparison[0];
  
      return {
        content: [{
          type: 'text' as const,
          text: JSON.stringify({
            comparison,
            recommendations: {
              lowestRate: { id: lowestRate.id, name: lowestRate.name, rate: lowestRate.rate },
              lowestPayment: { id: lowestPayment.id, name: lowestPayment.name, payment: lowestPayment.monthlyPayment },
              highestApproval: { id: highestProbability.id, name: highestProbability.name, probability: highestProbability.probability }
            }
          }, null, 2)
        }]
      };
    }
  );

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

  Top-level registration invocation within registerAllTools that calls registerLoanTools(server), thereby registering the compare-loans tool.

  registerLoanTools(server);

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

  Helper function to fetch and return the list of available loans from the API, used by the compare-loans handler.

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