MIST.cash MCP Server

Instructions

Implementation Reference

• src/tools/obtener-assets.ts:11-49 (handler)

  The core handler function that validates input using Zod schema, sets up Starknet provider and Chamber contract, fetches transaction assets via Mistcash SDK with retry logic and 30s timeout, returns assets with spending warning.

  export async function obtenerAssetsTransaccion(params: unknown) {
      // Validate parameters
      const validated = ObtenerAssetsTransaccionSchema.parse(params);
  
      try {
          // Create provider
          const provider = createProvider(
              validated.provider_rpc_url ? { nodeUrl: validated.provider_rpc_url } : undefined
          );
  
          // Get contract address (supports custom Madara address)
          const network = (process.env.STARKNET_NETWORK || 'mainnet') as 'mainnet' | 'sepolia';
          const contractAddress = getContractAddress(network);
  
          // Get contract instance
          const contract = await getChamberContract(provider, contractAddress, CHAMBER_ABI);
  
          // Fetch transaction assets with retry logic and 30s timeout
          const assetsPromise = retryWithBackoff(
              () => fetchTxAssets(contract, validated.transaction_key, validated.recipient_address)
          );
  
          const timeoutPromise = new Promise((_, reject) =>
              setTimeout(() => reject(new Error('Request timeout after 30s')), 30000)
          );
  
          const assets = await Promise.race([assetsPromise, timeoutPromise]) as TransactionAssets;
  
          return {
              success: true,
              assets,
              warning: '⚠️ This function shows assets even if they have already been spent. Use verificar_existencia_transaccion for accurate verification.',
              transaction_key: validated.transaction_key,
              recipient_address: validated.recipient_address
          };
      } catch (error) {
          throw new Error(`Failed to fetch transaction assets: ${(error as Error).message}`);
      }
  }

• src/utils/validation.ts:20-24 (schema)

  Zod runtime validation schema for tool inputs: requires transaction_key (non-empty string), recipient_address (valid Starknet address), optional provider_rpc_url (valid URL).

  export const ObtenerAssetsTransaccionSchema = z.object({
      transaction_key: z.string().min(1, 'Transaction key is required'),
      recipient_address: StarknetAddressSchema,
      provider_rpc_url: z.string().url().optional()
  });

• src/index.ts:63-84 (registration)

  MCP tool registration in listTools handler: defines name, description, and static JSON schema for input validation, mirroring the Zod schema.

  {
      name: 'obtener_assets_transaccion',
      description: 'Fetch assets from a transaction. WARNING: This shows assets even if already spent. Use verificar_existencia_transaccion for accurate verification.',
      inputSchema: {
          type: 'object',
          properties: {
              transaction_key: {
                  type: 'string',
                  description: 'Transaction key to query',
              },
              recipient_address: {
                  type: 'string',
                  description: 'Starknet address of the recipient',
              },
              provider_rpc_url: {
                  type: 'string',
                  description: 'Optional custom Starknet RPC URL',
              },
          },
          required: ['transaction_key', 'recipient_address'],
      },
  },