search_near_fungible_tokens

Instructions

Implementation Reference

• src/services.ts:770-856 (handler)

  Registration and handler for the 'search_near_fungible_tokens' MCP tool. Defined via mcp.tool() with schema for accountIDSearchTerm, symbolSearchTerm, nameSearchTerm, and maxNumberOfResults. The handler calls searchFungibleTokens() then enriches results with getFungibleTokenContractInfo().

    'search_near_fungible_tokens',
    noLeadingWhitespace`
    Search for fungible token contract information for the NEAR blockchain, based on search terms.
    This tool works by 'grepping' through a list of contract information JSON objects. Be careful
    with this tool, it can return a lot of results. Ensure that your query is specific.`,
    {
      accountIDSearchTerm: z
        .string()
        .optional()
        .describe(
          'The grep-like search term to use for finding fungible token contract information by account ID.',
        ),
      symbolSearchTerm: z
        .string()
        .optional()
        .describe(
          'The grep-like search term to use for finding fungible token contract information by symbol.',
        ),
      nameSearchTerm: z
        .string()
        .optional()
        .describe(
          'The grep-like search term to use for finding fungible token contract information by name.',
        ),
      maxNumberOfResults: z
        .number()
        .min(1)
        .max(8)
        .default(4)
        .describe(
          'The maximum number of results to return. This is a limit to the number of results returned by the API. Keep this number low to avoid overwhelming the API.',
        ),
    },
    async (args, __) => {
      const tokenContractsSearchResult = await searchFungibleTokens(
        args.accountIDSearchTerm,
        args.symbolSearchTerm,
        args.nameSearchTerm,
        args.maxNumberOfResults,
      );
      if (!tokenContractsSearchResult.ok) {
        return {
          content: [
            {
              type: 'text',
              text: `Error: ${tokenContractsSearchResult.error}`,
            },
          ],
        };
      }
      const tokenContracts = tokenContractsSearchResult.value;
  
      // get the contract info for each contract
      const contractInfoResults = await mapSemaphore(
        tokenContracts,
        4,
        async (
          contract,
        ): Promise<[string, FungibleTokenContract, Result<object, Error>]> => {
          return [
            contract.contract,
            contract,
            await getFungibleTokenContractInfo(contract.contract),
          ];
        },
      );
  
      const contractInfos = contractInfoResults.map(
        ([_, contract, contractInfoResult]) => {
          if (contractInfoResult.ok) {
            return contractInfoResult.value;
          } else {
            return contract;
          }
        },
      );
  
      return {
        content: [
          {
            type: 'text',
            text: stringify_bigint(contractInfos),
          },
        ],
      };
    },
  );

• src/utils.ts:262-339 (helper)

  The searchFungibleTokens helper function that fetches token list from https://api.ref.finance/list-token, filters by accountID, symbol, and name using case-insensitive regex, and returns up to maxNumberOfResults matching FungibleTokenContract entries.

  export const searchFungibleTokens = async (
    accountIDSearchTerm: string | undefined,
    symbolSearchTerm: string | undefined,
    nameSearchTerm: string | undefined,
    maxNumberOfResults: number,
  ): Promise<Result<FungibleTokenContract[], Error>> => {
    try {
      const url = 'https://api.ref.finance/list-token';
      const response = await fetch(url);
      const data = (await response.json()) as Record<
        string,
        {
          spec: string;
          name: string;
          symbol: string;
          icon: string;
          reference: string;
          reference_hash: string;
          decimals: number;
        }
      >;
      if (!Object.keys(data).length) {
        return {
          ok: false,
          error: new Error('No tokens found'),
        };
      }
  
      // Filter tokens based on search term
      const filteredTokens = Object.entries(data)
        .filter(([contractId, tokenInfo]) => {
          // filter by account ID
          if (
            accountIDSearchTerm &&
            !new RegExp(accountIDSearchTerm, 'i').test(contractId)
          ) {
            return false;
          }
  
          // filter by symbol
          if (
            symbolSearchTerm &&
            !new RegExp(symbolSearchTerm, 'i').test(tokenInfo.symbol)
          ) {
            return false;
          }
  
          // filter by name
          if (
            nameSearchTerm &&
            !new RegExp(nameSearchTerm, 'i').test(tokenInfo.name)
          ) {
            return false;
          }
  
          return true;
        })
        .slice(0, maxNumberOfResults)
        .map(([contractId, tokenInfo]) => ({
          contract: contractId,
          ...tokenInfo,
        }));
  
      if (filteredTokens.length === 0) {
        return {
          ok: false,
          error: new Error('No matching tokens found'),
        };
      }
  
      return {
        ok: true,
        value: filteredTokens,
      };
    } catch (error) {
      return { ok: false, error: error as Error };
    }
  };

• src/services.ts:776-802 (schema)

  Zod schema for the tool's input parameters: optional accountIDSearchTerm, symbolSearchTerm, nameSearchTerm strings, and maxNumberOfResults number (min 1, max 8, default 4).

    accountIDSearchTerm: z
      .string()
      .optional()
      .describe(
        'The grep-like search term to use for finding fungible token contract information by account ID.',
      ),
    symbolSearchTerm: z
      .string()
      .optional()
      .describe(
        'The grep-like search term to use for finding fungible token contract information by symbol.',
      ),
    nameSearchTerm: z
      .string()
      .optional()
      .describe(
        'The grep-like search term to use for finding fungible token contract information by name.',
      ),
    maxNumberOfResults: z
      .number()
      .min(1)
      .max(8)
      .default(4)
      .describe(
        'The maximum number of results to return. This is a limit to the number of results returned by the API. Keep this number low to avoid overwhelming the API.',
      ),
  },