ValueRouter MCP Server

Instructions

Implementation Reference

• src/index.ts:265-290 (registration)

  Registration of the 'get_user_balance' tool including name, description, and input schema definition.

  {
    name: 'get_user_balance',
    description: 'Get user token balance on a specific chain',
    inputSchema: {
      type: 'object',
      properties: {
        chainId: {
          oneOf: [
            { type: 'number' },
            { type: 'string' },
          ],
          description: 'Chain ID to check balance on',
        },
        tokenAddress: {
          type: 'string',
          description: 'Token contract address',
        },
        userAddress: {
          type: 'string',
          description: 'User address to check balance for',
        },
      },
      required: ['chainId', 'tokenAddress', 'userAddress'],
      additionalProperties: false,
    },
  },

• src/types/index.ts:182-188 (schema)

  Zod input schema (BalanceQuerySchema) used for validating get_user_balance tool arguments.

  export const BalanceQuerySchema = z.object({
    chainId: z.union([z.number(), z.string()]),
    tokenAddress: z.string(),
    userAddress: z.string(),
  });
  
  export type BalanceQuery = z.infer<typeof BalanceQuerySchema>;

• src/index.ts:447-458 (handler)

  Main tool handler 'getUserBalance' that parses input schema and calls BalanceService for execution.

  private async getUserBalance(args: any): Promise<MCPToolResult> {
    try {
      const request = BalanceQuerySchema.parse(args);
      const result = await this.balanceService.getBalance(request);
      return createSuccessResponse(result);
    } catch (error) {
      return createErrorResponse(
        error instanceof Error ? error.message : String(error),
        'BALANCE_ERROR'
      );
    }
  }

• src/services/balance.ts:55-74 (handler)

  Core balance fetching logic in BalanceService.getBalance, dispatching to chain-specific balance retrievers.

  async getBalance(query: BalanceQuery): Promise<BalanceResponse> {
    const { chainId, tokenAddress, userAddress } = query;
    const chainIdTyped = chainId as SupportedChainId;
  
    try {
      if (isEVMChain(chainIdTyped)) {
        return await this.getEVMBalance(chainIdTyped, tokenAddress, userAddress);
      } else if (isSolanaChain(chainIdTyped)) {
        return await this.getSolanaBalance(chainIdTyped, tokenAddress, userAddress);
      } else if (isSuiChain(chainIdTyped)) {
        return await this.getSuiBalance(chainIdTyped, tokenAddress, userAddress);
      } else if (isCosmosChain(chainIdTyped)) {
        return await this.getCosmosBalance(chainIdTyped, tokenAddress, userAddress);
      } else {
        throw new Error(`Unsupported chain: ${chainId}`);
      }
    } catch (error) {
      throw new Error(`Failed to get balance: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/types/index.ts:191-200 (schema)

  Zod output schema (BalanceResponseSchema) defining the structure of balance query results.

  export const BalanceResponseSchema = z.object({
    chainId: z.union([z.number(), z.string()]),
    tokenAddress: z.string(),
    balance: z.string(),
    decimals: z.number(),
    symbol: z.string(),
    formattedBalance: z.string(),
  });
  
  export type BalanceResponse = z.infer<typeof BalanceResponseSchema>;