NEAR MCP

Instructions

Implementation Reference

• src/services.ts:803-855 (handler)

  Handler function that searches for fungible tokens using searchFungibleTokens helper, enriches results with contract info from getFungibleTokenContractInfo, and returns formatted content.
  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/services.ts:775-802 (schema)

  Zod input schema defining parameters for searching fungible tokens: optional search terms for account ID, symbol, name, and max results.
  { 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.', ), },
• src/services.ts:770-856 (registration)

  MCP tool registration call including name, description, input schema, and handler function.
  '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)

  Helper function that fetches token list from Ref Finance API and filters by account ID, symbol, or name using regex, limiting results.
  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/utils.ts:341-379 (helper)

  Supporting helper that fetches additional fungible token contract details from NearBlocks API.
  export const getFungibleTokenContractInfo = async ( contractId: string, ): Promise<Result<object, Error>> => { try { const url = `https://api.nearblocks.io/v1/fts/${contractId}`; const response = await fetch(url); const data = (await response.json()) as { contracts?: { contract: string; name: string; symbol: string; decimals: number; description: string; website: string; }[]; }; const contracts = data?.contracts; if (!contracts) { return { ok: false, error: new Error('No fungible token contracts found'), }; } const contractInfo = contracts.map((contract) => ({ contract: contract.contract, name: contract.name, symbol: contract.symbol, decimals: contract.decimals, description: contract.description, website: contract.website, })); return { ok: true, value: contractInfo, }; } catch (error) { return { ok: false, error: error as Error }; } };