Aave Liquidation MCP Server

Instructions

Implementation Reference

• src/index.ts:81-95 (registration)

  Registration of the 'get_user_positions' tool in the MCP server's listTools handler, including name, description, and input schema.

  {
    name: 'get_user_positions',
    description:
      'Get detailed breakdown of a user collateral and debt positions across all Aave V3 assets.',
    inputSchema: {
      type: 'object',
      properties: {
        address: {
          type: 'string',
          description: 'Ethereum address to query',
        },
      },
      required: ['address'],
    },
  },

• src/index.ts:275-309 (handler)

  MCP server handler for 'get_user_positions' tool: validates input, calls AaveClient.getUserReserves, and formats response as JSON.

  case 'get_user_positions': {
    const address = args?.address as string;
    if (!address || typeof address !== 'string') {
      throw new McpError(
        ErrorCode.InvalidParams,
        'address parameter is required and must be a string'
      );
    }
  
    if (!aaveClient.isValidAddress(address)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid Ethereum address format'
      );
    }
  
    const positions = await aaveClient.getUserReserves(address);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              address,
              collateralPositions: positions.collateral,
              debtPositions: positions.debt,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/aave-client.ts:82-129 (handler)

  Core implementation of get_user_positions: fetches all reserves, queries user reserve data in parallel, categorizes into collateral and debt positions with formatted values.

  async getUserReserves(userAddress: string): Promise<{
    collateral: UserReserveData[];
    debt: UserReserveData[];
  }> {
    const reserves = await this.getAllReserves();
    const collateral: UserReserveData[] = [];
    const debt: UserReserveData[] = [];
  
    // Parallel query all user reserves
    const userReservePromises = reserves.map(reserve =>
      this.dataProviderContract.getUserReserveData(reserve.tokenAddress, userAddress)
    );
    const userReservesData = await Promise.all(userReservePromises);
  
    // Process results
    for (let i = 0; i < reserves.length; i++) {
      const reserve = reserves[i];
      const userReserve = userReservesData[i];
      const totalDebt = userReserve.currentStableDebt + userReserve.currentVariableDebt;
  
      if (userReserve.currentATokenBalance > 0n || totalDebt > 0n) {
        // Use cached decimals from reserves
        const decimals = reserve.decimals;
  
        const data: UserReserveData = {
          asset: reserve.tokenAddress,
          symbol: reserve.symbol,
          currentATokenBalance: userReserve.currentATokenBalance,
          currentStableDebt: userReserve.currentStableDebt,
          currentVariableDebt: userReserve.currentVariableDebt,
          usageAsCollateralEnabled: userReserve.usageAsCollateralEnabled,
          decimals,
          balanceFormatted: ethers.formatUnits(userReserve.currentATokenBalance, decimals),
          debtFormatted: ethers.formatUnits(totalDebt, decimals),
          liquidationBonus: reserve.liquidationBonus,
        };
  
        if (userReserve.currentATokenBalance > 0n) {
          collateral.push(data);
        }
        if (totalDebt > 0n) {
          debt.push(data);
        }
      }
    }
  
    return { collateral, debt };
  }